API de Finanzas Inteligentes
¡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
Cada solicitud necesita dos cosas: el token, que indica qué organización eres, y la cabecera X-Workspace-Id, que indica en cuál de sus espacios de trabajo actuar.
Authorization: Bearer <token>
X-Workspace-Id: <uuid del espacio de trabajo>
El token
Un Bearer JWT firmado en RS256 por el servidor de autorización de Kobana (HS512 solo contra un servidor de desarrollo local).
| Claim | Papel |
|---|---|
org | El tenant. El public_id de la organización — es lo que decide a qué datos llega el token. |
sub | La persona que autorizó. Existe para auditoría y no delimita nada. |
scope | Lista separada por espacios (ej.: finance.payables finance.people.write). Un scope .write también sirve para lectura. |
jti | Identificador del token, usado para revocación. |
iss / aud / exp | Emisor, destinatario y expiración. |
⚠️ El tenant es org, nunca sub. Son espacios de identificadores distintos: un id de persona jamás corresponde a una organización, así que un token armado con el valor equivocado falla en cada solicitud.
La cabecera X-Workspace-Id
Una organización puede tener varios espacios de trabajo, y cada ruta de esta API responde por exactamente uno. El token por sí solo no dice cuál — por eso la cabecera es obligatoria en todas las operaciones.
Es un selector, nunca un permiso: el espacio indicado se coteja contra la organización del token. Un espacio que pertenece a otra organización responde igual que uno inexistente — a propósito, para que la respuesta no revele que ese id es real en otro lugar.
| Situación | Respuesta |
|---|---|
| Cabecera ausente | 400 WORKSPACE_REQUIRED |
| Espacio de otra organización, inexistente, o id malformado | 403 UNKNOWN_WORKSPACE |
org no corresponde a ninguna organización | 403 UNKNOWN_ORGANIZATION |
| Scope insuficiente para la operación | 403 INSUFFICIENT_SCOPE |
Una regla de Seguridad del espacio bloqueó la operación (details.reason indica cuál) | 403 SECURITY_BLOCKED |
Ejemplo
curl https://api.finance.kobana.com.br/v1/payables \
-H "Authorization: Bearer $KOBANA_TOKEN" \
-H "X-Workspace-Id: $KOBANA_WORKSPACE_ID"
Para pruebas en línea de comandos, exporta ambos: export KOBANA_TOKEN=xxxxxxxx y export KOBANA_WORKSPACE_ID=xxxxxxxx, y pega los comandos de la documentación 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. |
$KOBANA_WORKSPACE_ID | UUID del espacio de trabajo, enviado en X-Workspace-Id. Expórtalo con export KOBANA_WORKSPACE_ID=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 — cuerpo mal formado, filtro no permitido, o X-Workspace-Id ausente. |
| ❌ | 401 Unauthorized | Token ausente, inválido o expirado. |
| ❌ | 403 Forbidden | Alcance insuficiente, organización desconocida, o espacio de trabajo fuera de ella. |
| ❌ | 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