Pedidos

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 como operar pedidos pela API compatível com a Venddor 1.0 (/api/v1.0/orders...): o contrato da Venddor 1.0, para clientes escritos para a plataforma antiga. As respostas têm valores em string decimal, datas em Unix timestamp e status em letra.

Como funciona

O ciclo de vida de um pedido

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.

Essa é a instalação padrão. Cada loja pode renomear, esconder e criar status, e mudar letras. Como mudar o status está 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 e devolver a nota

   Grave o código do pedido no ERP e a nota fiscal no pedido (Sincronização com ERP) ou, para observações e rastreio, use Alterar pedido.

4. Despachar

   Grave o código de rastreio com Alterar pedido (tracking_number) e depois mude o status para enviado. O cliente recebe o e-mail de envio, se o status estiver configurado para isso.

5. Tratar exceções

   Cancelamentos (Cancelar pedido), devoluções e reembolsos (Reembolsos).

Conceitos-chave

Formato da API

Autenticação

Um administrador gera uma chave de API para o próprio usuário no painel e você envia Authorization: Basic base64(e-mail:chave) em toda chamada. Authorization: Bearer <JWT> também funciona. Usuário que não é administrador recebe 403. A mesma rota responde com e sem /v1.0 (/api/orders e /api/v1.0/orders), com maiúsculas ou minúsculas e com barra no final.

Token de app. Para apps de terceiros, sem usuário, veja Pedidos por token de app.

Ids

Em /api/v1.0, todo id é um UUID em string (a8a3c7a3-5f15-45a8-a385-4f20fbf8b722). Na forma sem versão (/api/orders), pensada para clientes que esperam o id inteiro da Venddor 1.0, os ids saem como números decimais dentro de uma string ("681822115"), derivados do UUID. Eles também são aceitos na entrada (caminho, query e corpo). Não misture as duas formas no mesmo cliente: escolha uma. O UUID é aceito nas duas rotas.

Dinheiro, datas e fuso

Todo valor é string decimal com ponto e duas casas ("225.00"), exceto o amount do refund, que é inteiro em centavos. As datas são Unix timestamp em segundos (UTC). O filtro de data por dia (time_from/time_to) trabalha em dias inteiros.

Pedido pai e pedidos filhos

Uma compra com itens de sellers diferentes gera um pedido pai (o que o cliente vê) e um 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. Os filhos apontam para o pai em parent_order_id e usam o número do pai mais -V1, -V2... O detalhe do pai (GET /orders/{id}) informa is_parent_order: "Y" e suborder_ids.

Cancelar, reembolsar e excluir

Cancelar muda o status e devolve o estoque; o dinheiro não volta sozinho, só com o reembolso. Reembolsar devolve o pagamento. O DELETE desta API cancela, não apaga o registro. São coisas diferentes: Cancelar pedido, Reembolsos.

Endpoints

Auth: Admin é o administrador (Basic ou Bearer). Seller é o usuário do seller. App é o token de app.

Duas rotas da API 1.0 existem só para responder 405 (Method Not Allowed): PUT /api/v1.0/orders (sem id) e POST /api/v1.0/orders/{id}. Elas não fazem parte da integração.

Erros comuns

1. Filtrar a lista por nome de status (status=shipped). A tabela antiga mapeia nomes longos para outras letras (shipped vira P, refunded vira D) e o filtro devolve pedidos errados ou nenhum. Filtre pela letra.
2. Mudar o status com um nome longo ({"status":"shipped"}). Nomes fora da tabela antiga viram pending sem erro e o pedido volta para pendente. Mande a letra do cadastro de status da loja.
3. Presumir que a letra é a inicial do nome: C é entregue (não cancelado), cancelado é I. Peça o cadastro da loja ao administrador (padrão na tabela de status da home da seção).
4. Tratar pai e filhos como pedidos independentes ao somar vendas. A lista traz os dois; somar tudo conta o dinheiro em dobro. Ignore itens com parent_order_id, ou ignore os pais, mas nunca os dois.
5. Enviar dinheiro no formato errado. Os valores são string decimal ("49.90"). No refund, o amount do corpo é inteiro em centavos.
6. Esperar que cancelar estorne o pagamento. O cancelamento só muda o status e devolve o estoque; o reembolso é uma chamada à parte.

Próximos passos