Quickstart

Do zero à primeira chamada bem-sucedida em ~5 minutos.

Pre-req — você precisa de um client_id + client_secret. Cadastre-se em /onboarding: informe email corporativo, nome da empresa e contato. Após confirmar por email, as credenciais aparecem uma única vez na plataforma.

Obtenha um token OAuth2

Faça o request client_credentials com Basic Auth:

AUTH=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64)

TOKEN=$(curl -s -X POST \
  -H "Authorization: Basic $AUTH" \
  -d "grant_type=client_credentials&scope=customers:read customers:write" \
  https://auth.api.voalle.dev/oauth2/token | jq -r .access_token)

echo $TOKEN  # JWT RS256, ~1100 chars, expira em 1h

Scopes disponíveis hoje:

Crie um cliente

Todo POST/PATCH exige header Idempotency-Key e X-Voalle-Tenant:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Voalle-Tenant: tenant_demo" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"ACME Ltda","document":"12345678000190"}' \
  https://api.voalle.dev/v1/crm/customers

# Resposta:
# {
#   "id": "cus_ABC123...",
#   "name": "ACME Ltda",
#   "document": "12345678000190",
#   "status": "active",
#   "created_at": "2026-05-29T...",
#   "request_id": "req_..."
# }
Idempotency — repetir o request com a mesma Idempotency-Key retorna a resposta original (header X-Idempotent-Replay: true). Cache de 24h.

Liste recursos

Paginação cursor-based via limit + after:

curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Voalle-Tenant: tenant_demo" \
     'https://api.voalle.dev/v1/crm/customers?limit=10'

Receba webhooks

Subscreva eventos pra ser notificado em tempo real:

# exemplo de payload recebido no seu endpoint:
# POST https://your-app.com/webhooks/voalle
#   Voalle-Event-Type: voalle.crm.customer.created.v1
#   Voalle-Signature: t=1779995294,v1=<hex_sha256>
#   Voalle-Event-Id: evt_...
#   Content-Type: application/json
#   {"specversion":"1.0","id":"evt_...","type":"voalle.crm.customer.created.v1",...}

Validar HMAC sempre. Padrão de eventos: voalle.<domain>.<aggregate>.<action>.v<n>. Suportamos wildcards em event_types (ex: voalle.crm.customer.*).

Próximos passos