Pedidos: rotas sem versão e app do seller

A seção Pedidos documenta as rotas /api/v1.0/orders.... A plataforma antiga, porém, respondia também sem o prefixo de versão (/api/orders), e os conectores de ERP, o app móvel do seller e os apps de terceiros foram escritos contra esses endereços. Esta seção cobre o que sobrou: as formas sem versão, os ganchos de ERP (extra_order_fields, orders_ext, order_limit), as rotas do app do seller e o rastreio por token de app.

A regra de ouro: o código é o mesmo. GET /api/orders e GET /api/v1.0/orders chamam o mesmo tratamento e devolvem o mesmo pedido; o que muda é a forma dos ids. Por isso as páginas desta seção são curtas e apontam para as páginas de Pedidos quando a regra é a mesma.

Como funciona

Um conector de ERP típico usa as formas sem versão assim:

1. Buscar os pedidos

   Coleção de pedidos lista os pedidos por status e data. Guarde o order_id decimal de cada um.

2. Ler e alterar um pedido

   Um pedido devolve o detalhe, aceita alterações de dados e cancela. Itens, reembolso e histórico cobrem as consultas auxiliares.

3. Devolver dados do ERP

   Ganchos de ERP grava o número do pedido no ERP, a nota fiscal e o limite de crédito do cliente.

4. Acompanhar o envio

   Rastreio por token de app deixa um sistema externo consultar o rastreio sem usuário administrador.

Conceitos-chave

Ids decimais na forma sem versão

Em /api/... o servidor troca cada UUID de entidade por um número decimal de até 32 bits, em toda a resposta, e aceita esses números na entrada (caminho, consulta e corpo). É só uma outra grafia do mesmo registro: o UUID continua sendo aceito. Não misture as duas formas no mesmo cliente. A tradução vale para order_id, user_id, product_id, company_id, item_id e outros campos terminados em _id; payment_id (um código) e status não são traduzidos.

A tradução do caminho só vale para alguns nomes de recurso (orders, extra_order_fields, entre outros). Em orders_ext/{id} ela não vale; em vendor_order/{id} e vn_order_api/{id} também não: veja as páginas.

Rotas que só respondem 405

PUT /api/orders (sem id) e POST /api/orders/{id} (com id) não executam nada. Elas devolvem 405 Method Not Allowed com o cabeçalho Allow e corpo vazio, para que um cliente que tente o método errado receba uma resposta clara em vez de 404. Para criar, use POST /api/orders; para alterar, PUT /api/orders/{id}.

Os três públicos desta seção

Dinheiro, datas e status

Dinheiro é string decimal ("52.66"). Datas são Unix timestamp (segundos) nas rotas de pedido e RFC 3339 no app do seller. O status das rotas de pedido é uma letra do cadastro da loja (O, P, C...); no app do seller vem o código longo (shipped) e a letra em status_code.

Endpoints

Erros comuns

• Misturar /api/orders com ids UUID em uma parte do cliente e decimais em outra. Funciona, mas dificulta a conciliação. Escolha uma forma.
• Usar PUT /api/orders para alterar. Sem o id no caminho a resposta é 405. O id vai na URL: PUT /api/orders/{id}.
• Mudar status junto com outros campos no PUT /api/orders/{id}. O status passa por uma tabela antiga de 7 letras e pode virar pending. Mande o status sozinho (veja Alterar o status).
• Reenviar extra_order_fields. Cada envio cria outro registro; a chamada não é idempotente.
• Usar orders_ext sem o status U no cadastro de status da loja: responde 409.
• No app do seller, ler só o HTTP. Toda resposta é 200; o resultado está em data.success.
• Usar um JWT de usuário nas rotas de rastreio. Elas aceitam só token de app e respondem 401 app_token_required.

Próximos passos