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.
| Letra | Significado |
|---|---|
N | Pendente (criado sem código de rastreio) |
A | Enviado |
P | Em trânsito |
W | Saiu para entrega |
H | Aguardando retirada |
C | Entregue |
F | Falha na entrega |
D | Devolvido |
L | Extraviado |
I | Cancelado |
/api/v1.0/shipmentsAdminListar 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/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.
/api/v1.0/shipments/{id}AdminConsultar um envio
Devolve um envio pelo id, com os itens.
Parâmetros de caminho
idstringobrigatório/api/shipments/{id})./api/v1.0/shipmentsAdminCriar 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órioshipping_idstringobrigatórioproductsobjectobrigatórioItens 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_numberstringcarrierstringcommentsstring/api/v1.0/shipments/{id}AdminAtualizar 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órioCorpo da requisição
tracking_numberstringcarrierstringstatusstringpendingshippedin_transitout_for_deliveryawaiting_pickupdelivereddelivery_failedreturnedlostcanceledstatus volta como letra.commentsstring/api/v1.0/shipments/{id}AdminRemover 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órioExemplo de requisição
Resposta
Campos da resposta
shipmentsarrayshipments[].shipment_idstringshipments[].order_idstringshipments[].tracking_numberstringshipments[].carrierstringshipments[].statusstringshipments[].commentsstringshipments[].timestampintegershipments[].productsarrayshipments[].products[].item_idstringshipments[].products[].amountintegershipments[].products[].productstringshipments[].products[].product_codestringparamsobjectitems_per_page, page e total_items (quantidade de envios devolvidos).Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | order_id ausente na lista | {"message":"order_id is required","status":400} |
| 400 | order_id ausente na criação | {"message":"order_id is required","status":400} |
| 400 | shipping_id ausente na criação | {"message":"shipping_id is required","status":400} |
| 400 | products ausente ou vazio | {"message":"products[] is required","status":400} |
| 400 | Item que não é do pedido, quantidade maior que a que falta enviar, pedido inexistente | {"message":"order not found: ...","status":400} |
| 400 | Status inválido na atualização | {"message":"invalid shipment status: A","status":400} |
| 400 | Envio inexistente na atualização | {"message":"shipment not found: ...","status":400} |
| 401 | Sem credenciais | {"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401} |
| 403 | Usuário que não é administrador | {"message":"Forbidden: admin scope required","status":403} |
| 404 | Id do envio que não existe (consulta, quando não é um UUID) | {"message":"shipment abc not found","status":404} |
| 500 | Consulta com um UUID bem formado que não existe | {"error":"internal server error"} |
| 501 | Qualquer DELETE | {"message":"shipment deletion not yet supported","status":501} |