Sua primeira requisição
Tutorial ponta a ponta: autenticar, listar produtos, criar um cliente e criar um pedido.
Neste tutorial você faz o ciclo mínimo de uma integração de vendas: entra na loja, escolhe um produto, cadastra um comprador e registra um pedido para ele. No final, você apaga o que criou. Leva poucos minutos e usa só as rotas que quase toda integração precisa.
Antes de começar
Você precisa de:
- A URL base da loja (
$BASE_URL, veja Endereço e ambientes). - O e-mail e a senha de um usuário administrador da loja.
- Um terminal com
curlejq, ou Node.js 18 ou superior, ou Python comrequests.
O fluxo
- Autenticar
Troque e-mail e senha por um
access_token(Autenticação). Todos os passos seguintes enviam esse token. - Listar produtos
Busque um produto pelo nome (
search). A lista é paginada:per_pagedefine o tamanho da página e a resposta traztotaletotal_pages.200Produtos encontradosGuarde o
iddo produto (UUID). Opriceestá em centavos:11500é R$ 115,00. O campoprice_strtraz o mesmo valor como string decimal. A resposta real tem muitos outros campos; aqui estão só os principais. - Escolher o frete e a forma de pagamento
Um pedido de produto físico precisa de um método de frete, e todo pedido precisa do código da forma de pagamento. Leia os dois cadastros da loja e guarde o
iddo frete e ocodedo pagamento.As duas respostas têm a lista dentro de
methods. Em cada item de frete você usaid; em cada forma de pagamento,code(por exemplopix,boletooupagamento-na-entrega). - Criar um cliente
POST /api/v1/admin/userscadastra o comprador.email,passwordefirst_namesão obrigatórios. Comuser_typeigual acustomer, ele é um comprador (e não um administrador).201Cliente criadoGuarde o
id(UUID). Se o e-mail já existir, a resposta é400com{"error":"email already registered"}. - Criar o pedido
Junte tudo: o cliente, os itens, o endereço de entrega, o frete e a forma de pagamento. Envie sempre um
idempotency_keyseu: se a chamada falhar por timeout e você repetir, a plataforma devolve o mesmo pedido em vez de criar outro.201Pedido criado (resumo)O pedido nasce com
statusO(pendente). O preço vem do catálogo, não do seu corpo, e o frete é recalculado pela plataforma: R$ 115,00 de produto mais R$ 5,00 de frete dão12000centavos. Repita a mesma chamada com o mesmoidempotency_keye você recebe o mesmo pedido de volta (mesmoid), sem duplicar nada.
Parabéns: você autenticou, leu o catálogo e gravou um cliente e um pedido. Para o que fazer a seguir com o pedido (alterar status, criar remessa, cancelar), veja Pedidos.
Limpeza
Num pedido de verdade, o caminho normal é cancelar (DELETE /api/v1/admin/orders/{id}), que mantém o registro e devolve o estoque. Para um pedido de teste que nunca deveria ter existido, a exclusão permanente remove o registro por completo. Ela é irreversível: use só em dados de teste. Apague o pedido antes do cliente.
As duas respostas são 200: {"deleted": true, "permanent": true} e {"message": "user deleted"}. As variações de cancelamento e a exclusão permanente estão em Cancelar e excluir.
Erros comuns neste fluxo
400 at least one item is required: a listaitemsveio vazia ou ausente.401 invalid or expired token: o token venceu; renove ou faça login de novo.403 insufficient privileges: o usuário não tem permissão de gerenciar pedidos ou usuários.400no frete: produto físico semshipping_method_id.priceparece 100 vezes maior: o preço é em centavos, não em reais.429: muitos logins em pouco tempo. Guarde o token (Limites e boas práticas).