Guia do Desenvolvedor

Testando seu App

Teste a integracao do seu app contra o sandbox Venddor antes de ir ao ar.

Ambiente Sandbox

O Venddor fornece um ambiente sandbox completo para testes. O sandbox tem dados de demonstracao e nao afeta lojas reais.

AmbienteURLUso
Sandboxhttps://sandbox.api.io.venddor.com.brDesenvolvimento e testes
Producaohttps://api.io.venddor.com.brApps em producao
O sandbox e resetado semanalmente. Dados criados nele sao temporarios. Use-o para testar e validar, nao para armazenar dados permanentes.

Credenciais de Teste

Ao criar um app no portal do desenvolvedor, voce automaticamente recebe credenciais de sandbox. Use-as para testar antes de ir ao ar:

bash
# Sandbox test credentials (from your developer dashboard)
export VENDDOR_API_URL="https://sandbox.api.io.venddor.com.br"
export CLIENT_ID="your_sandbox_client_id"
export CLIENT_SECRET="your_sandbox_client_secret"
export TEST_TENANT_ID="sandbox-demo-tenant"

# Quick test: list products from sandbox
curl -H "Authorization: Bearer $TEST_TOKEN" \
     -H "X-Tenant-ID: $TEST_TENANT_ID" \
     "$VENDDOR_API_URL/api/storefront/products"

O sandbox inclui dados de demonstracao: 50 produtos, 20 pedidos, 10 clientes, 5 categorias.

Teste do Fluxo OAuth

Teste o fluxo OAuth completo no sandbox antes de ir a producao:

#TesteResultado esperado
1Redirecione para /oauth/authorizePagina de autorizacao exibida
2Aprove os escoposRedirect para sua callback URL com ?code=...
3Troque codigo por tokenaccess_token e refresh_token retornados
4Use token para chamar APIDados retornados com sucesso
5Use token expiradoHTTP 401 retornado
6Refresh o tokenNovo access_token retornado
7Use state invalidoErro de CSRF detectado
bash
# Test token exchange
curl -X POST "$VENDDOR_API_URL/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "'$CLIENT_ID'",
    "client_secret": "'$CLIENT_SECRET'",
    "code": "AUTH_CODE_FROM_CALLBACK",
    "redirect_uri": "https://localhost:3000/auth/callback"
  }'

# Test token refresh
curl -X POST "$VENDDOR_API_URL/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "'$CLIENT_ID'",
    "client_secret": "'$CLIENT_SECRET'",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

Teste de APIs

Teste cada endpoint que seu app utiliza. Verifique tanto cenarios de sucesso quanto de erro:

bash
# Set up test environment
API="https://sandbox.api.io.venddor.com.br"
AUTH="Authorization: Bearer $TOKEN"
TENANT="X-Tenant-ID: $TENANT_ID"

# Test: List products (should return 200)
curl -s -w "\nHTTP Status: %{http_code}\n" \
  -H "$AUTH" -H "$TENANT" "$API/api/storefront/products"

# Test: Get non-existent product (should return 404)
curl -s -w "\nHTTP Status: %{http_code}\n" \
  -H "$AUTH" -H "$TENANT" "$API/api/storefront/products/nonexistent-id"

# Test: Create product without required field (should return 400)
curl -s -w "\nHTTP Status: %{http_code}\n" -X POST \
  -H "$AUTH" -H "$TENANT" -H "Content-Type: application/json" \
  -d '{"description": "no name field"}' \
  "$API/api/admin/products"

# Test: Access without token (should return 401)
curl -s -w "\nHTTP Status: %{http_code}\n" \
  -H "$TENANT" "$API/api/admin/products"

# Test: Access scope you don't have (should return 403)
curl -s -w "\nHTTP Status: %{http_code}\n" \
  -H "$AUTH" -H "$TENANT" "$API/api/admin/settings"

Teste de Webhooks

Use ferramentas como ngrok ou webhook.site para testar webhooks localmente:

bash
# Option 1: Use ngrok to expose your local server
ngrok http 3000
# Copy the ngrok URL (e.g., https://abc123.ngrok.io)
# Register it as webhook URL in your developer dashboard

# Option 2: Use webhook.site for quick testing
# Go to https://webhook.site and copy your unique URL
# Register it as webhook URL in your developer dashboard

# Option 3: Trigger a test webhook from the API
curl -X POST "$API/api/developers/apps/YOUR_APP_ID/webhooks/test" \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order.created",
    "webhook_url": "https://your-ngrok-url.ngrok.io/webhooks/venddor"
  }'
Sempre valide a assinatura do webhook em seu handler. Requests sem assinatura valida devem ser rejeitados com HTTP 401.
javascript
// Webhook signature verification (Node.js)
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post('/webhooks/venddor', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-venddor-signature'];

  if (!verifyWebhookSignature(req.body, signature, CLIENT_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // Process the event...
  res.status(200).send('OK');
});

Erros Comuns

ErroCausaSolucao
401 UnauthorizedToken expirado ou invalidoUse refresh_token para obter novo access_token
403 ForbiddenEscopo insuficienteSolicite os escopos necessarios durante OAuth
404 Not FoundRecurso nao existe ou pertence a outro tenantVerifique o ID e o X-Tenant-ID
429 Rate LimitedMuitas requisicoesImplemente backoff exponencial
CORS errorChamando API do browserUse um proxy server-side. A API nao suporta CORS direto.
Invalid stateParametro state nao confereGere um state unico por sessao e valide no callback

Checklist Pre-Lancamento

Antes de publicar seu app no marketplace, verifique todos os itens: