Glossário de envio e entrega

A documentação de pedidos usa quatro termos relacionados mas com papéis distintos. Esta seção explica cada um e onde aparecem.

shipping

Atributos do envio: valor do frete e estado atual da remessa.

Campo	Onde aparece	Significado
payment.shipping_amount	Request do POST, response do GET detalhe e listagem	Valor do frete cobrado, em centavos
items[].shipping_status	Response do GET detalhe	Estado atual do envio do item: AWAITING_SHIPMENT, SHIPPED, DELIVERED, RETURNED, LOST
tracking.shipping_status	Response do GET listagem	Mesmo estado, agrupado dentro de tracking no resumo da listagem
shipping_status	Body do PATCH /sellers/orders/{uuid}/tracking/	Estado do envio sendo informado (aplicado a todos os itens)

tracking

Atributos do rastreio: código fornecido pela transportadora e o estado de envio associado a ele. No payload da listagem, tracking também é o nome do objeto que agrupa esses dois campos como resumo.

Campo	Onde aparece	Significado
items[].tracking_code	Response do GET detalhe	Código de rastreio da transportadora
tracking.tracking_code	Response do GET listagem	Mesmo código, dentro do objeto tracking
tracking_code	Body do PATCH /sellers/orders/{uuid}/tracking/	Código sendo informado (aplicado a todos os itens)
tracking (objeto)	Response do GET listagem	Agrupador { tracking_code, shipping_status }
/tracking/ (path)	Endpoint PATCH /sellers/orders/{uuid}/tracking/	Ação de atualizar rastreio e estado do envio

delivery

Informações da entrega final: o que aconteceu quando a remessa chegou ao destinatário.

Campo	Onde aparece	Significado
delivery.estimated_delivery_date	Response do GET detalhe	Data estimada de entrega
delivery.delivered_at	Response do GET detalhe	Data/hora efetiva da entrega
delivery.signed_by	Response do GET detalhe	Nome de quem assinou o recebimento

Relação entre os três termos

O ciclo de vida típico de um pedido com produto físico é:

1. Pagamento aprovado → o pedido fica disponível para envio.
2. Envio (shipping) → o vendedor despacha. Atualiza shipping_status para SHIPPED e informa o tracking_code via PATCH /sellers/orders/{uuid}/tracking/.
3. Rastreio (tracking) → o cliente acompanha a remessa pelo tracking_code no site da transportadora.
4. Entrega (delivery) → o vendedor atualiza shipping_status para DELIVERED e informa signed_by. A plataforma preenche delivery.delivered_at automaticamente.

Granularidade

O modelo de dados guarda tracking_code e shipping_status por item (cada item de um pedido pode ter código e estado próprios no banco). O endpoint PATCH /sellers/orders/{uuid}/tracking/ aceita um único par de valores e os aplica a todos os itens do pedido. Envio parcial (cada item com código diferente) não é suportado nesta versão.