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

Pedidos

Como funcionam os pedidos da Venddor, o ciclo de status, o modelo de sub-pedidos e o mapa de todas as rotas.

Um pedido é o registro de uma compra: quem comprou, o que, por quanto, como vai pagar, para onde vai e em que etapa está. Ele nasce no checkout da loja (ou por esta API, quando a venda vem de um ERP, de um PDV ou do atendimento) e acompanha toda a vida da compra: pagamento, separação, envio, entrega, devolução.

Esta seção documenta a API de pedidos (/api/v1/admin/orders...). Valores em centavos, datas RFC 3339, ids UUID e todas as operações do ciclo da venda: remessas, faturas, reembolsos, lote e fluxo de status.

Pontos-chave
  • O status do pedido é uma letra (O, P, S...), mas a letra não é a inicial do nome e cada loja tem o seu cadastro de status. Leia o cadastro da loja em vez de assumir (Status de pedido).
  • Compras com produtos de mais de um seller viram um pedido pai e um sub-pedido por seller, e tudo aparece na mesma lista (Sub-pedidos).
  • Dinheiro é inteiro em centavos (4990 = R$ 49,90) e datas são RFC 3339.
  • "Apagar" um pedido normalmente é cancelar. A exclusão permanente existe, mas é irreversível (Cancelar e excluir).

Como funciona

O ciclo de vida de um pedido

Pendente→Processando→Enviado→Entregue→Concluído

O caminho mais comum numa loja padrão. Pago é um passo opcional entre pendente e enviado (muitos gateways levam o pedido direto a Processando quando o pagamento é aprovado). Cancelado, Falho, Em espera, Reembolsado e Chargeback são os desvios.

codeLetraQuando acontece
pendingOO pedido foi recebido e aguarda pagamento ou confirmação.
processingPPagamento aprovado ou pedido em preparação.
paidAPagamento confirmado (passo opcional).
on_holdHParado por alguém da loja, à espera de algo.
failedFPagamento recusado. O estoque volta.
shippedSO pacote saiu da loja.
deliveredCO cliente recebeu.
completedKConcluído, sem pendências de pós-venda.
cancelledICancelado. O estoque volta. Pode ser reaberto.
refundedRDinheiro devolvido. Estado final.
chargebackZO cliente contestou o pagamento no cartão.

Essa é a instalação padrão. Cada loja pode renomear, esconder e criar status, e mudar letras. As regras de quais mudanças são permitidas estão em Alterar o status.

O fluxo típico de uma integração (ERP, WMS)

  1. Buscar pedidos novos

    Chame Listar pedidos filtrando pelo status inicial e pela data do último pedido que você processou. Guarde o id de cada pedido: ele é a chave para todo o resto.

  2. Ler o detalhe

    Consultar pedido devolve itens, endereços, pagamento e sub-pedidos. Importe no seu sistema.

  3. Confirmar a importação

    Registre a importação no pedido, com uma observação interna ou o código do pedido no ERP (Alterar pedido).

  4. Despachar

    Crie a remessa com o código de rastreio e depois mude o status para enviado. O cliente recebe o e-mail de envio.

  5. Tratar exceções

    Cancelamentos pedidos pelo cliente (Cancelamentos), devoluções e reembolsos (Reembolsos).

Conceitos-chave

Formato da API

ItemComo a API trabalha
AutenticaçãoBearer JWT de um usuário administrador (POST /api/v1/auth/login)
PermissãoPrivilégios view_orders (leitura) e manage_orders (escrita)
IdsUUID em string
DinheiroInteiro em centavos: 4990
DataRFC 3339 em UTC (created_at)
StatusLetra em status e código em status_text: "P", "processing"
Lista{"orders":[...],"total","page","per_page","total_pages"}
Erros{"error":"...","detail":"..."}

Autenticação

Faça login (POST /api/v1/auth/login com {"email","password"}) e use access_token como Bearer. O login tem limite de requisições (429): guarde o token e reaproveite-o até expirar. Cada rota exige um privilégio do usuário; sem ele a resposta é 403 com o privilégio que faltou.

Ids

Todo id é um UUID em string (a8a3c7a3-5f15-45a8-a385-4f20fbf8b722), no caminho, na query e no corpo.

Dinheiro, datas e fuso

Todo valor é inteiro em centavos (22500 = R$ 225,00), e cada pedido traz também campos *_str em decimal. Datas são RFC 3339 em UTC. O filtro de data por dia (date_from/date_to) trabalha em dias inteiros.

Pedido pai e sub-pedidos

Uma compra com itens de sellers diferentes gera um pedido pai (o que o cliente vê) e um sub-pedido por seller (o que o seller cuida). O pai não deve ser alterado à mão: o status dele é calculado a partir dos filhos. Veja Sub-pedidos.

Cancelar, reembolsar e excluir

Cancelar muda o status e devolve o estoque; se o pedido já estava pago, a plataforma estorna o pagamento no gateway antes de cancelar (ou você reembolsa). Reembolsar devolve o pagamento. Excluir remove o registro. São três coisas diferentes: Cancelar e excluir, Reembolsos.

Recursos opcionais da loja

Algumas rotas dependem de um recurso que a loja precisa ter ligado: o fluxo de status personalizado e o acompanhamento ao cliente (order-status-flow), custo e lucro, pagamentos diretos. Quando desligado, a rota responde 403 {"error":"module_disabled","module":"..."}. As páginas indicam quais rotas são assim.

Endpoints

Auth: Admin é o administrador (Bearer).

MétodoRotaO que fazAuthPágina
GET/api/v1/admin/ordersLista pedidosAdminListar pedidos
GET/api/v1/admin/orders/{id}Consulta um pedidoAdminConsultar pedido
GET/api/v1/admin/orders/{id}/dataRegistros auxiliares do pedidoAdminConsultar pedido
POST/api/v1/admin/ordersCria pedidoAdminCriar pedido
PUT/api/v1/admin/orders/{id}Altera campos simplesAdminAlterar pedido
PUT/api/v1/admin/orders/{id}/editEdição completaAdminAlterar pedido
PUT/api/v1/admin/orders/{id}/statusMuda o statusAdminAlterar o status
GET/api/v1/admin/orders/{id}/allowed-transitionsDestinos de status permitidosAdminAlterar o status
POST/api/v1/admin/orders/{id}/force-statusForça uma mudança de statusAdminAlterar o status
POST/api/v1/admin/orders/{id}/sync-statusRecalcula o status do pedido paiAdminAlterar o status
GET/api/v1/admin/orders/{id}/timelineLinha do tempoAdminHistórico do pedido
DELETE/api/v1/admin/orders/{id}Cancela o pedidoAdminCancelar e excluir
DELETE/api/v1/admin/orders/{id}/permanentExclui de forma permanenteAdminCancelar e excluir
POST/api/v1/admin/orders/bulkAção em até 100 pedidosAdminAções em lote
GET/api/v1/admin/orders/{id}/sub-ordersSub-pedidos de um pedido paiAdminSub-pedidos
GET/api/v1/admin/orders/{id}/parentPedido pai de um sub-pedidoAdminSub-pedidos
GET/api/v1/admin/orders/{id}/shipmentsLista as remessasAdminRemessas e rastreio
POST/api/v1/admin/orders/{id}/shipmentsCria remessaAdminRemessas e rastreio
PUT/api/v1/admin/orders/{id}/shipments/{shipmentId}Atualiza remessaAdminRemessas e rastreio
PUT/api/v1/admin/orders/{id}/shipments/{shipmentId}/trackingDados públicos de rastreioAdminRemessas e rastreio
GET/api/v1/admin/orders/{id}/tracking-eventsEventos da transportadoraAdminRastreio da transportadora
GET/api/v1/admin/order-trackingAcompanhamento por CNPJAdminRastreio da transportadora
GET/api/v1/admin/order-tracking/{id}Acompanhamento de um pedidoAdminRastreio da transportadora
GET/api/v1/admin/shipment-carriersTransportadoras ativasAdminRastreio da transportadora
GET/api/v1/admin/orders/refundsLista reembolsosAdminReembolsos
GET/api/v1/admin/orders/pending-refundsEstornos pendentesAdminReembolsos
POST/api/v1/admin/orders/{id}/resolve-refundResolve um estorno pendenteAdminReembolsos
GET/api/v1/admin/order-cancellationsSolicitações de cancelamentoAdminCancelamentos
POST/api/v1/admin/order-cancellations/{id}/approveAprova o cancelamentoAdminCancelamentos
POST/api/v1/admin/order-cancellations/{id}/rejectRecusa o cancelamentoAdminCancelamentos
GET/api/v1/admin/orders/{id}/invoiceFatura em JSON ou HTMLAdminFatura e NF-e
GET/api/v1/admin/orders/{id}/invoice.pdfFatura em PDFAdminFatura e NF-e
POST/api/v1/admin/orders/{id}/invoice/sendEnvia a fatura por e-mailAdminFatura e NF-e
POST/api/v1/admin/orders/bulk-invoice.pdfPDF com várias faturasAdminFatura e NF-e
GET/api/v1/admin/orders/{orderId}/nfeNF-e do pedidoAdminFatura e NF-e
GET/api/v1/admin/orders/{id}/packing-slipRomaneio (JSON)AdminRomaneio
GET/api/v1/admin/orders/{id}/packing-slip.pdfRomaneio (PDF)AdminRomaneio
GET/api/v1/admin/orders/{id}/shipments/{shipmentId}/packing-slipRomaneio da remessa (JSON)AdminRomaneio
GET/api/v1/admin/orders/{id}/shipments/{shipmentId}/packing-slip.pdfRomaneio da remessa (PDF)AdminRomaneio
GET/api/v1/admin/orders/{id}/credit-noteNota de créditoAdminNota de crédito
POST/api/v1/admin/orders/{id}/credit-noteGera a nota de créditoAdminNota de crédito
GET/api/v1/admin/orders/{id}/credit-note.pdfNota de crédito (PDF)AdminNota de crédito
GET/api/v1/admin/orders/{id}/credit-auditAuditoria de créditoAdminDados financeiros
GET/api/v1/admin/orders/{id}/payment-statisticsHistórico de pedidos do compradorAdminDados financeiros
GET/api/v1/admin/orders/{orderID}/payment-splitsRateio do pagamentoAdminDados financeiros
GET/api/v1/admin/orders/{id}/custo-lucroCusto e lucroAdminDados financeiros
GET/api/v1/admin/order-statusesLista os statusAdminStatus de pedido
GET/api/v1/admin/order-statuses/{code}Consulta um statusAdminStatus de pedido
POST/api/v1/admin/order-statusesCria um statusAdminStatus de pedido
PUT/api/v1/admin/order-statuses/{code}Altera um statusAdminStatus de pedido
DELETE/api/v1/admin/order-statuses/{code}Remove um statusAdminStatus de pedido
GET, PUT/api/v1/admin/order-statuses/{code}/descriptionsTraduções do statusAdminTraduções dos status
GET, PUT/api/v1/admin/order-status-flowLê e salva o fluxo de statusAdminFluxo de status
POST/api/v1/admin/order-status-flow/validateValida um fluxoAdminFluxo de status
POST/api/v1/admin/order-status-flow/templates/{key}Aplica um modelo de fluxoAdminFluxo de status
GET/api/v1/admin/order-status-blockBloqueio de status (compatibilidade)AdminFluxo de status

Erros comuns

  1. Presumir que a letra é a inicial do nome: C é entregue (não cancelado), cancelado é I. Leia o cadastro em Status de pedido.
  2. Achar que criar remessa envia o pedido. A remessa grava o rastreio e avisa o cliente, mas só mudar o status move o pedido para enviado.
  3. Tratar pai e sub-pedidos como pedidos independentes ao somar vendas. A lista traz os dois; somar tudo conta o dinheiro em dobro. Ignore itens com parent_id, ou ignore os pais, mas nunca os dois.
  4. Enviar dinheiro em decimal. Os valores são centavos inteiros (4990), não "49.90".
  5. Pular etapas ao mudar o status. Entre os status padrão só valem as transições permitidas; consulte Alterar o status.
  6. Repetir POST /api/v1/admin/orders depois de um timeout sem idempotency_key. Isso cria um pedido duplicado e baixa o estoque duas vezes.

Próximos passos

Listar pedidos
Busque pedidos por status, data, cliente e mais.
Alterar o status
As regras de transição e o que cada mudança dispara.
Criar pedido
Registre uma venda de ERP, PDV ou atendimento.
Remessas e rastreio
Despache, rastreie e avise o cliente.
Anterior
Perguntas frequentes
Próxima
Listar pedidos
Nesta página
  • Como funciona
  • O ciclo de vida de um pedido
  • O fluxo típico de uma integração (ERP, WMS)
  • Conceitos-chave
  • Formato da API
  • Autenticação
  • Ids
  • Dinheiro, datas e fuso
  • Pedido pai e sub-pedidos
  • Cancelar, reembolsar e excluir
  • Recursos opcionais da loja
  • Endpoints
  • Erros comuns
  • Próximos passos