API de Financeiro Inteligente
¡Eh, dev, diviértete! ✨
Índice de la documentación — accede al índice completo en https://docs.finance.kobana.com.br/llms.txt. Usa este archivo para descubrir todas las páginas disponibles antes de empezar a explorar.
Autenticación
La API usa Bearer JWT (HS512). Envía el token en la cabecera de cada solicitud:
Authorization: Bearer <token>
Para pruebas en línea de comandos, exporta el token: export KOBANA_TOKEN=xxxxxxxx y pega los comandos de la documentación directamente en tu terminal.
Formato
La API solo acepta el formato JSON. Todas las solicitudes deben usar Content-Type: application/json. Todas las respuestas usan snake_case.
| Tipo de Campo | Formato |
|---|---|
| DateTime | Formato ISO8601. Ejemplos — Fecha: 2026-01-24. Fecha y hora: 2026-01-24T10:07:00.000Z |
| Money | Decimal como cadena con 2 decimales ("150.00"). Siempre positivo — la dirección la indica el campo type (debit/credit) o el contexto (payable/receivable). |
| UUID | Identificadores de recursos en formato UUID v4 |
Convenciones
Convenciones usadas en esta documentación:
| Convención | Descripción |
|---|---|
:id | Parámetro de path que debe reemplazarse por el UUID del recurso. |
#{variable} | Un valor de tu cuenta que debe sustituirse en el ejemplo. |
... | Contenido de la respuesta truncado para facilitar la lectura. |
$KOBANA_TOKEN | Token JWT de acceso. Expórtalo con export KOBANA_TOKEN=xxxxxxxx. |
Entornos
| Entorno | Base URL |
|---|---|
| Producción | https://api.finance.kobana.com.br/v1 |
| Sandbox | https://api.finance.sandbox.kobana.com.br/v1 |
Códigos de Retorno
La API devuelve códigos HTTP estándar:
| Código | Descripción | |
|---|---|---|
| ✅ | 200 OK | Solicitud exitosa con cuerpo de respuesta. |
| ✅ | 201 Created | Recurso creado con éxito. |
| ✅ | 204 No Content | Solicitud exitosa, sin cuerpo de respuesta. |
| ❌ | 400 Bad Request | Solicitud inválida, normalmente un cuerpo mal formado. |
| ❌ | 401 Unauthorized | Token ausente, inválido o expirado. |
| ❌ | 403 Forbidden | Alcance insuficiente para la operación. |
| ❌ | 404 Not Found | Recurso no encontrado o fuera del workspace. |
| ❌ | 422 Unprocessable Entity | Solicitud válida, pero los datos enviados no lo son. |
| ❌ | 429 Too Many Requests | Límite de solicitudes alcanzado. |
| ❌ | 500 Internal Server Error | Error interno de procesamiento. Consulta el estado de los servidores. |
Listado y Paginación
Todos los endpoints de listado usan paginación por cursor:
GET /v1/payables?cursor=<opaque_cursor>&limit=25
La respuesta incluye meta.next_cursor — pásalo como ?cursor= en la siguiente solicitud para obtener la página siguiente. Cuando meta.next_cursor es null, no hay más páginas.
Idempotencia
Las operaciones de creación (POST) aceptan la cabecera X-Idempotency-Key. Los reenvíos con la misma clave devuelven el resultado original sin crear duplicados — seguro para reintentar ante un fallo de red.
X-Idempotency-Key: <uuid-v4-generado-por-el-cliente>
ID de las Solicitudes (Request ID)
Cada solicitud tiene un identificador asociado, disponible en la cabecera Request-Id de la respuesta. Este valor ayuda en la depuración y auditoría. El registro de solicitudes se conserva durante 30 días. Al abrir un ticket de soporte sobre una solicitud específica, indica el Request-Id para acelerar la investigación.
Seguridad
La API usa certificados SSL de 2048 bits. Toda solicitud debe hacerse vía HTTPS — las llamadas al puerto 80 se redirigen al 443.
Los clientes deben admitir TLSv1.2 o TLSv1.3 con una de las siguientes cifras: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-CHACHA20-POLY1305, ECDHE-RSA-AES256-SHA384. TLSv1 y TLSv1.1 no son compatibles.
Caché HTTP
Usa las cabeceras HTTP de caché para reducir carga y ganar velocidad. La mayoría de las respuestas incluyen ETag y/o Last-Modified — almacena estos valores y reenvíalos en las siguientes solicitudes mediante If-None-Match e If-Modified-Since. Si el recurso no cambió, la respuesta será 304 Not Modified, sin cuerpo y sin reprocesamiento.
Manejo de Errores
Los errores 5xx indican fallos del servidor: 500 Internal Server Error (aplicación no disponible), 502 Bad Gateway, 503 Service Unavailable y 504 Gateway Timeout (fallos puntuales de infraestructura). Tu aplicación debe identificar estos códigos y reprogramar la solicitud tras unos minutos con backoff exponencial. Estado de los servidores: https://status.kobana.com.br.
Spec OpenAPI
Importa la spec en Postman o Insomnia para tener una colección lista que siempre refleja la API actual:
- YAML:
/api/v1/openapi.yaml - JSON:
/api/v1/openapi.json