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

Enviar e entregar

Marca uma expedição como enviada, com rastreio, e depois como entregue; o envio com rastreio avisa o cliente por e-mail.

Os dois momentos que importam ao cliente. Enviar grava o rastreio e o horário de saída e, se houver código de rastreio, dispara o evento que gera o e-mail (e o aviso por WhatsApp, quando a loja o usa) "seu pedido foi enviado", com transportadora e código. Entregar fecha o ciclo.

Ambas atualizam apenas a expedição; o status do pedido não muda.

Marcar como enviada

Permitido a partir de pending, picking e packed. Os três campos do corpo são gravados como vierem; os que você omitir ficam vazios, mesmo que já houvesse valor.

POST/api/v1/admin/fulfillments/{id}/shipAdmin

Marca uma expedição como enviada

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

tracking_numberstring

Código de rastreio. Sem ele, o e-mail de envio não é disparado.

tracking_urlstring

Link de rastreamento.

carrierstring

Nome da transportadora, texto livre.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fulfillments/$FULFILLMENT_ID/ship" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "BR123456789CD",
    "carrier": "Correios",
    "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objetos=BR123456789CD"
  }'

Resposta

200Expedição enviada

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": "shipped",
  "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,
  "tracking_number": "BR123456789CD",
  "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objetos=BR123456789CD",
  "carrier": "Correios",
  "shipped_at": "2026-10-12T13:02:11.410022Z"
}

Devolve a expedição completa (campos em Consultar expedições).

Marcar como entregue

Só vale para uma expedição em shipped. Grava delivered_at. Sem corpo.

POST/api/v1/admin/fulfillments/{id}/deliverAdmin

Marca uma expedição como entregue

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

Parâmetros de caminho

iduuidobrigatório

Id da expedição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fulfillments/$FULFILLMENT_ID/deliver" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Expedição entregue

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": "delivered",
  "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,
  "tracking_number": "BR123456789CD",
  "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objetos=BR123456789CD",
  "carrier": "Correios",
  "shipped_at": "2026-10-12T13:02:11.410022Z",
  "delivered_at": "2026-10-15T16:40: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; expedição inexistente; estado que não permite a ação	`{"error":"failed to mark as shipped","detail":"cannot mark as shipped from status delivered"}` / `{"error":"failed to mark as delivered","detail":"cannot mark as delivered from status pending (must be shipped)"}`

Veja também

Enviar e entregar

Marca uma expedição como enviada, com rastreio, e depois como entregue; o envio com rastreio avisa o cliente por e-mail.

Ambas atualizam apenas a expedição; o status do pedido não muda.

Marcar como enviada

Permitido a partir de pending, picking e packed. Os três campos do corpo são gravados como vierem; os que você omitir ficam vazios, mesmo que já houvesse valor.

POST/api/v1/admin/fulfillments/{id}/shipAdmin

Marca uma expedição como enviada

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

tracking_numberstring

Código de rastreio. Sem ele, o e-mail de envio não é disparado.

tracking_urlstring

Link de rastreamento.

carrierstring

Nome da transportadora, texto livre.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fulfillments/$FULFILLMENT_ID/ship" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "BR123456789CD",
    "carrier": "Correios",
    "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objetos=BR123456789CD"
  }'

Resposta

200Expedição enviada

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": "shipped",
  "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,
  "tracking_number": "BR123456789CD",
  "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objetos=BR123456789CD",
  "carrier": "Correios",
  "shipped_at": "2026-10-12T13:02:11.410022Z"
}

Devolve a expedição completa (campos em Consultar expedições).

Marcar como entregue

Só vale para uma expedição em shipped. Grava delivered_at. Sem corpo.

POST/api/v1/admin/fulfillments/{id}/deliverAdmin

Marca uma expedição como entregue

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

Parâmetros de caminho

iduuidobrigatório

Id da expedição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/fulfillments/$FULFILLMENT_ID/deliver" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Expedição entregue

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": "delivered",
  "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,
  "tracking_number": "BR123456789CD",
  "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objetos=BR123456789CD",
  "carrier": "Correios",
  "shipped_at": "2026-10-12T13:02:11.410022Z",
  "delivered_at": "2026-10-15T16:40: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; expedição inexistente; estado que não permite a ação	`{"error":"failed to mark as shipped","detail":"cannot mark as shipped from status delivered"}` / `{"error":"failed to mark as delivered","detail":"cannot mark as delivered from status pending (must be shipped)"}`