VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Primeiros passos

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.

Use uma loja de teste

Os passos 4 e 5 gravam dados (um cliente e um pedido; o pedido reduz o estoque do produto). Faça o tutorial numa loja de homologação ou num produto que você possa mexer, e siga a seção de limpeza no final.

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.

O fluxo

  1. Autenticar

    Troque e-mail e senha por um access_token (Autenticação). Todos os passos seguintes enviam esse 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.

    200Produtos encontrados

    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.

    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).

    201Cliente criado

    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.

    201Pedido criado (resumo)

    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.

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

Pedidos
Status, remessas, notas fiscais e reembolsos.
Produtos
Criar e atualizar o catálogo.
Clientes
Endereços, documentos e status da conta.
Anterior
Autenticação
Próxima
Convenções
Nesta página
  • Antes de começar
  • O fluxo
  • Limpeza
  • Erros comuns neste fluxo
  • Próximos passos
bash
export BASE_URL="https://minhaloja.io.venddor.com.br"
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)
bash
curl -s "$BASE_URL/api/v1/admin/products?search=Slim%20Rosa&per_page=2" \
  -H "Authorization: Bearer $TOKEN"
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"
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)
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"
    }
  }'
bash
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"
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
}
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"
}
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
    }
  ]
}