VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Expedição de pedidos

Consultar expedições

Lista e filtra as expedições, lê uma pelo id e consulta os números gerais e as taxas do marketplace.

Quatro leituras para acompanhar o despacho: a lista com filtros, uma expedição com detalhe, os totais por estado com os tempos médios e as taxas que a plataforma cobrou dos sellers.

Listar expedições

GET/api/v1/admin/fulfillmentsAdmin

Lista as expedições

Exige view_orders ou manage_orders e o módulo fulfillment ligado.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora disso vale 20.
vendor_iduuid
Só deste seller.
fulfilled_bystring
vendormarketplace
Quem despacha.
statusstring
pendingpickingpackedshippeddeliveredreturned
Estado. Aceita a palavra ou a letra.
order_iduuid
Só deste pedido.
searchstring
Texto parcial no número do pedido ou no código de rastreio.

Exemplo de requisição

Resposta

200Expedições retornadas

Campos da resposta

fulfillmentsarray
Expedições da página.
fulfillments[].iduuid
Id da expedição.
fulfillments[].order_iduuid
Pedido (ou sub-pedido) expedido.
fulfillments[].order_numberstring
Número do pedido.
fulfillments[].vendor_iduuid
Seller dono dos itens. Ausente em pedido da própria loja.
fulfillments[].vendor_namestring
Nome do seller. Ausente se não houver.
fulfillments[].fulfilled_bystring
vendormarketplace
Quem despacha.
fulfillments[].statusstring
pendingpickingpackedshippeddeliveredreturned
Estado da expedição.
fulfillments[].tracking_numberstring
Código de rastreio. Ausente antes do envio.
fulfillments[].tracking_urlstring
Link de rastreamento. Ausente se não informado.
fulfillments[].carrierstring
Transportadora, em texto livre. Ausente se não informada.
fulfillments[].picked_atstring
Quando entrou em separação (RFC 3339). Ausente enquanto não ocorreu; o mesmo vale para packed_at, shipped_at, delivered_at e returned_at.
fulfillments[].notesstring
Observações internas.
fulfillments[].updated_byuuid
Usuário da última alteração, quando registrado.
fulfillments[].itemsarray
Itens cobertos, quando a expedição é parcial: order_item_id, quantity, product_name. Ausente quando cobre o pedido todo.
fulfillments[].is_partialboolean
Verdadeiro quando os itens declarados cobrem menos que o pedido.
fulfillments[].feesarray
Taxas cobradas do seller por esta expedição (veja Taxas). Sempre presente, [] se não houver.
fulfillments[].fee_totalinteger
Soma das taxas, em centavos.
fulfillments[].fee_countinteger
Quantidade de taxas.
fulfillments[].created_atstring
Criação, RFC 3339 em UTC.
fulfillments[].updated_atstring
Última alteração, RFC 3339 em UTC.
totalinteger
Total que atende ao filtro.
pageinteger
Página devolvida.
per_pageinteger
Itens por página aplicados.
total_pagesinteger
Quantidade de páginas.

Consultar uma expedição

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

Lê uma expedição

Exige view_orders ou manage_orders e o módulo fulfillment ligado.

Parâmetros de caminho

iduuidobrigatório
Id da expedição.

Exemplo de requisição

Resposta

200Expedição encontrada

Os campos são os da listagem, com items e fees completos.

Números gerais

Conta as expedições por estado e calcula os tempos médios, em dias, entre a criação e o envio, e entre o envio e a entrega.

GET/api/v1/admin/fulfillments/statsAdmin

Números gerais das expedições

Exige view_orders ou manage_orders e o módulo fulfillment ligado.

Parâmetros de consulta

fulfilled_bystring
vendormarketplace
Restringe a vendor ou marketplace.

Exemplo de requisição

Resposta

200Números

Campos da resposta

total_pendinginteger
Expedições em pending. O mesmo vale, por estado, para total_picking, total_packed, total_shipped, total_delivered e total_returned.
avg_ship_time_daysnumber
Média, em dias, da criação ao envio.
avg_deliver_daysnumber
Média, em dias, do envio à entrega.

Taxas do marketplace

Lista as taxas cobradas de um seller (vendor_id) ou de uma expedição (fulfillment_id). Um dos dois filtros é obrigatório; se enviar os dois, vale fulfillment_id.

GET/api/v1/admin/fulfillments/feesAdmin

Lista as taxas de expedição

Exige view_orders ou manage_orders e o módulo fulfillment ligado.

Parâmetros de consulta

vendor_iduuid
Seller cobrado. Obrigatório se não houver fulfillment_id.
fulfillment_iduuid
Expedição. Obrigatório se não houver vendor_id.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página.

Exemplo de requisição

Resposta

200Taxas retornadas

Campos da resposta

feesarray

Taxas da página. null quando não há nenhuma.

iduuid
Id da taxa.
fulfillment_iduuid
Expedição.
vendor_iduuid
Seller cobrado.
order_iduuid
Pedido.
amountinteger
Valor da taxa, em centavos.
fee_typestring
Categoria da taxa (padrão shipping).
descriptionstring
Texto livre. Ausente se vazio.
rate_bpsinteger
Taxa aplicada, em pontos-base (500 = 5%).
base_amountinteger
Subtotal do pedido sobre o qual a taxa foi calculada, em centavos.
is_deductedboolean
Se já foi descontada de um repasse ao seller.
deducted_atstring
Quando foi descontada. Ausente se ainda não.
payout_iduuid
Repasse em que foi descontada. Ausente se ainda não.
created_atstring
Criação, RFC 3339 em UTC.
pageinteger
Página devolvida.
per_pageinteger
Itens por página.
totalinteger
Total de taxas.

Erros

StatusQuandoCorpo
401Sem token, token inválido ou expirado{"error":"invalid or expired token"}
403Sem o privilégio exigido{"error":"insufficient privileges","privilege_required_any":["manage_orders","view_orders"]}
403Módulo fulfillment desligado{"error":"module_disabled","module":"fulfillment"}
400fees sem vendor_id nem fulfillment_id{"error":"vendor_id or fulfillment_id query parameter is required"}
404A expedição não existe{"error":"fulfillment not found"}
500id, vendor_id ou order_id que não é UUID; falha interna{"error":"failed to get fulfillment","detail":"o valor \"bad\" não é um uuid válido..."}
UUID inválido responde 500

Nestas rotas, um id que não é UUID não vira 400: a resposta é 500 com a explicação em detail. Valide os ids antes de chamar.

Fila do dia

Para a fila de separação: status=pending ou status=picking, filtrando por fulfilled_by=marketplace quando só os pedidos do armazém da plataforma interessam.

Veja também

  • Criar uma expedição
  • Enviar e entregar
Anterior
Expedição de pedidos
Próxima
Criar expedição
Nesta página
  • Listar expedições
  • Exemplo de requisição
  • Resposta
  • Consultar uma expedição
  • Exemplo de requisição
  • Resposta
  • Números gerais
  • Exemplo de requisição
  • Resposta
  • Taxas do marketplace
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/fulfillments?status=pending&per_page=20" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/fulfillments/$FULFILLMENT_ID" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/fulfillments/stats?fulfilled_by=marketplace" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/fulfillments/fees?vendor_id=9d9d9d56-eb43-4719-889d-055632f7c7da" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "fulfillments": [
    {
      "id": "42f4e4b1-5d78-4ce5-bf0e-355f927168ef",
      "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "fulfilled_by": "vendor",
      "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
    }
  ],
  "total": 79,
  "page": 1,
  "per_page": 20,
  "total_pages": 4
}
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"
}
json
{
  "total_pending": 77,
  "total_picking": 0,
  "total_packed": 0,
  "total_shipped": 2,
  "total_delivered": 0,
  "total_returned": 0,
  "avg_ship_time_days": 4.9,
  "avg_deliver_days": 0
}
json
{
  "fees": [
    {
      "id": "0b8f6a70-3a10-4b45-9d0c-6f1f2a6c1d11",
      "fulfillment_id": "42f4e4b1-5d78-4ce5-bf0e-355f927168ef",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "amount": 1250,
      "fee_type": "shipping",
      "rate_bps": 500,
      "base_amount": 25000,
      "is_deducted": false,
      "created_at": "2026-10-11T20:55:26.100000Z"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 1
}