Endpoints REST, webhooks firmados, idempotencia nativa.
3 ambientes aislados (production, staging, sandbox). HMAC-SHA256 en todos los webhooks. Rate limiting por API key. SDKs oficiales Node/Python/Ruby en desarrollo.
Funcionalidad
643
endpoints REST
3
ambientes aislados
HMAC-SHA256
webhooks firmados
Idempotency-Key
nativo
Ambientes para flujo seguro de integración
Production
Ambiente real. Cobros reales. Logs auditados.
- https://api.billing.kobana.com.br
- Cobros reales
- Logs auditados
Staging
Datos persistentes, gateways en sandbox. Para validación pre-producción.
- https://api-staging.billing.kobana.com.br
- Datos persistentes
- Gateways en sandbox
Sandbox
Reset periódico. Gateways mockeados. Tarjetas de prueba predefinidas.
- https://api-sandbox.billing.kobana.com.br
- Reset periódico
- Tarjetas de prueba
Qué está disponible para integrar
REST API Completa
643 endpoints cubriendo todos los recursos: suscripciones, facturas, pagos, clientes, planes, NFe, propuestas, eventos.
- JSON request/response estandarizados
- HTTP status codes semánticos
- Paginación cursor + offset
- Versionamiento por URL (/v1)
Webhooks Firmados
WebhookEndpoint por organización. Eventos seleccionados vía array events. Cada delivery en WebhookDelivery con retry y backoff.
- HMAC-SHA256 vía X-Kobana-Signature header
- Secret cifrado en reposo (AES-256-GCM)
- 40+ tipos de evento
- Retry exponencial hasta 5 intentos
Idempotencia Nativa
Header Idempotency-Key aceptado en todas las mutaciones. Store server-side garantiza misma respuesta para misma key.
- UUID o ULID recomendados
- Columna única en mutations
- Retorna respuesta cacheada
- TTL configurable
API Keys con Alcance
ApiKey por organización con array de permissions. RateLimitConfig por key (req/s + burst).
- Read-only vs write
- Restricción por recurso
- Revocación inmediata
- Last used tracked
Rate Limiting
Límites por API key, IP y endpoint. Headers X-RateLimit-* en todas las respuestas.
- Default 100 req/s por org
- Configurable por enterprise
- 429 con Retry-After
Eventos Internos
Modelo Event registra todo cambio de estado. Útil para auditoría, replay y debug. Worker EventDispatch dispara webhooks.
- Tipo + resource + data JSON
- Filtros por tipo y período
- API de retry manual
Sandbox con Tarjetas de Prueba
Ambiente aislado con gateway mock. Tarjetas estándar simulan aprobación, rechazo, 3DS, expirada.
- Reset bajo demanda
- Webhooks entregados en endpoint configurable (ngrok recomendado)
- Misma API que producción
OpenAPI Spec
Especificación OpenAPI 3.x para generación de SDKs y documentación interactiva.
- Swagger UI hospedado
- Postman collection
- SDKs auto-generados
Callbacks de Gateways
Endpoints públicos /api/callbacks/{provider} reciben webhooks de Pagar.me, Kobana Gateway Bancario, NFe.io. Procesados vía worker con handlers dedicados.
- Idempotencia por payload
- Validación de firma
- Logs en modelo Callback
Verificar firma HMAC del 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 pagado
break;
case 'subscription.canceled':
// remueve acceso
break;
}
res.json({ received: true });
});