VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Pedidos

Remessas e rastreio

Cria, lista e atualiza as remessas de um pedido, com transportadora, código de rastreio e itens enviados em cada uma.

Uma remessa (envio) é um pacote que saiu da loja: ela diz quais itens, em que quantidade, por qual transportadora e com qual código de rastreio. Um pedido pode ter várias remessas (envio parcial: três itens saem hoje, dois amanhã), e a plataforma controla quanto de cada item ainda falta enviar.

Quando você grava o código de rastreio, o cliente recebe o e-mail de envio com o código e o link da transportadora, e a remessa passa para "enviada".

Pontos-chave
  • A remessa é do pedido que você informa na URL. Em compras divididas por seller (Sub-pedidos), crie a remessa no sub-pedido do seller: os order_item_id são as linhas dele.
  • Criar uma remessa não muda o status do pedido. Depois de despachar, mude o pedido para "enviado" com Alterar o status.
  • Na resposta, o status da remessa vem como letra; na requisição você manda o nome por extenso (veja a tabela).

Status de uma remessa

Nome (requisição)Letra (resposta)Significado
pendingNCriada, ainda sem despacho (sem código de rastreio).
shippedADespachada. É o status que a remessa recebe ao ser criada com código de rastreio.
in_transitPEm trânsito.
out_for_deliveryWSaiu para entrega.
awaiting_pickupHAguardando retirada.
deliveredCEntregue.
delivery_failedFTentativa de entrega falhou.
returnedDDevolvida; os itens voltam a contar como "a enviar".
lostLExtraviada.
canceledICancelada.
GET/api/v1/admin/orders/{id}/shipmentsAdmin

Lista as remessas de um pedido

Lista as remessas do pedido, com os itens de cada uma. Exige view_orders ou manage_orders.

Path parameters

iduuidobrigatório
Id do pedido (ou do sub-pedido).
POST/api/v1/admin/orders/{id}/shipmentsAdmin

Cria uma remessa

Cria uma remessa com os itens e as quantidades informadas. A plataforma confere que os itens são do pedido e que não se envia mais do que o pedido tem (descontadas as remessas anteriores que não foram devolvidas). Exige manage_orders.

Com tracking_code, a remessa nasce como enviada (A), registra shipped_at e o cliente recebe o e-mail de rastreio. Sem o código, nasce pendente (N); informe o código depois com a rota de atualização. mark_shipped despacha mesmo sem código.

Path parameters

iduuidobrigatório
Id do pedido (ou do sub-pedido) dono dos itens.

Corpo da requisição

itemsarrayobrigatório

Itens da remessa. Pelo menos um.

order_item_iduuidobrigatório
Id da linha do pedido (items[].id em Consultar pedido).
quantity_shippedintegerobrigatório
Quantidade enviada nesta remessa. Mínimo 1, e não maior que a quantidade ainda não enviada da linha.
carrierstring
Nome da transportadora (Correios, Jadlog...).
tracking_codestring
Código de rastreio. Ao informar, a remessa é despachada.
notesstring
Observação interna da remessa.
tracking_urlstring
Link de rastreio da transportadora. Só http ou https, até 2048 caracteres. Aparece no acompanhamento do pedido.
estimated_delivery_atstring
Previsão de entrega: AAAA-MM-DD (meia-noite no fuso de Brasília) ou RFC 3339.
public_notestring
Texto que o cliente vê na linha do tempo da remessa (até 1000 caracteres). notes continua interna.
mark_shippedboolean
true despacha a remessa mesmo sem código de rastreio.
PUT/api/v1/admin/orders/{id}/shipments/{shipmentId}Admin

Atualiza uma remessa

Atualiza transportadora, código, status e observação de uma remessa existente. Só os campos enviados mudam. Exige manage_orders. Se você informar um tracking_code, o cliente recebe o e-mail de envio com o código (é o único aviso, pois esta rota não emite outro evento).

Mudar o status para shipped, in_transit ou delivered preenche shipped_at; delivered também preenche delivered_at. Atualizar a remessa não muda o status do pedido.

Estes campos não podem ser alterados aqui e causam 400 immutable_field: items (cancele a remessa e crie outra), mark_shipped, e tracking_url, estimated_delivery_at e public_note (use a rota de rastreio abaixo).

Path parameters

iduuidobrigatório
Id do pedido.
shipmentIduuidobrigatório
Id da remessa.

Corpo da requisição

tracking_codestring
Código de rastreio.
carrierstring
Transportadora.
statusstring
pendingshippedin_transitout_for_deliveryawaiting_pickupdelivereddelivery_failedreturnedlostcanceled
Status da remessa, por extenso.
notesstring
Observação interna.
PUT/api/v1/admin/orders/{id}/shipments/{shipmentId}/trackingAdmin

Atualiza os dados de rastreio de uma remessa

Grava os dados de rastreio exibidos ao cliente (link, previsão e texto público) e registra a atualização na linha do tempo do pedido, sem mudar o status. Existe quando a loja ativa o recurso de acompanhamento de pedidos (fluxo de status); sem ele responde 403 module_disabled. Exige manage_orders. Envie ao menos um campo.

Path parameters

iduuidobrigatório
Id do pedido.
shipmentIduuidobrigatório
Id da remessa. Precisa pertencer ao pedido da URL.

Corpo da requisição

carrierstring
Transportadora (até 120 caracteres).
tracking_codestring
Código de rastreio (até 120 caracteres). Código novo dispara o e-mail ao cliente.
tracking_urlstring
Link de rastreio (http/https, até 2048 caracteres).
estimated_delivery_atstring
Previsão de entrega, AAAA-MM-DD ou RFC 3339. Vazio limpa a previsão.
public_notestring
Texto público da remessa (até 1000 caracteres).

Exemplo de requisição

bash
# Criar a remessa já com rastreio
curl -X POST "$BASE_URL/api/v1/admin/orders/$ORDER_ID/shipments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "Correios",
    "tracking_code": "BR123456789BR",
    "notes": "Caixa 1 de 2",
    "items": [{ "order_item_id": "9787424c-0fca-44a9-9c96-9bba0c1f4704", "quantity_shipped": 1 }]
  }'

# Marcar como entregue depois
curl -X PUT "$BASE_URL/api/v1/admin/orders/$ORDER_ID/shipments/$SHIPMENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"delivered"}'

Resposta

201Remessa criada
json
{
  "id": "45171534-2fbd-46ca-973a-132149a564da",
  "order_id": "2b4bd680-b717-4295-a2be-8b5c6771a4d0",
  "tracking_code": "BR123456789BR",
  "carrier": "Correios",
  "status": "A",
  "notes": "Caixa 1 de 2",
  "shipped_at": "2026-10-11T20:16:39.661262Z",
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T20:16:39.661262Z",
  "updated_at": "2026-10-11T20:16:39.661262Z",
  "items": [
    {
      "id": "e28a4232-aade-47e5-83e1-2ecda9da3927",
      "shipment_id": "45171534-2fbd-46ca-973a-132149a564da",
      "order_item_id": "9787424c-0fca-44a9-9c96-9bba0c1f4704",
      "quantity_shipped": 1,
      "product_name": "Notebook Vintage Vermelho",
      "product_sku": "SD-004018-C"
    }
  ]
}
200Lista de remessas
json
{
  "order_id": "2b4bd680-b717-4295-a2be-8b5c6771a4d0",
  "count": 1,
  "shipments": [
    { "id": "45171534-2fbd-46ca-973a-132149a564da", "tracking_code": "BR123456789BR", "carrier": "Correios", "status": "A", "items": [] }
  ]
}
200Rastreio atualizado
json
{
  "id": "45171534-2fbd-46ca-973a-132149a564da",
  "carrier": "Correios",
  "tracking_code": "BR123456789BR",
  "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objeto=BR123456789BR",
  "estimated_delivery_at": "2026-10-20T03:00:00Z",
  "public_note": "Saiu do centro de distribuição",
  "shipped_at": "2026-10-11T20:16:39.661262Z",
  "created_at": "2026-10-11T20:16:39.661262Z",
  "updated_at": "2026-10-11T21:02:10.114Z"
}

Campos da resposta (remessa)

iduuid
Id da remessa.
order_iduuid
Pedido dono da remessa.
tracking_codestring
Código de rastreio. Ausente se ainda não foi informado.
carrierstring
Transportadora.
statusstring
Letra do status (tabela acima).
notesstring
Observação interna.
shipped_atstring
Quando foi despachada. RFC 3339.
delivered_atstring
Quando foi entregue. RFC 3339.
created_byuuid
Usuário que criou a remessa.
itemsarray
Itens da remessa: order_item_id, quantity_shipped, product_name, product_sku e product_image.
countinteger
(Lista) Quantidade de remessas.
tracking_urlstring
(Rota de rastreio) Link de rastreio.
estimated_delivery_atstring
(Rota de rastreio) Previsão de entrega, RFC 3339 em UTC.
public_notestring
(Rota de rastreio) Texto público.

Erros

StatusQuandoCorpo
400Corpo inválido; items vazio; order_item_id ou quantity_shipped faltando{"error":"at least one item is required"}, {"error":"order_item_id is required for each item"}, {"error":"quantity_shipped must be at least 1"}
400status de remessa inválido{"error":"invalid shipment status: bogus"}
400Campo que não pode ser alterado nesta rota{"error":"immutable_field","detail":"o campo \"tracking_url\" não pode ser alterado por este endpoint: ... use PUT /api/v1/admin/orders/{id}/shipments/{shipmentId}/tracking ..."}
401Sem credenciais ou token expirado{"error":"invalid or expired token"}
403Sem manage_orders; ou recurso de acompanhamento desligado (rota de rastreio){"error":"insufficient privileges","required":"manage_orders"} ou {"error":"module_disabled","module":"order-status-flow"}
404Pedido, item ou remessa não encontrados{"error":"order not found: ..."}, {"error":"order item not found: ..."}, {"error":"shipment not found"}
422Quantidade maior que a pendente, ou item de outro pedido{"error":"cannot ship 1 of item 9787424c-...: only 0 remaining unshipped (total: 1, already shipped: 1)"}
422Dados de rastreio inválidos{"error":"validation_failed","issues":[{"field":"tracking_url","code":"invalid"}]}, com field entre tracking_url, estimated_delivery_at, tracking e code entre invalid, too_long, nothing_to_update
500Falha interna{"error":"failed to create shipment","detail":"..."}
Remessa não é mudança de status

É comum esquecer o segundo passo: criar a remessa com rastreio não move o pedido para "enviado". O cliente recebe o e-mail com o código, mas o pedido continua em "processando" nas telas e relatórios até você chamar Alterar o status. Faça as duas chamadas, nessa ordem.

Envio parcial

Um item com quantity 5 pode sair em duas remessas (3 e 2). Se você tentar enviar 4 depois de ter enviado 3, a resposta é 422 informando quantas faltam. Só uma remessa marcada como returned (devolvida) libera a quantidade de volta para novo envio.

Veja também

  • Rastreio da transportadora
  • Romaneio (packing slip)
  • Alterar o status
Anterior
Sub-pedidos
Próxima
Rastreio da transportadora
Nesta página
  • Status de uma remessa
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também