API atual/Referência completa/Expedição de pedidos

Alterar expedição

Corrige o rastreio, as notas ou o estado de uma expedição, respeitando a ordem permitida entre os estados.

Use esta rota para o dia a dia da separação (picking, packed), para corrigir um código de rastreio digitado errado ou para registrar uma devolução (returned). A alteração é parcial: só os campos enviados mudam. Ao mudar o estado, o horário do novo estado é gravado.

Para despachar e entregar, prefira as rotas dedicadas de Enviar e entregar: somente elas avisam o cliente.

Alterar

PUT/api/v1/admin/fulfillments/{id}Admin

Altera uma expedição

Exige o privilégio manage_orders e o módulo fulfillment ligado.

Parâmetros de caminho

iduuidobrigatório

Id da expedição.

Corpo da requisição

statusstring

pendingpickingpackedshippeddeliveredreturned

Novo estado, só a palavra. Veja as transições na página inicial da seção.

tracking_numberstring

Código de rastreio.

tracking_urlstring

Link de rastreamento.

carrierstring

Transportadora, texto livre.

notesstring

Observações internas.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/fulfillments/$FULFILLMENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "packed",
    "notes": "Caixa 2, frágil"
  }'

Resposta

200Expedição alterada

json

{
  "id": "42f4e4b1-5d78-4ce5-bf0e-355f927168ef",
  "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "fulfilled_by": "vendor",
  "status": "packed",
  "created_at": "2026-10-11T20:55:25.63652Z",
  "updated_at": "2026-10-11T20:55:25.63652Z",
  "vendor_name": "Loja Otávio",
  "order_number": "PILOT-20261011-0009",
  "is_partial": false,
  "fees": [],
  "fee_total": 0,
  "fee_count": 0,
  "notes": "Caixa 2, frágil",
  "packed_at": "2026-10-12T09:30:00.000000Z"
}

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio exigido	`{"error":"insufficient privileges","privilege_required_any":["manage_orders"]}`
403	Módulo `fulfillment` desligado	`{"error":"module_disabled","module":"fulfillment"}`
400	Corpo que não é JSON; `status` desconhecido (inclusive em letra); transição não permitida; expedição inexistente	`{"error":"failed to update fulfillment","detail":"invalid transition from pending to delivered"}` / `{"error":"failed to update fulfillment","detail":"invalid status: S"}`
200	Id que não existe e corpo sem `status`: a resposta é `null`, não um erro	`null`

Veja também