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

Expedição e retirada

Acompanhe quem despacha cada pedido do seller, informe o rastreio, veja as taxas e conduza as retiradas na loja.

Depois que um pedido é pago, alguém precisa separá-lo, embalá-lo e entregá-lo à transportadora, ou entregá-lo ao cliente que veio buscar. Estas rotas cobrem essa etapa do ponto de vista do seller (lojista): a expedição (fulfillment) registra quem despacha o pedido e em que etapa ele está; a retirada (pickup) conduz o pedido que o cliente vai buscar na loja; e a lista de transportadoras alimenta o formulário de envio.

Pontos principais
  • Duas coisas diferentes: expedição (/fulfillments, o despacho) e retirada (/pickups, o cliente busca na loja). Um pedido de retirada não passa por transportadora.
  • O seller só altera expedições cujo fulfilled_by é vendor. As de marketplace são só leitura (403).
  • O estado da expedição só anda para a frente, em transições fixas (invalid transition se pular).
  • Em status, envie a palavra (shipped), não a letra do banco. No filtro da lista, uma palavra desconhecida é tratada como pending.
  • Confirmar uma retirada exige o código de 6 dígitos do cliente; 5 erros seguidos travam a retirada por 15 minutos.
Idioma das mensagens

As mensagens de erro e alguns textos de pendência vêm do servidor em português ou em inglês, conforme a rota, e os exemplos desta seção as mostram exatamente como são devolvidas. Para lógica no seu código, use o status HTTP e os códigos (error, reason, code), nunca o texto.

Como funciona

Ciclo da expedição

pending→picking→packed→shipped→delivered
statusSignificadoPode ir para
pendingCriada, aguardando separação.picking, packed, shipped
pickingItens sendo separados.packed, shipped
packedEmbalada, pronta para despacho.shipped
shippedEntregue à transportadora.delivered, returned
deliveredEntregue ao cliente.returned
returnedDevolvida. Final.nenhum

Cada etapa grava a data correspondente (picked_at, packed_at, shipped_at...). O atalho /ship vai direto para shipped e grava o rastreio de uma vez.

Ciclo da retirada

awaiting_preparation→ready→picked_up
statusSignificado
awaiting_preparationO cliente pediu e escolheu retirar. O seller precisa separar o pedido.
readySeparado. O cliente recebeu o código de 6 dígitos (e um QR) e pode buscar.
picked_upCódigo conferido no balcão. Final.
expiredPassou do prazo (expires_at) sem retirada. O estoque reservado volta. Final.
cancelledCancelada pelo seller ou pela loja. O estoque volta. Final.

Conceitos-chave

Quem é o dono do pedido

As rotas só devolvem registros do seller do token. Uma expedição ou retirada de outro seller responde 404, como se não existisse. Em carrinhos com vários sellers, a retirada é aberta no pedido pai, mas cada seller a enxerga pelo seu sub-pedido.

Dinheiro e datas

Taxas em inteiros centavos; datas em RFC 3339 (UTC). IDs são UUID.

Privilégios

As rotas de retirada exigem um destes privilégios do seller (o dono da conta sempre passa): vendor_manage_orders, vendor_orders, vendor_view_orders, vendor_manage_returns, vendor_manage_fulfillments, vendor_manage_reviews, vendor_manage_messages ou vendor_manage_live. As rotas de expedição e de transportadoras dependem apenas do módulo estar ligado.

Endpoints

MétodoCaminhoPara que serveAutenticação
GET/api/v1/vendor/fulfillmentsLista as expedições do seller.vendor
GET/api/v1/vendor/fulfillments/{id}Mostra uma expedição.vendor
PUT/api/v1/vendor/fulfillments/{id}Altera rastreio, etapa ou notas.vendor
POST/api/v1/vendor/fulfillments/{id}/shipMarca como enviada com o rastreio.vendor
GET/api/v1/vendor/fulfillments/statsContagens por etapa e tempos médios.vendor
GET/api/v1/vendor/fulfillments/feesLista as taxas de expedição cobradas.vendor
GET/api/v1/vendor/pickupsLista as retiradas do seller.vendor
POST/api/v1/vendor/pickups/{id}/readyMarca a retirada como pronta.vendor
POST/api/v1/vendor/pickups/{id}/confirmConfirma a retirada pelo código.vendor
POST/api/v1/vendor/pickups/{id}/cancelCancela a retirada.vendor
GET/api/v1/vendor/shipment-carriersLista as transportadoras ativas da loja.vendor

Erros comuns

  1. Mandar a letra em vez da palavra em status (S em vez de shipped): invalid status.
  2. Pular etapas. De pending para delivered dá invalid transition from pending to delivered.
  3. Tentar alterar expedição da plataforma. 403 quando fulfilled_by é marketplace.
  4. Confiar no filtro status com palavra errada. status=entregue não dá erro: vira pending.
  5. Digitar o código da retirada sem checar o limite. 5 erros seguidos travam por 15 minutos (429).
  6. Confirmar uma retirada que não está ready. Marque como pronta antes, ou dá 400.
  7. Esperar ver o código da retirada na lista. O código é só do cliente; o seller o recebe pessoalmente.
  8. Esperar [] em fees da lista de taxas. Sem taxas o campo vem null.

Próximos passos

Marcar como enviada
Rastreio e e-mail ao cliente.
Retiradas
Fila de pedidos para retirar.
Formas de envio
Como o cliente escolhe a entrega.
Anterior
Testar um endereço
Próxima
Listar e consultar expedições
Nesta página
  • Como funciona
  • Ciclo da expedição
  • Ciclo da retirada
  • Conceitos-chave
  • Quem é o dono do pedido
  • Dinheiro e datas
  • Privilégios
  • Endpoints
  • Erros comuns
  • Próximos passos