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

Sua primeira requisição

Tutorial ponta a ponta na API legada: 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ê cancela o pedido e apaga o cliente 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 ($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.

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.

    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.

    200Produtos encontrados

    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.

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

    201Cliente criado

    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.

    201Pedido criado (resumo)

    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.

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

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"
export EMAIL="erp@minhaloja.com.br"
export API_KEY="a-chave-de-64-caracteres"
bash
curl -s "$BASE_URL/api/v1.0/products?items_per_page=1" -u "$EMAIL:$API_KEY" | jq .params
bash
curl -s "$BASE_URL/api/v1.0/products?q=Slim%20Rosa&items_per_page=2" -u "$EMAIL:$API_KEY"
bash
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"
bash
curl -s "$BASE_URL/api/v1.0/shippings?items_per_page=10" -u "$EMAIL:$API_KEY" | jq '.shippings[] | {shipping_id, shipping}'
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)
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"
    }
  }'
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 }
}
json
{
  "user_id": "9781e019-a0c1-4cc5-bbd2-16ef86e1c999",
  "profile_id": "9781e019-a0c1-4cc5-bbd2-16ef86e1c999"
}
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" }
  }
}