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

Envios do pedido

Lista, consulta, cria e atualiza os envios (remessas) de um pedido, com código de rastreio, transportadora e itens despachados.

Um envio (remessa) registra que parte de um pedido, ou o pedido inteiro, saiu para o cliente: quais itens, em que quantidade, por qual transportadora e com qual código de rastreio. Um pedido pode ter vários envios, por exemplo quando o estoque sai em dois lotes. Use estas rotas quando o ERP ou o sistema de expedição precisa dar baixa do que foi despachado e informar o rastreio ao cliente.

Todas exigem um usuário administrador e também respondem sem o prefixo de versão (/api/shipments). Criar um envio não muda o status do pedido: faça isso à parte, com Alterar o status.

Status do envio

O campo status do envio é uma letra.

LetraSignificado
NPendente (criado sem código de rastreio)
AEnviado
PEm trânsito
WSaiu para entrega
HAguardando retirada
CEntregue
FFalha na entrega
DDevolvido
LExtraviado
ICancelado
GET/api/v1.0/shipmentsAdmin

Listar os envios de um pedido

Devolve os envios de um pedido. O filtro order_id é obrigatório: não existe lista de todos os envios da loja.

Parâmetros de consulta

order_idstringobrigatório
Id do pedido (UUID; decimal em string em /api/shipments).

A resposta traz sempre todos os envios do pedido. Os campos page e items_per_page aparecem em params apenas como eco do que você mandou (padrão 1 e 10) e não fatiam a lista.

GET/api/v1.0/shipments/{id}Admin

Consultar um envio

Devolve um envio pelo id, com os itens.

Parâmetros de caminho

idstringobrigatório
Id do envio (UUID; decimal em string em /api/shipments/{id}).
POST/api/v1.0/shipmentsAdmin

Criar um envio

Cria um envio com os itens e as quantidades que você mandar. A plataforma confere que os itens pertencem ao pedido e que você não despacha mais do que ainda falta enviar (envios devolvidos não contam). Com tracking_number, o envio nasce como enviado (A) e o cliente recebe o e-mail de rastreio. Sem o código, nasce como pendente (N).

Corpo da requisição

order_idstringobrigatório
Pedido. Aceita texto ou número.
shipping_idstringobrigatório
Id do método de frete. Precisa estar presente; a plataforma não o grava no envio.
productsobjectobrigatório

Itens do envio. Duas formas são aceitas: um objeto {"<item_id>": quantidade} (a forma da Venddor 1.0) ou uma lista de objetos [{"item_id": "...", "amount": 2}]. Os item_id são os ids dos itens do pedido (veja products[].item_id em Consultar um pedido). Não pode ser vazio.

tracking_numberstring
Código de rastreio.
carrierstring
Transportadora.
commentsstring
Observação interna.
PUT/api/v1.0/shipments/{id}Admin

Atualizar um envio

Altera o rastreio, a transportadora, o status ou a observação de um envio. Só os campos enviados mudam. Ao colocar o status delivered, a plataforma grava a data de entrega.

Parâmetros de caminho

idstringobrigatório
Id do envio.

Corpo da requisição

tracking_numberstring
Código de rastreio.
carrierstring
Transportadora.
statusstring
pendingshippedin_transitout_for_deliveryawaiting_pickupdelivereddelivery_failedreturnedlostcanceled
Novo status, pelo nome em inglês da lista. Na entrada a letra não é aceita, mas na saída status volta como letra.
commentsstring
Observação.
DELETE/api/v1.0/shipments/{id}Admin

Remover um envio (não disponível)

A plataforma ainda não apaga envios. A rota existe para manter o contrato, mas sempre responde 501. Para desfazer um envio, mude o status dele para canceled ou returned com a rota de atualização.

Parâmetros de caminho

idstringobrigatório
Id do envio.

Exemplo de requisição

bash
# Cria o envio com rastreio
curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/shipments" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "e841d5e1-e00f-4df3-92a3-b01a139026f9",
    "shipping_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
    "tracking_number": "BR123456789BR",
    "carrier": "Correios",
    "products": { "9787424c-0fca-44a9-9c96-9bba0c1f4704": 1 }
  }'

# Lista os envios do pedido
curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/shipments?order_id=$ORDER_ID"

Resposta

200Envios do pedido
json
{
  "shipments": [
    {
      "shipment_id": "0d5b1f0e-6a3c-4a53-9f55-5a1f7c7d2a10",
      "order_id": "e841d5e1-e00f-4df3-92a3-b01a139026f9",
      "tracking_number": "BR123456789BR",
      "carrier": "Correios",
      "status": "A",
      "comments": "",
      "timestamp": 1791749793,
      "products": [
        { "item_id": "9787424c-0fca-44a9-9c96-9bba0c1f4704", "amount": 1, "product": "Camiseta Básica", "product_code": "CAM-001" }
      ]
    }
  ],
  "params": { "items_per_page": 10, "page": 1, "total_items": 1 }
}
201Envio criado
json
{ "shipment_id": "0d5b1f0e-6a3c-4a53-9f55-5a1f7c7d2a10" }

Campos da resposta

shipmentsarray
Envios do pedido. Vazio se não houver nenhum.
shipments[].shipment_idstring
Id do envio.
shipments[].order_idstring
Id do pedido.
shipments[].tracking_numberstring
Código de rastreio. Ausente se não houver.
shipments[].carrierstring
Transportadora. Ausente se não houver.
shipments[].statusstring
Letra do status (tabela acima).
shipments[].commentsstring
Observação. Ausente se vazia.
shipments[].timestampinteger
Criação do envio, em Unix timestamp (segundos, UTC).
shipments[].productsarray
Itens despachados.
shipments[].products[].item_idstring
Id do item do pedido.
shipments[].products[].amountinteger
Quantidade despachada.
shipments[].products[].productstring
Nome do produto.
shipments[].products[].product_codestring
Código (SKU), quando existe.
paramsobject
items_per_page, page e total_items (quantidade de envios devolvidos).

Erros

StatusQuandoCorpo
400order_id ausente na lista{"message":"order_id is required","status":400}
400order_id ausente na criação{"message":"order_id is required","status":400}
400shipping_id ausente na criação{"message":"shipping_id is required","status":400}
400products ausente ou vazio{"message":"products[] is required","status":400}
400Item que não é do pedido, quantidade maior que a que falta enviar, pedido inexistente{"message":"order not found: ...","status":400}
400Status inválido na atualização{"message":"invalid shipment status: A","status":400}
400Envio inexistente na atualização{"message":"shipment not found: ...","status":400}
401Sem credenciais{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403Usuário que não é administrador{"message":"Forbidden: admin scope required","status":403}
404Id do envio que não existe (consulta, quando não é um UUID){"message":"shipment abc not found","status":404}
500Consulta com um UUID bem formado que não existe{"error":"internal server error"}
501Qualquer DELETE{"message":"shipment deletion not yet supported","status":501}
Envie primeiro, mude o status depois

Crie o envio e só então mude o status do pedido para o de enviado. Se o código de rastreio só chega depois, crie o envio sem ele (fica pendente) e complete com PUT /shipments/{id}, mandando tracking_number e "status": "shipped": informar só o rastreio não tira o envio de pendente.

Veja também

  • Status de pedido
  • Alterar o status de um pedido
  • Consultar um pedido
Anterior
Status de pedido
Próxima
Produtos
Nesta página
  • Status do envio
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também