Endpoints REST, webhooks assinados, idempotência nativa.
3 ambientes isolados (production, staging, sandbox). HMAC-SHA256 em todos webhooks. Rate limiting por API key. SDKs oficiais Node/Python/Ruby em desenvolvimento.
Funcionalidade
643
endpoints REST
3
ambientes isolados
HMAC-SHA256
webhooks assinados
Idempotency-Key
nativo
Ambientes para fluxo seguro de integração
Production
Ambiente real. Cobranças reais. Logs auditados.
- https://api.billing.kobana.com.br
- Cobranças reais
- Logs auditados
Staging
Dados persistentes, gateways em sandbox. Para validação pré-produção.
- https://api-staging.billing.kobana.com.br
- Dados persistentes
- Gateways em sandbox
Sandbox
Reset periódico. Gateways mockados. Cartões de teste pré-definidos.
- https://api-sandbox.billing.kobana.com.br
- Reset periódico
- Cartões de teste
O que está disponível para integrar
REST API Completa
643 endpoints cobrindo todos os recursos: assinaturas, faturas, pagamentos, clientes, planos, NFe, propostas, eventos.
- JSON request/response padronizados
- HTTP status codes semânticos
- Paginação cursor + offset
- Versionamento por URL (/v1)
Webhooks Assinados
WebhookEndpoint por organização. Eventos selecionados via array events. Cada delivery em WebhookDelivery com retry e backoff.
- HMAC-SHA256 via X-Kobana-Signature header
- Secret criptografado em repouso (AES-256-GCM)
- 40+ tipos de evento
- Retry exponencial até 5 tentativas
Idempotência Nativa
Header Idempotency-Key aceito em todas as mutações. Store server-side garante mesma resposta para mesma key.
- UUID ou ULID recomendados
- Coluna única em mutations
- Retorna resposta cacheada
- TTL configurável
API Keys com Escopo
ApiKey por organização com permissions array. RateLimitConfig por key (req/s + burst).
- Read-only vs write
- Restrição por recurso
- Revogação imediata
- Last used tracked
Rate Limiting
Limites por API key, IP e endpoint. Headers X-RateLimit-* em todas respostas.
- Default 100 req/s por org
- Configurável por enterprise
- 429 com Retry-After
Eventos Internos
Event model registra toda mudança de estado. Útil para auditoria, replay e debug. EventDispatch worker dispara webhooks.
- Tipo + resource + data JSON
- Filtros por tipo e período
- API de retry manual
Sandbox com Cartões de Teste
Ambiente isolado com gateway mock. Cartões padrão simulam aprovação, recusa, 3DS, expirado.
- Reset sob demanda
- Webhooks delivered em endpoint configurável (ngrok recomendado)
- Mesma API que produção
OpenAPI Spec
Especificação OpenAPI 3.x para geração de SDKs e documentação interativa.
- Swagger UI hospedado
- Postman collection
- SDKs auto-gerados
Callbacks de Gateways
Endpoints públicos /api/callbacks/{provider} recebem webhooks de Pagar.me, Kobana Gateway Bancário, NFe.io. Processados via worker com handlers dedicados.
- Idempotência por payload
- Validação de assinatura
- Logs em Callback model
Verificar assinatura HMAC do webhook
javascript
const crypto = require('crypto');
app.post('/webhooks/kobana', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-kobana-signature'];
const secret = process.env.KOBANA_WEBHOOK_SECRET;
const expected = crypto
.createHmac('sha256', secret)
.update(req.body)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(req.body);
switch (event.type) {
case 'invoice.paid':
// marca pedido como pago
break;
case 'subscription.canceled':
// remove acesso
break;
}
res.json({ received: true });
});