Guia do Desenvolvedor

Integracao via API

Chame APIs REST e GraphQL do Venddor para ler e escrever dados do seu app.

Primeiros PassosIntegracao via APIConstruindo seu AppModelos de DadosReferencia APITestando seu AppPublicacao no Marketplace

Autenticacao

Todas as chamadas API autenticadas requerem dois headers:

bash
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "X-Tenant-ID: TENANT_UUID" \
     https://api.io.venddor.com.br/api/storefront/products
HeaderDescriçãoExemplo
AuthorizationToken OAuth BearerBearer eyJhbG...
X-Tenant-IDUUID do tenant alvo550e8400-e29b-41d4...
Content-TypePara POST/PUT (JSON)application/json

Endpoints REST

O Venddor oferece 1.250+ endpoints REST organizados por dominio. Aqui estao os mais comuns:

Produtos

bash
# List products
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-ID: $TENANT" \
     "https://api.io.venddor.com.br/api/storefront/products?page=1&limit=20"

# Get a single product
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-ID: $TENANT" \
     "https://api.io.venddor.com.br/api/storefront/products/PRODUCT_ID"

# Create a product (requires write_products scope)
curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-ID: $TENANT" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Camiseta Premium",
       "price_cents": 8990,
       "description": "100% cotton premium t-shirt",
       "status": "active",
       "category_id": "CAT_UUID"
     }' \
     "https://api.io.venddor.com.br/api/admin/products"

# Update a product
curl -X PUT -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-ID: $TENANT" \
     -H "Content-Type: application/json" \
     -d '{"price_cents": 7990}' \
     "https://api.io.venddor.com.br/api/admin/products/PRODUCT_ID"

Pedidos

bash
# List orders
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-ID: $TENANT" \
     "https://api.io.venddor.com.br/api/admin/orders?status=pending&page=1"

# Get order details
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-ID: $TENANT" \
     "https://api.io.venddor.com.br/api/admin/orders/ORDER_ID"

# Update order status (requires write_orders scope)
curl -X PUT -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-ID: $TENANT" \
     -H "Content-Type: application/json" \
     -d '{"status": "shipped", "tracking_code": "BR123456789"}' \
     "https://api.io.venddor.com.br/api/admin/orders/ORDER_ID/status"

Clientes

bash
# List customers
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-ID: $TENANT" \
     "https://api.io.venddor.com.br/api/admin/users?role=customer&page=1"

# Get customer details
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-ID: $TENANT" \
     "https://api.io.venddor.com.br/api/admin/users/USER_ID"

# Search customers
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-ID: $TENANT" \
     "https://api.io.venddor.com.br/api/admin/users?search=joao&role=customer"

API GraphQL

O Venddor tambem oferece uma API GraphQL para consultas mais flexiveis. O endpoint e:

bash
POST https://api.io.venddor.com.br/graphql

Exemplo: Buscar Produtos com Categorias

bash
curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-ID: $TENANT" \
     -H "Content-Type: application/json" \
     -d '{
       "query": "{ products(limit: 10, status: "active") { id name price_cents category { id name } images { url alt } } }"
     }' \
     "https://api.io.venddor.com.br/graphql"

Resposta:

json
{
  "data": {
    "products": [
      {
        "id": "prod_abc123",
        "name": "Camiseta Premium",
        "price_cents": 8990,
        "category": {
          "id": "cat_456",
          "name": "Vestuario"
        },
        "images": [
          { "url": "https://cdn.venddor.com.br/...", "alt": "Camiseta frente" }
        ]
      }
    ]
  }
}
Explore o schema completo no GraphQL Playground: https://api.io.venddor.com.br/graphql/playground

Webhooks

Registre webhooks no painel do desenvolvedor para ser notificado quando eventos acontecem na loja do tenant. Webhooks sao enviados via POST com payload JSON.

EventoQuando dispara
order.createdNovo pedido criado
order.updatedPedido atualizado (status, tracking, etc.)
order.cancelledPedido cancelado
product.createdNovo produto criado
product.updatedProduto atualizado
product.deletedProduto removido
user.registeredNovo usuario registrado
checkout.completedCheckout finalizado
cart.updatedCarrinho modificado

Exemplo de Payload de Webhook

json
{
  "event": "order.created",
  "timestamp": "2026-03-27T14:30:00Z",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "app_id": "your_client_id",
  "data": {
    "id": "ord_789",
    "status": "pending",
    "total_cents": 15980,
    "currency": "BRL",
    "customer": {
      "id": "usr_123",
      "name": "Joao Silva",
      "email": "joao@example.com"
    },
    "items": [
      {
        "product_id": "prod_abc",
        "name": "Camiseta Premium",
        "quantity": 2,
        "price_cents": 7990
      }
    ],
    "created_at": "2026-03-27T14:30:00Z"
  },
  "signature": "sha256=abc123..."
}
Valide a assinatura do webhook usando seu Client Secret para garantir que a requisicao veio do Venddor. O header X-Venddor-Signature contem o HMAC SHA-256.

Paginacao e Filtros

Endpoints de listagem suportam paginacao e filtros via query parameters:

bash
# Pagination
?page=1&limit=20

# Sorting
?sort_by=created_at&sort_order=desc

# Filtering
?status=active&category_id=CAT_UUID

# Search
?search=camiseta

# Date range
?created_after=2026-01-01&created_before=2026-03-31

# Combined example
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-ID: $TENANT" \
     "https://api.io.venddor.com.br/api/admin/products?page=2&limit=10&status=active&sort_by=price_cents&sort_order=asc"

Rate Limiting

A API aplica rate limiting por app por tenant. Os limites sao retornados nos headers de resposta:

HeaderDescrição
X-RateLimit-LimitMaximo de requests por minuto
X-RateLimit-RemainingRequests restantes neste periodo
X-RateLimit-ResetTimestamp Unix quando o limite reseta
Se voce exceder o limite, recebera HTTP 429 Too Many Requests. Implemente exponential backoff no seu app.

Tratamento de Erros

A API retorna erros no formato JSON padronizado:

json
{
  "error": "not_found",
  "message": "Product not found",
  "status": 404
}
Status HTTPSignificadoO que fazer
400Bad RequestVerifique o corpo da requisicao
401UnauthorizedToken expirado ou invalido — re-autentique
403ForbiddenEscopo insuficiente ou modulo desabilitado
404Not FoundRecurso nao existe
422UnprocessableValidacao falhou — verifique campos
429Rate LimitedAguarde e tente novamente
500Server ErrorProblema no servidor — tente novamente
Anterior
Primeiros Passos
Proximo
Construindo seu App