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ê cancela o pedido e apaga o cliente 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 ($EMAIL) e a chave de API ($API_KEY) de um usuário administrador da loja (Autenticação).
• 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"
export EMAIL="erp@minhaloja.com.br"
export API_KEY="a-chave-de-64-caracteres"

O fluxo

1. Autenticar

   Com a chave de API não há login: o par e-mail:chave vai em cada chamada, em HTTP Basic. Confirme que as credenciais funcionam pedindo uma página de uma lista.

   cURLJavaScriptPython

   bash

   curl -s "$BASE_URL/api/v1.0/products?items_per_page=1" -u "$EMAIL:$API_KEY" | jq .params

   Se preferir um token, troque e-mail e senha em POST /api/v1.0/auth_tokens e envie Authorization: Bearer <token> nas chamadas seguintes (Autenticação). Um 401 aqui quer dizer e-mail ou chave incorretos.

2. Listar produtos

   Busque um produto pelo nome com o parâmetro q. A lista é paginada: items_per_page define o tamanho da página e a resposta traz os totais em params.

   cURLJavaScriptPython

   bash

   curl -s "$BASE_URL/api/v1.0/products?q=Slim%20Rosa&items_per_page=2" -u "$EMAIL:$API_KEY"

   200Produtos encontrados

   json

   {
     "products": [
       {
         "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
         "product": "Notebook Slim Rosa 02373",
         "product_code": "SD-002373",
         "price": "115.00",
         "list_price": "123.45",
         "amount": 51,
         "status": "A",
         "timestamp": 1779886024
       }
     ],
     "params": { "page": 1, "items_per_page": 2, "total_items": 43 }
   }

   Guarde o product_id (UUID). O price é uma string decimal: "115.00" é R$ 115,00. O amount é o estoque. A resposta real tem muitos outros campos; aqui estão só os principais.

3. Escolher o frete

   Um pedido de produto físico precisa de uma forma de envio. Leia o cadastro da loja e guarde o shipping_id de uma delas.

   bash

   curl -s "$BASE_URL/api/v1.0/shippings?items_per_page=10" -u "$EMAIL:$API_KEY" | jq '.shippings[] | {shipping_id, shipping}'

   Cada item traz shipping_id (UUID) e shipping (o nome). A forma de pagamento é um código (slug) definido pela loja, como pix, boleto ou pagamento-na-entrega; use um que exista na sua loja.

4. Criar um cliente

   POST /api/v1.0/users cadastra o comprador. email e user_type são obrigatórios; informe também firstname. Com user_type igual a C, ele é um comprador (e não um administrador).

   cURLJavaScriptPython

   bash

   CUSTOMER_ID=$(curl -s -X POST "$BASE_URL/api/v1.0/users" -u "$EMAIL:$API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"email": "joao.lima@example.com", "user_type": "C", "firstname": "João", "lastname": "Lima"}' \
     | jq -r .user_id)

   201Cliente criado

   json

   {
     "user_id": "9781e019-a0c1-4cc5-bbd2-16ef86e1c999",
     "profile_id": "9781e019-a0c1-4cc5-bbd2-16ef86e1c999"
   }

   Guarde o user_id (UUID). O profile_id é igual a ele. Sem password, a plataforma gera uma senha aleatória e o cliente define a dele pelo fluxo "esqueci a senha". Se o e-mail já existir, a resposta é 400.

5. Criar o pedido

   Junte tudo: o cliente, os itens, o endereço de entrega, a forma de envio e a forma de pagamento. O preço vem do catálogo, não do seu corpo.

   cURLJavaScriptPython

   bash

   curl -s -X POST "$BASE_URL/api/v1.0/orders" -u "$EMAIL:$API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "user_id": "9781e019-a0c1-4cc5-bbd2-16ef86e1c999",
       "payment_id": "pagamento-na-entrega",
       "shipping_ids": ["85e87a54-dcee-4947-8cfa-f6406f2f3cbb"],
       "products": [{ "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035", "amount": 1 }],
       "user_data": {
         "firstname": "João", "lastname": "Lima", "email": "joao.lima@example.com",
         "s_address": "Avenida Paulista, 1000", "s_city": "São Paulo",
         "s_state": "SP", "s_zipcode": "01310-100", "s_country": "BR"
       }
     }'

   201Pedido criado (resumo)

   json

   {
     "order_id": "819887d3-069f-4f33-91fa-ea8693d3b5c9",
     "order_data": {
       "order_id": "819887d3-069f-4f33-91fa-ea8693d3b5c9",
       "order_number": "PEDIDO-20261011-0007",
       "user_id": "9781e019-a0c1-4cc5-bbd2-16ef86e1c999",
       "subtotal": "115.00",
       "shipping_cost": "5.00",
       "discount": "0.00",
       "total": "120.00",
       "currency": "BRL",
       "status": "O",
       "timestamp": 1791767828,
       "payment_method": { "payment": "pagamento-na-entrega", "payment_id": "pagamento-na-entrega" }
     }
   }

   O pedido nasce com status O (pendente). Os valores são strings decimais e o timestamp é Unix. O frete é recalculado pela plataforma: R$ 115,00 de produto mais R$ 5,00 de frete dão "120.00". Para um produto físico, a forma de envio em shipping_ids é obrigatória; sem ela a resposta é 400 com shipping_service_unavailable: a shipping method is required for physical products, e uma forma de envio que não atende o produto ou o CEP responde 400 com shipping_service_unavailable: selected shipping method/service is unavailable. Guarde o order_id agora: a API não tem idempotência, e repetir o POST cria outro pedido. Todos os campos estão em Criar pedido.

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

Nesta API, DELETE num pedido cancela o pedido: o registro continua existindo com o status I (cancelado) e o estoque volta. Um usuário, por sua vez, é removido de verdade. Cancele o pedido antes de apagar o cliente.

curl -s -X DELETE "$BASE_URL/api/v1.0/orders/$ORDER_ID" -u "$EMAIL:$API_KEY"
curl -s -X DELETE "$BASE_URL/api/v1.0/users/$CUSTOMER_ID" -u "$EMAIL:$API_KEY"

As duas respostas são 204, sem corpo. As variações de cancelamento estão em Cancelar e excluir.

Erros comuns neste fluxo

• 400 com o nome do campo na mensagem (por exemplo user_id is required): o corpo veio sem um campo obrigatório.
• 401 Invalid credentials: e-mail ou chave incorretos, ou a chave foi substituída por outra.
• 403 Forbidden: admin scope required: o usuário da chave não é administrador.
• 400 no frete: produto físico sem shipping_ids, ou com uma forma de envio que não atende o produto.
• price aparece como texto: na API legada o dinheiro é uma string decimal, não um número.
• Pedido duplicado: o POST foi repetido depois de um timeout; confira antes de criar de novo (Limites e boas práticas).

Próximos passos