API atual/Referência completa/Expedição e retirada

POSTMarcar como enviada

Registra o despacho da expedição com rastreio e transportadora e avisa o cliente.

É a forma mais direta de dizer "saiu". Leva a expedição para shipped, grava shipped_at, o código e o link de rastreio e a transportadora. Se você informou tracking_number, a plataforma também dispara o evento de envio criado, que gera o e-mail "seu pedido foi enviado" ao cliente (e a mensagem de WhatsApp, quando a loja usa).

POST/api/v1/vendor/fulfillments/{id}/shipSeller

Marca uma expedição do seller como enviada

Parâmetros de caminho

iduuidobrigatório

Id da expedição.

Corpo da requisição

tracking_numberstring

Código de rastreio. Sem ele a expedição vai para shipped, mas o cliente não é avisado.

tracking_urlstring

Link de rastreio mostrado ao cliente.

carrierstring

Transportadora (por exemplo o code de Transportadoras). Aparece no e-mail.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/fulfillments/e1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b/ship" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "AA123456789BR",
    "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR",
    "carrier": "correios_sedex"
  }'

Resposta

200Expedição enviada

json

{
  "id": "e1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
  "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
  "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "fulfilled_by": "vendor",
  "status": "shipped",
  "tracking_number": "AA123456789BR",
  "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR",
  "carrier": "correios_sedex",
  "shipped_at": "2026-10-03T13:05:00Z",
  "notes": "Caixa dupla",
  "created_at": "2026-10-01T14:20:11Z",
  "updated_at": "2026-10-03T13:05:00Z",
  "vendor_name": "Loja Exemplo",
  "order_number": "VD-20261001-0042",
  "items": [
    {
      "id": "a1b2c3d4-0000-4000-8000-000000000001",
      "fulfillment_id": "e1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
      "order_item_id": "a1b2c3d4-0000-4000-8000-000000000002",
      "quantity": 2,
      "product_name": "Camiseta Básica",
      "created_at": "2026-10-01T14:20:11Z"
    }
  ],
  "is_partial": false,
  "fees": [],
  "fee_total": 0,
  "fee_count": 0
}

Campos da resposta

(campos)object

A expedição completa, já em shipped.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	A expedição não pode ir para `shipped` a partir do estado atual (já enviada, entregue ou devolvida).	`{"error":"failed to mark as shipped","detail":"cannot mark as shipped from status delivered"}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	A expedição é da plataforma (`fulfilled_by` = `marketplace`): o seller não pode enviá-la.	`{"error":"cannot ship marketplace-fulfilled orders","detail":"only vendor-fulfilled orders can be shipped by the vendor"}`
404	O usuário não tem perfil de seller.	`{"error":"vendor profile not found"}`
404	Não existe expedição com esse id para este seller (ou a expedição é de outro).	`{"error":"fulfillment not found"}`
403	O módulo `fulfillment` está desligado na loja.	`{"error":"module_disabled","module":"fulfillment"}`
500	O `id` não é um UUID. A rota não valida o formato: o `detail` vem em português.	`{"error":"failed to get fulfillment","detail":"o valor \"abc\" não é um uuid válido. ..."}`

Veja também