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

PUTAlterar expedição

Muda a etapa, o rastreio ou as notas de uma expedição do próprio seller.

Use para andar com a expedição pelas etapas (separando, embalada, entregue) e para corrigir o rastreio. A alteração é parcial: só os campos enviados mudam. Mudar o status grava a data da etapa (picked_at, packed_at, shipped_at, delivered_at ou returned_at). Para despachar com rastreio e avisar o cliente, prefira /ship.

PUT/api/v1/vendor/fulfillments/{id}Seller

Altera uma expedição do seller

Parâmetros de caminho

iduuidobrigatório

Id da expedição.

Corpo da requisição

statusstring

pickingpackedshippeddeliveredreturned

Nova etapa, em palavra. Só transições permitidas (veja a visão geral).

tracking_numberstring

Código de rastreio.

tracking_urlstring

Link de rastreio.

carrierstring

Transportadora, texto livre.

notesstring

Observações internas.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/fulfillments/e1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "packed",
    "notes": "Caixa dupla"
  }'

Resposta

200Expedição atualizada

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": "packed",
  "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,
  "packed_at": "2026-10-02T10:40:00Z"
}

Campos da resposta

(campos)object

A expedição completa, igual a Consultar uma expedição.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	`status` que não é uma das seis palavras (inclusive a letra do banco).	`{"error":"failed to update fulfillment","detail":"invalid status: S"}`
400	Transição não permitida.	`{"error":"failed to update fulfillment","detail":"invalid transition from pending to 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 alterá-la.	`{"error":"cannot update marketplace-fulfilled orders","detail":"only vendor-fulfilled orders can be updated 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