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

Remessas e rastreio

Lista e cria as remessas do pedido do seller, com transportadora, código de rastreio e itens, e atualiza o rastreio mostrado ao cliente.

Uma remessa (envio) é um pacote que saiu do seller: 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 a remessa nasce com código de rastreio, ela passa a "enviada" e o cliente recebe um e-mail de envio com o código e o link da transportadora.

Remessa não é mudança de status

Criar a remessa não move o pedido para "enviado". O cliente recebe o e-mail, mas o pedido continua em "processando" até você chamar Mudar o status com shipped. Faça as duas chamadas, nessa ordem.

Status de uma remessa

NomeLetra (resposta)Significado
pendingNCriada, ainda sem despacho (sem código de rastreio).
shippedADespachada. É o status de uma remessa 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.

Listar as remessas

GET/api/v1/vendor/orders/{id}/shipmentsSeller

Lista as remessas de um pedido do seller

Parâmetros de caminho

iduuidobrigatório
Id do sub-pedido do seller.

Resposta: listar

200Remessas do pedido
json
{
  "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
  "count": 1,
  "shipments": [
    {
      "id": "45171534-2fbd-46ca-973a-132149a564da",
      "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
      "tracking_code": "BR123456789BR",
      "carrier": "Correios",
      "status": "A",
      "shipped_at": "2026-10-11T20:16:39.661262Z",
      "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": "020ead81-da4e-4b70-b80b-88562ba9497a",
          "quantity_shipped": 2,
          "product_name": "Camiseta Algodão Azul",
          "product_sku": "CAM-AZ-M"
        }
      ]
    }
  ]
}

Campos da resposta

order_iduuid
Pedido consultado.
countinteger
Quantidade de remessas.
shipmentsarray
Remessas. Lista vazia ([]) quando ainda não há.
shipments[].iduuid
Id da remessa (use-o como shipmentId na atualização do rastreio).
shipments[].tracking_codestring
Código de rastreio. Ausente se ainda não foi informado.
shipments[].carrierstring
Transportadora.
shipments[].statusstring
Letra do status (tabela acima).
shipments[].notesstring
Observação interna.
shipments[].shipped_atstring (RFC 3339)
Quando foi despachada.
shipments[].delivered_atstring (RFC 3339)
Quando foi entregue.
shipments[].itemsarray
Itens da remessa: order_item_id, quantity_shipped, product_name, product_sku, product_image.

Criar uma remessa

POST/api/v1/vendor/orders/{id}/shipmentsSeller

Cria uma remessa para um pedido do seller

Cria uma remessa com os itens e as quantidades informados. A plataforma confere que os itens são do pedido e que você não envia mais do que o pedido tem (descontadas as remessas anteriores que não foram devolvidas). Com tracking_code, a remessa nasce enviada (A), registra shipped_at e o cliente recebe o e-mail. Sem o código, nasce pendente (N); informe o código depois. mark_shipped despacha mesmo sem código.

Parâmetros de caminho

iduuidobrigatório
Id do sub-pedido do seller.

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 pedidos).
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.
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.

Exemplo de requisição: criar

bash
curl -X POST "$BASE_URL/api/v1/vendor/orders/e148b6aa-d495-4b89-92ab-f38b5979a43f/shipments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "Correios",
    "tracking_code": "BR123456789BR",
    "items": [{ "order_item_id": "020ead81-da4e-4b70-b80b-88562ba9497a", "quantity_shipped": 2 }]
  }'

Resposta: criar

201Remessa criada
json
{
  "id": "45171534-2fbd-46ca-973a-132149a564da",
  "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
  "tracking_code": "BR123456789BR",
  "carrier": "Correios",
  "status": "A",
  "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": "020ead81-da4e-4b70-b80b-88562ba9497a",
      "quantity_shipped": 2,
      "product_name": "Camiseta Algodão Azul",
      "product_sku": "CAM-AZ-M"
    }
  ]
}

Os campos são os de cada item de shipments na listagem, mais created_by (o usuário que criou).

Atualizar o rastreio

PUT/api/v1/vendor/orders/{id}/shipments/{shipmentId}/trackingSeller

Atualiza o rastreio de uma remessa

Grava os dados de rastreio que o cliente vê (link, previsão, texto público) e registra a atualização na linha do tempo do pedido, sem mudar o status. Funciona quando a loja liga o módulo order-status-flow (acompanhamento de pedidos); sem ele a resposta é 403 module_disabled. Envie ao menos um campo. Um código de rastreio novo dispara o e-mail de envio ao cliente.

Parâmetros de caminho

iduuidobrigatório
Id do sub-pedido do seller.
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).
tracking_urlstring
Link de rastreio (http ou 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: atualizar o rastreio

bash
curl -X PUT "$BASE_URL/api/v1/vendor/orders/$ORDER_ID/shipments/$SHIPMENT_ID/tracking" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objeto=BR123456789BR",
    "estimated_delivery_at": "2026-10-20",
    "public_note": "Saiu do centro de distribuição"
  }'

Resposta: atualizar o rastreio

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

iduuid
Id da remessa.
carrierstring
Transportadora.
tracking_codestring
Código de rastreio.
tracking_urlstring
Link de rastreio.
estimated_delivery_atstring (RFC 3339)
Previsão de entrega, em UTC.
public_notestring
Texto público.
shipped_atstring (RFC 3339)
Quando foi despachada.

Erros

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"missing authorization header"}
403O token não é de um usuário seller, ou ele não tem privilégio de pedidos.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_view_orders", "..."]}
403O pedido é de outro seller, ou é o pedido pai.{"error":"you do not have access to this order"}
403Atualizar rastreio com o módulo de acompanhamento desligado.{"error":"module_disabled","module":"order-status-flow"}
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"}
404Pedido, item ou remessa não encontrados. Na atualização, id ou shipmentId que não é UUID também dá isto.{"error":"order not found"}, {"error":"shipment_not_found"}
422Quantidade maior que a ainda não enviada, ou item de outro pedido.{"error":"cannot ship 2 of item 020ead81-...: only 0 remaining unshipped (total: 2, already shipped: 2)"}
422Dados de rastreio inválidos. field é tracking_url, estimated_delivery_at ou tracking; code é invalid, too_long ou nothing_to_update.{"error":"validation_failed","issues":[{"field":"tracking_url","code":"invalid"}]}
500Falha inesperada.{"error":"failed to create shipment","detail":"..."}
Envio parcial

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

Criar e listar não passam pelo escopo de representante

O detalhe do pedido e a atualização do rastreio respeitam a carteira do representante comercial. A listagem e a criação de remessa conferem só que o pedido é do seller.

Veja também

  • Mudar o status do pedido
  • Acompanhamento do pedido
  • Consultar pedidos
Anterior
Mudar o status do pedido
Próxima
Acompanhamento do pedido
Nesta página
  • Status de uma remessa
  • Listar as remessas
  • Resposta: listar
  • Criar uma remessa
  • Exemplo de requisição: criar
  • Resposta: criar
  • Atualizar o rastreio
  • Exemplo de requisição: atualizar o rastreio
  • Resposta: atualizar o rastreio
  • Erros
  • Veja também