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

bash

curl "$BASE_URL/api/v1/admin/fulfillments?status=pending&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Expedições retornadas

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
}

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

bash

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

Resposta

200Expedição encontrada

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"
}

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

bash

curl "$BASE_URL/api/v1/admin/fulfillments/stats?fulfilled_by=marketplace" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Números

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
}

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

bash

curl "$BASE_URL/api/v1/admin/fulfillments/fees?vendor_id=9d9d9d56-eb43-4719-889d-055632f7c7da" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Taxas retornadas

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
}

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

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","view_orders"]}`
403	Módulo `fulfillment` desligado	`{"error":"module_disabled","module":"fulfillment"}`
400	`fees` sem `vendor_id` nem `fulfillment_id`	`{"error":"vendor_id or fulfillment_id query parameter is required"}`
404	A expedição não existe	`{"error":"fulfillment not found"}`
500	`id`, `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..."}`

Veja também

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

bash

curl "$BASE_URL/api/v1/admin/fulfillments?status=pending&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Expedições retornadas

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
}

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

bash

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

Resposta

200Expedição encontrada

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"
}

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

bash

curl "$BASE_URL/api/v1/admin/fulfillments/stats?fulfilled_by=marketplace" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Números

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
}

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

bash

curl "$BASE_URL/api/v1/admin/fulfillments/fees?vendor_id=9d9d9d56-eb43-4719-889d-055632f7c7da" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Taxas retornadas

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
}

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

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","view_orders"]}`
403	Módulo `fulfillment` desligado	`{"error":"module_disabled","module":"fulfillment"}`
400	`fees` sem `vendor_id` nem `fulfillment_id`	`{"error":"vendor_id or fulfillment_id query parameter is required"}`
404	A expedição não existe	`{"error":"fulfillment not found"}`
500	`id`, `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..."}`