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

Pedidos do seller

Como o seller (lojista) consulta e atende os pedidos dele: status, remessas, rastreio, cancelamentos, devoluções, fatura e oferta pós-compra.

Quando um cliente compra, o pedido fica com a loja e, se a compra tem produtos de mais de um seller (lojista), a plataforma cria um pedido pai (o que o cliente vê) e um sub-pedido por seller. Para o seller, "pedido" é sempre o sub-pedido dele: ele consulta, move de status, despacha e cancela só o que é dele. Estas rotas, sob /api/v1/vendor, são a operação diária de atendimento: ver o que chegou, despachar com rastreio, decidir cancelamentos e devoluções, mandar a fatura e configurar a oferta de pós-compra.

Pontos principais
  • O id de um pedido nestas rotas é o do sub-pedido do seller. O id do pedido pai ou de outro seller responde 403 you do not have access to this order.
  • Dinheiro é inteiro em centavos (22500 = R$ 225,00). A exceção é a exportação, que escreve valores decimais (225.00) em arquivo.
  • O status do pedido é gravado como letra (P), mas o seller envia o nome por extenso (shipped) ao mudar o status.
  • Criar uma remessa não muda o status do pedido: são duas chamadas, nessa ordem (remessa, depois status).
  • Usuário de equipe do seller que é representante comercial só enxerga os pedidos da carteira dele. O dono da loja enxerga tudo.
  • Seller com cadastro ainda em análise recebe 403 vendor_pending_review em tudo isto.

Como funciona

O pedido do seller, do início ao fim

Pendente→Processando→Enviado→Entregue

O caminho mais comum. Os desvios são Cancelado, Em espera, Falho e Reembolsado. A tabela mostra os status da instalação padrão (cada loja pode renomear, esconder e criar os seus):

codeLetraQuando aconteceO seller pode definir?
pendingORecebido, aguardando pagamento ou confirmação.Só reabrindo um cancelado
processingPPagamento aprovado ou em preparação.Só reabrindo um cancelado
paidAPagamento confirmado (opcional).Não
on_holdHParado, à espera de algo.Só reabrindo um cancelado
failedFPagamento recusado.Não
shippedSO pacote saiu.Sim
deliveredCO cliente recebeu.Sim
completedKConcluído.Não
cancelledICancelado (o estoque volta).Sim, se ainda não enviado
refundedRDinheiro devolvido.Não
chargebackZO cliente contestou no cartão.Não

Fluxo típico de atendimento

  1. Ver o que chegou
    Listar pedidos com status=processing (pedidos pagos) e abrir cada um para ler itens e endereço.
  2. Despachar
    Criar a remessa com transportadora, código de rastreio e itens. O cliente recebe o e-mail de envio.
  3. Marcar como enviado
    Mudar o status para shipped, e depois para delivered quando entregar.
  4. Tratar exceções
    Decidir cancelamentos pedidos pelo cliente e devoluções.

Conceitos importantes

Recursos opcionais da loja

O acompanhamento depende de um módulo que a loja precisa ter ligado. Desligado, a rota responde 403 com {"error":"module_disabled","module":"..."} ou 404:

MóduloRotas
order-status-flow (fluxo de status e acompanhamento)order-tracking, order-tracking/{id}, e PUT .../shipments/{shipmentId}/tracking

Quem pode o quê dentro do seller

Um usuário de equipe do seller pode ter só leitura de pedidos ou também escrita. As rotas de escrita sensíveis (decidir cancelamento, enviar fatura) pedem o privilégio de gerenciar pedidos; as demais aceitam também o de ver pedidos. As rotas de devolução e de oferta pós-compra não conferem privilégio fino: qualquer usuário do seller as acessa.

Escopo de representante

Quando o usuário de equipe é um representante comercial ativo e não é o dono da loja, listas e detalhes mostram apenas os pedidos atribuídos a ele ou de clientes da carteira dele. Fora disso, 403 you do not have access to this order.

Datas

RFC 3339 em UTC. A exportação escreve a data no horário de Brasília.

Endpoints

MétodoCaminhoPara que serveAutenticação
GET/api/v1/vendor/ordersLista os pedidos do seller.seller
GET/api/v1/vendor/orders/{id}Detalha um pedido.seller
GET/api/v1/vendor/orders/exportExporta pedidos em CSV ou planilha.seller
PUT/api/v1/vendor/orders/{id}/statusMuda o status do pedido.seller
GET/api/v1/vendor/orders/{id}/allowed-transitionsPróximos status possíveis.seller
GET/api/v1/vendor/orders/{id}/shipmentsLista as remessas do pedido.seller
POST/api/v1/vendor/orders/{id}/shipmentsCria uma remessa.seller
PUT/api/v1/vendor/orders/{id}/shipments/{shipmentId}/trackingAtualiza o rastreio de uma remessa.seller
GET/api/v1/vendor/order-trackingAcompanhamento dos pedidos do seller.seller
GET/api/v1/vendor/order-tracking/{id}Acompanhamento de um pedido.seller
GET/api/v1/vendor/order-cancellationsFila de pedidos de cancelamento.seller
POST/api/v1/vendor/order-cancellations/{id}/approveAprova um cancelamento.seller
POST/api/v1/vendor/order-cancellations/{id}/rejectRecusa um cancelamento.seller
GET/api/v1/vendor/returnsLista as devoluções do seller.seller
GET/api/v1/vendor/returns/{id}Detalha uma devolução.seller
PUT/api/v1/vendor/returns/{id}/statusAprova, recebe ou recusa uma devolução.seller
POST/api/v1/vendor/orders/{id}/invoice/sendEnvia a fatura em PDF por e-mail.seller
GET/api/v1/vendor/post-purchase-rulesLista as regras de oferta pós-compra.seller
POST/api/v1/vendor/post-purchase-rulesCria uma regra.seller
PUT/api/v1/vendor/post-purchase-rules/{id}Altera uma regra.seller
DELETE/api/v1/vendor/post-purchase-rules/{id}Exclui uma regra.seller

Erros comuns

  • Mandar a letra do status (S) em vez do nome (shipped). Na mudança de status do seller, a letra é recusada com 403 vendor_status_not_allowed quando a loja não usa fluxo de status próprio.
  • Achar que criar a remessa envia o pedido. A remessa só avisa o cliente; o status continua processing até você mudá-lo.
  • Usar o id do pedido pai. O seller só opera o sub-pedido dele; o pai responde 403.
  • Decidir cancelamento pelo id do pedido. approve e reject recebem o id da solicitação (campo id da fila), não o order_id.
  • Pedir a lista de cancelamentos sem status esperando todas. Sem status vale pending.
  • Passar date_to=2026-10-11 na exportação esperando o dia inteiro. Na exportação a data final é o instante 00:00 daquele dia; use 2026-10-12 ou um horário.
  • Esquecer o módulo. O acompanhamento responde 403 module_disabled quando a loja não os ligou.

Próximos passos

Consultar pedidos
Lista, detalhe e exportação.
Mudar o status
Quais mudanças o seller pode fazer.
Remessas e rastreio
Despache com código de rastreio.
Cancelamentos
Decida os pedidos de cancelamento.
Anterior
Regras por categoria
Próxima
Consultar pedidos
Nesta página
  • Como funciona
  • O pedido do seller, do início ao fim
  • Fluxo típico de atendimento
  • Conceitos importantes
  • Recursos opcionais da loja
  • Quem pode o quê dentro do seller
  • Escopo de representante
  • Datas
  • Endpoints
  • Erros comuns
  • Próximos passos