Sua primeira requisição

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 curl e jq, ou Node.js 18 ou superior, ou Python com requests.

export BASE_URL="https://minhaloja.io.venddor.com.br"

O fluxo

1. Autenticar

   Troque e-mail e senha por um access_token (Autenticação). Todos os passos seguintes enviam esse token.

   cURLJavaScriptPython

   bash

   TOKEN=$(curl -s -X POST "$BASE_URL/api/v1/auth/login" \
     -H "Content-Type: application/json" \
     -d '{"email": "integracao@minhaloja.com.br", "password": "sua-senha"}' \
     | jq -r .access_token)

2. Listar produtos

   Busque um produto pelo nome (search). A lista é paginada: per_page define o tamanho da página e a resposta traz total e total_pages.

   cURLJavaScriptPython

   bash

   curl -s "$BASE_URL/api/v1/admin/products?search=Slim%20Rosa&per_page=2" \
     -H "Authorization: Bearer $TOKEN"

   200Produtos encontrados

   json

   {
     "products": [
       {
         "id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
         "name": "Notebook Slim Rosa 02373",
         "sku": "SD-002373",
         "price": 11500,
         "price_str": "115.00",
         "quantity": 51,
         "status": "A",
         "created_at": "2026-05-27T12:47:04Z"
       }
     ],
     "total": 43,
     "page": 1,
     "per_page": 2,
     "total_pages": 22
   }

   Guarde o id do produto (UUID). O price está em centavos: 11500 é R$ 115,00. O campo price_str traz o mesmo valor como string decimal. A resposta real tem muitos outros campos; aqui estão só os principais.

3. 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 id do frete e o code do pagamento.

   bash

   curl -s "$BASE_URL/api/v1/admin/shipping-methods" -H "Authorization: Bearer $TOKEN"
   curl -s "$BASE_URL/api/v1/admin/payment-methods"  -H "Authorization: Bearer $TOKEN"

   As duas respostas têm a lista dentro de methods. Em cada item de frete você usa id; em cada forma de pagamento, code (por exemplo pix, boleto ou pagamento-na-entrega).

4. Criar um cliente

   POST /api/v1/admin/users cadastra o comprador. email, password e first_name são obrigatórios. Com user_type igual a customer, ele é um comprador (e não um administrador).

   cURLJavaScriptPython

   bash

   CUSTOMER_ID=$(curl -s -X POST "$BASE_URL/api/v1/admin/users" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{
       "email": "maria.souza@example.com",
       "password": "Senha#12345",
       "first_name": "Maria",
       "last_name": "Souza",
       "user_type": "customer"
     }' | jq -r .id)

   201Cliente criado

   json

   {
     "id": "9781e019-a0c1-4cc5-bbd2-16ef86e1c999",
     "email": "maria.souza@example.com",
     "user_type": "customer",
     "status": "A",
     "first_name": "Maria",
     "last_name": "Souza",
     "language": "pt-BR",
     "currency": "BRL",
     "person_type": "F",
     "created_at": "2026-10-11T20:50:31.04207Z"
   }

   Guarde o id (UUID). Se o e-mail já existir, a resposta é 400 com {"error":"email already registered"}.

5. 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_key seu: se a chamada falhar por timeout e você repetir, a plataforma devolve o mesmo pedido em vez de criar outro.

   cURLJavaScriptPython

   bash

   curl -s -X POST "$BASE_URL/api/v1/admin/orders" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{
       "customer_id": "9781e019-a0c1-4cc5-bbd2-16ef86e1c999",
       "payment_method": "pagamento-na-entrega",
       "shipping_method_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
       "idempotency_key": "tutorial-pedido-0001",
       "items": [
         { "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035", "quantity": 1 }
       ],
       "shipping_address": {
         "first_name": "Maria", "last_name": "Souza",
         "address_line1": "Avenida Paulista, 1000",
         "city": "São Paulo", "state": "SP",
         "postal_code": "01310-100", "country": "BR",
         "phone": "11999990000"
       }
     }'

   201Pedido criado (resumo)

   json

   {
     "order": {
       "id": "819887d3-069f-4f33-91fa-ea8693d3b5c9",
       "order_number": "PEDIDO-20261011-0007",
       "customer_id": "9781e019-a0c1-4cc5-bbd2-16ef86e1c999",
       "subtotal": 11500,
       "shipping_total": 500,
       "tax_total": 0,
       "discount_total": 0,
       "total": 12000,
       "currency": "BRL",
       "payment_method": "pagamento-na-entrega",
       "payment_status": "pending",
       "status": "O",
       "status_text": "pending",
       "created_at": "2026-10-11T20:50:36.891371777Z"
     },
     "items": [
       {
         "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
         "product_name": "Notebook Slim Rosa 02373",
         "product_sku": "SD-002373",
         "unit_price": 11500,
         "quantity": 1,
         "total": 11500
       }
     ]
   }

   O pedido nasce com status O (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ão 12000 centavos. Repita a mesma chamada com o mesmo idempotency_key e você recebe o mesmo pedido de volta (mesmo id), 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.

curl -s -X DELETE "$BASE_URL/api/v1/admin/orders/$ORDER_ID/permanent" -H "Authorization: Bearer $TOKEN"
curl -s -X DELETE "$BASE_URL/api/v1/admin/users/$CUSTOMER_ID" -H "Authorization: Bearer $TOKEN"

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 lista items veio 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.
• 400 no frete: produto físico sem shipping_method_id.
• price parece 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).

Próximos passos