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

Criar expedição

Registra quem despacha um pedido, o seller ou o marketplace, e cobra a taxa do marketplace quando é ele quem envia.

Em condições normais você não precisa criar expedições: com o módulo ligado, a plataforma cria uma por seller assim que o pedido nasce. Use esta rota para pedidos anteriores ao módulo, para recriar uma expedição ou para trocar o responsável de um pedido que ainda não tem uma.

A criação é idempotente por pedido e seller: se já existe uma expedição para o par, a rota devolve a existente em vez de falhar. Com fulfilled_by: "marketplace", a taxa do seller é calculada e registrada; se o seller não tem taxa configurada, ou o cálculo falha, a expedição é criada mesmo assim, sem taxa.

Criar

POST/api/v1/admin/fulfillmentsAdmin

Cria uma expedição

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

Corpo da requisição

order_iduuidobrigatório

Pedido (ou sub-pedido) a expedir.

fulfilled_bystringobrigatório

vendormarketplace

Quem despacha.

vendor_iduuid

Seller dono dos itens. Omita em pedido da própria loja.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fulfillments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
    "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
    "fulfilled_by": "marketplace"
  }'

Resposta

201Expedição criada

json

{
  "id": "42f4e4b1-5d78-4ce5-bf0e-355f927168ef",
  "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "fulfilled_by": "marketplace",
  "status": "pending",
  "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
}

Os campos são os de Consultar expedições. Na resposta de uma criação nova, fees ainda vem []: a taxa é gravada logo em seguida e aparece ao reler a expedição.

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; `order_id` ou `fulfilled_by` vazio; `fulfilled_by` que não é `vendor` nem `marketplace`; pedido ou seller inexistente	`{"error":"order_id and fulfilled_by are required"}` / `{"error":"failed to create fulfillment","detail":"..."}`

Veja também