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

Listar e consultar expedições

Lista as expedições do seller com filtros e paginação, ou devolve uma delas pelo id.

Listar expedições

Devolve as expedições do seller, da mais nova para a mais antiga, paginadas.

GET/api/v1/vendor/fulfillmentsSeller

Lista as expedições do seller

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 volta para 20.
statusstring
pendingpickingpackedshippeddeliveredreturned
Filtra por etapa: pending, picking, packed, shipped, delivered ou returned. Um valor desconhecido não dá erro: é tratado como pending.
fulfilled_bystring
vendormarketplace
vendor ou marketplace.
order_iduuid
Só as expedições deste pedido.
searchstring
Busca parcial, sem diferenciar maiúsculas, no número do pedido ou no código de rastreio.

Exemplo de requisição: listar

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

Resposta: listar

200Página de expedições
json
{
  "fulfillments": [
    {
      "id": "e1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
      "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
      "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "fulfilled_by": "vendor",
      "status": "pending",
      "notes": "Caixa dupla",
      "created_at": "2026-10-01T14:20:11Z",
      "updated_at": "2026-10-03T13:05:00Z",
      "vendor_name": "Loja Exemplo",
      "order_number": "VD-20261001-0042",
      "items": [
        {
          "id": "a1b2c3d4-0000-4000-8000-000000000001",
          "fulfillment_id": "e1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
          "order_item_id": "a1b2c3d4-0000-4000-8000-000000000002",
          "quantity": 2,
          "product_name": "Camiseta Básica",
          "created_at": "2026-10-01T14:20:11Z"
        }
      ],
      "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 (campos em "Consultar uma expedição").
totalinteger
Total de expedições que casam com o filtro.
pageinteger
Página devolvida.
per_pageinteger
Tamanho da página usado.
total_pagesinteger
Total de páginas.

Erros: listar

StatusQuandoCorpo de exemplo
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
404O usuário não tem perfil de seller.{"error":"vendor profile not found"}
403O módulo fulfillment está desligado na loja.{"error":"module_disabled","module":"fulfillment"}
500Falha ao consultar (por exemplo, order_id que não é UUID).{"error":"failed to list fulfillments"}
Fila de trabalho

Para montar a fila do dia, consulte status=pending e fulfilled_by=vendor: são as expedições que dependem de você.

Consultar uma expedição

Devolve a expedição completa, com itens (se parcial) e taxas, sem envelope.

GET/api/v1/vendor/fulfillments/{id}Seller

Mostra uma expedição do seller

Parâmetros de caminho

iduuidobrigatório
Id da expedição.

Exemplo de requisição: consultar

bash
curl "$BASE_URL/api/v1/vendor/fulfillments/e1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $TOKEN"

Resposta: consultar

200Expedição encontrada
json
{
  "id": "e1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
  "order_id": "b4d2f0a8-6c1e-4b3d-9a7f-2e5c8d1b0a96",
  "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "fulfilled_by": "vendor",
  "status": "shipped",
  "tracking_number": "AA123456789BR",
  "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR",
  "carrier": "correios_sedex",
  "shipped_at": "2026-10-03T13:05:00Z",
  "notes": "Caixa dupla",
  "created_at": "2026-10-01T14:20:11Z",
  "updated_at": "2026-10-03T13:05:00Z",
  "vendor_name": "Loja Exemplo",
  "order_number": "VD-20261001-0042",
  "items": [
    {
      "id": "a1b2c3d4-0000-4000-8000-000000000001",
      "fulfillment_id": "e1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
      "order_item_id": "a1b2c3d4-0000-4000-8000-000000000002",
      "quantity": 2,
      "product_name": "Camiseta Básica",
      "created_at": "2026-10-01T14:20:11Z"
    }
  ],
  "is_partial": false,
  "fees": [],
  "fee_total": 0,
  "fee_count": 0
}

Campos da resposta

iduuid
Id da expedição.
order_iduuid
Pedido (ou sub-pedido) expedido.
vendor_iduuid
Seller responsável.
fulfilled_bystring
vendormarketplace
Quem envia: vendor (o seller) ou marketplace (a loja, no modelo de expedição pela plataforma).
statusstring
pendingpickingpackedshippeddeliveredreturned
pending, picking, packed, shipped, delivered ou returned.
tracking_numberstring
Código de rastreio. Ausente enquanto não informado.
tracking_urlstring
Link de rastreio. Ausente quando não informado.
carrierstring
Transportadora (texto livre). Ausente quando não informada.
picked_at, packed_at, shipped_at, delivered_at, returned_atstring
Datas (RFC 3339) em que a expedição entrou em cada etapa. Cada uma ausente até acontecer.
notesstring
Observações internas. Ausente quando vazio.
updated_byuuid
Último usuário que alterou, quando conhecido.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
vendor_namestring
Nome da empresa do seller.
order_numberstring
Número do pedido, o mesmo da lista de pedidos.
itemsarray
Itens cobertos, com order_item_id, quantity e product_name. Ausente quando a expedição cobre o pedido inteiro.
is_partialboolean
true quando os items cobrem menos que a quantidade total do pedido.
feesarray

Taxas cobradas desta expedição (veja Estatísticas e taxas). Sempre presente, [] se não há.

iduuid
Id da taxa.
fulfillment_iduuid
Expedição que gerou a taxa.
vendor_iduuid
Seller cobrado.
order_iduuid
Pedido da taxa.
amountinteger
Valor da taxa, em centavos.
fee_typestring
Categoria da taxa (shipping por padrão).
descriptionstring
Texto livre. Ausente quando vazio.
rate_bpsinteger
Taxa aplicada, em pontos-base (250 = 2,5%).
base_amountinteger
Subtotal do pedido sobre o qual a taxa foi calculada, em centavos.
is_deductedboolean
Se a taxa já foi descontada de um repasse.
payout_iduuid
Repasse em que foi descontada. Ausente enquanto pendente.
created_atstring
Criação, RFC 3339.
fee_totalinteger
Soma das taxas, em centavos.
fee_countinteger
Quantidade de taxas.

Erros: consultar

StatusQuandoCorpo de exemplo
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
404O usuário não tem perfil de seller.{"error":"vendor profile not found"}
404Não existe expedição com esse id para este seller (ou a expedição é de outro).{"error":"fulfillment not found"}
403O módulo fulfillment está desligado na loja.{"error":"module_disabled","module":"fulfillment"}
500O id não é um UUID. A rota não valida o formato: o detail vem em português.{"error":"failed to get fulfillment","detail":"o valor \"abc\" não é um uuid válido. ..."}

Veja também

  • Alterar expedição
  • Marcar como enviada
  • Visão geral
Anterior
Expedição e retirada
Próxima
Alterar expedição
Nesta página
  • Listar expedições
  • Exemplo de requisição: listar
  • Resposta: listar
  • Erros: listar
  • Consultar uma expedição
  • Exemplo de requisição: consultar
  • Resposta: consultar
  • Erros: consultar
  • Veja também