Expedição de pedidos

Num marketplace, nem sempre quem vende é quem envia. A expedição (fulfillment) registra, para cada pedido ou sub-pedido, quem despacha (fulfilled_by): o próprio seller (lojista) ou o marketplace, com o estoque no armazém da plataforma. Também guarda o andamento da separação ao envio e o código de rastreio.

Quando o módulo fulfillment está ligado, a plataforma cria sozinha a expedição de cada pedido novo, uma por seller. As rotas desta seção servem a quem precisa corrigir isso à mão, andar o estado de uma expedição ou ver as taxas e os números gerais.

Como funciona

Cada passo grava o seu horário (picked_at, packed_at, shipped_at, delivered_at, returned_at).

Conceitos-chave

Quem despacha e a taxa do marketplace

Com fulfilled_by: "marketplace", a plataforma prepara e envia. Em troca, cobra do seller uma taxa igual ao subtotal do pedido multiplicado pela taxa de despacho do seller (em pontos-base: 500 = 5%). A taxa é um registro à parte, listado em Taxas e números. Se o seller não tem taxa configurada, nada é cobrado.

Expedição parcial

Uma expedição pode cobrir só parte dos itens de um pedido (items, is_partial). A criação por esta API não aceita itens: ela sempre cobre o pedido todo.

Pedido e expedição são coisas diferentes

A expedição é o controle de despacho. O status do pedido é outro e continua sendo mudado pela API de pedidos (Alterar o status). Não espere que enviar uma expedição mude o pedido.

Endpoints

Erros comuns

1. Ler /fulfillments/fees sem filtro. Exige vendor_id ou fulfillment_id; sem eles, 400.
2. Passar o estado como letra no PUT. O corpo aceita só a palavra (shipped); a letra volta 400.
3. Pular etapas. pending não vai direto a delivered; delivered só nasce de shipped.
4. Enviar sem rastreio. Funciona, mas o cliente não recebe o e-mail de envio.
5. Mandar items na criação esperando expedição parcial. O campo é ignorado nesta rota.
6. Achar que enviar muda o pedido. Mude o status do pedido pela API de pedidos.

Próximos passos