Expedições (Shipments)

Endpoints de /api2/shipment para registrar a expedição do pedido com rastreio único ou em lote, listar shipments existentes, consultar individualmente, adicionar tracks a shipments já criados e reenviar e-mails ao cliente.

REST JSON Bearer Token Novo em 2026

Visão geral

O recurso de shipments cobre todo o registro logístico: criação da expedição (total ou parcial), inclusão de tracks (rastreio único ou múltiplos volumes), reenvio de e-mail e listagem para reconciliação com transportadoras. Para regras gerais (paginação, datas, status HTTP, tratamento de items), consulte a página principal de Pedidos.

Modos de rastreiotrack_number único ou tracks[] em lote.

Resoluçãoshipment_id, order_id ou order_increment_id.

Aliases reconhecidosshipment, shipments, shippment, shippments.

opt

Itens parciaisorder_item_id ou sku + qty.

GET/api2/shipment

Listar shipments.

ListagemFiltros

page, limit, include_pagination Opcional

Paginação padrão.

order_id Opcional

ID interno do pedido.

order_increment_id Opcional

Número incremental do pedido.

increment_id Opcional

Número incremental do shipment. Valor único retorna o shipment detalhado.

created_from, created_to Opcional

Intervalo de criação.

sort, direction Opcional

Campos aceitos: entity_id, created_at, updated_at, increment_id.

Exemplos

GET /api2/shipment?page=1&limit=50&include_pagination=1
Authorization: Bearer {{token}}

GET /api2/shipment?order_id=123
Authorization: Bearer {{token}}

{
  "page": 1,
  "limit": 50,
  "include_pagination": 1,
  "order_increment_id": "100000123",
  "created_from": "2026-01-01",
  "created_to": "2026-12-31"
}

Resposta de listagem usa shipments. Busca por ID ou increment_id único usa shipment. Aliases reconhecidos: /api2/shipments, /api2/shippment, /api2/shippments. A rota canônica recomendada é /api2/shipment.

GET/api2/shipment

Obter shipment individual.

GET /api2/shipment?id=789
Authorization: Bearer {{token}}

GET /api2/shipment?increment_id=100000078
Authorization: Bearer {{token}}

POST/api2/shipment/create

Criar shipment (expedição) total ou parcial. O payload pode incluir rastreio inicial por track_number (objeto único) ou por tracks (lista).

ExpediçãoRastreio

order_id / order_increment_id

Identificação do pedido. Use exatamente um dos dois.

items Opcional

Lista de itens a expedir. Se omitido, expede todas as quantidades disponíveis.

send_email Opcional

Quando true, envia o e-mail do shipment após salvar.

comment Opcional

Comentário registrado no shipment.

carrier_code, title, track_number Opcional

Rastreio único enviado direto no payload.

tracks Opcional

Lista de rastreios; cada entrada com carrier_code, title e track_number.

Expedição total com rastreio único

POST /api2/shipment/create
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_increment_id": "100000123",
  "send_email": true,
  "comment": "Shipment criado pela integração.",
  "carrier_code": "custom",
  "title": "Transportadora",
  "track_number": "BR123456789"
}

Expedição parcial com lista de rastreios

POST /api2/shipment/create
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_id": 123,
  "items": [
    {"order_item_id": 10, "qty": 1},
    {"sku": "PRODUTO-001", "qty": 2}
  ],
  "tracks": [
    {
      "carrier_code": "custom",
      "title": "Transportadora",
      "track_number": "BR123456789"
    }
  ]
}

POST/api2/shipment/track

Cria rastreio em um shipment já existente. Não cria o shipment do pedido. Pode receber o shipment_id direto ou resolver pelo pedido quando existir um único shipment.

Por `shipment_id`

POST /api2/shipment/track
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "shipment_id": 789,
  "carrier_code": "custom",
  "title": "Transportadora",
  "track_number": "BR123456789"
}

Por `order_increment_id`

POST /api2/shipment/track
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_increment_id": "100000123",
  "carrier_code": "custom",
  "title": "Transportadora",
  "track_number": "BR123456789"
}

Por `order_id`

POST /api2/shipment/track
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_id": 123,
  "carrier_code": "custom",
  "title": "Transportadora",
  "track_number": "BR123456789"
}

Se o pedido tiver mais de um shipment, informe shipment_id ou increment_id do shipment para evitar ambiguidade. Compatibilidade: POST /api2/shipment também cria rastreio.

POST/api2/shipment/email

Reenviar e-mail do shipment. Identifique-o com shipment_id, id ou increment_id.

POST /api2/shipment/email
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "shipment_id": 789,
  "comment": "Reenvio solicitado pela integração."
}

Formas de uso suportadas

Combinações testadas e homologadas para o recurso Shipments.

Listar shipments do diaGET /api2/shipment?created_from=2026-05-07&include_pagination=1

Shipments de um pedidoGET /api2/shipment?order_increment_id=100000123

Expedição total com rastreio únicoPOST /api2/shipment/create + carrier_code + track_number

Expedição com múltiplos volumesPOST /api2/shipment/create + tracks[]

Adicionar rastreio em shipment existentePOST /api2/shipment/track + shipment_id

Reenviar e-mailPOST /api2/shipment/email

Recomendações para integração

Evitar

Depender dos aliases /api2/shippment ou /api2/shippments em código novo.
Confiar que send_email=true sozinho substitua o reenvio explícito via /api2/shipment/email em casos de falha de SMTP.
Misturar order_id e order_increment_id no mesmo payload.

Pedidos com múltiplos shipments

Quando um pedido tem mais de um shipment, o endpoint /api2/shipment/track retorna 400 Ambiguous shipment for order ao receber apenas order_id. Capture o shipment_id da listagem e envie-o explicitamente.

Erros comuns

Status	Exemplo de body	Quando ocorre
`400`	`{"error": "Invalid item"}`	Item de `items` sem `order_item_id`/`sku` ou com `qty` não positivo.
`400`	`{"error": "Cannot create shipment"}`	O pedido não admite mais expedição (ex.: já totalmente expedido ou cancelado).
`400`	`{"error": "Ambiguous shipment for order"}`	`POST /api2/shipment/track` resolvido por pedido com múltiplos shipments — informe `shipment_id`.
`401`	`{"error": "Unauthorized"}`	`Authorization` ausente ou token expirado.
`404`	`{"error": "Order not found"}`	`order_id` ou `order_increment_id` inexistente.
`404`	`{"error": "Shipment not found"}`	`shipment_id` ou `increment_id` inexistente.
`409`	`{"error": "Conflict on save"}`	Duplicidade ou deadlock em gravação concorrente.

Expedições (Shipments)

Visão geral

Exemplos

Expedição total com rastreio único

Expedição parcial com lista de rastreios

Por shipment_id

Por order_increment_id

Por order_id

Formas de uso suportadas

Recomendações para integração

Recomendado

Evitar

Pedidos com múltiplos shipments

Erros comuns

Por `shipment_id`

Por `order_increment_id`

Por `order_id`