Saltar al contenido principal

Introducción

Tú que eres dev, ¡diviértete! ✨

La API del Financeiro Inteligente es REST sobre HTTPS, con JSON y autenticación Bearer. Todo lo que las pantallas hacen con cuentas por pagar, cuentas por cobrar, asientos, registros y conciliaciones está disponible para tus sistemas — con el mismo aislamiento por espacio de trabajo del producto.

Primeros pasos​

  1. Genera un token en la plataforma, en Integraciones → Token de API — ver Autenticación.

  2. Haz la primera llamada:

    export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx

    curl -H "Authorization: Bearer $KOBANA_TOKEN" \
      -H 'User-Agent: Mi Sistema (contacto@miempresa.com.br)' \
      'https://api.finance.kobana.com.br/v1/accounts'

  3. Explora los recursos — la categoría Recursos, en la barra lateral, documenta cada endpoint con ejemplos. O importa la especificación OpenAPI / la colección de Postman.

tip

Prefiere el sandbox (https://api.finance.sandbox.kobana.com.br/v1) para desarrollar — ver Endpoints.

Formato​

La API acepta únicamente el formato JSON. Todas las solicitudes deben usar Content-Type: application/json. Todas las respuestas usan snake_case.

Tipo de campoFormato
DateTimeFormato ISO8601. Ejemplos — Fecha: 2026-01-24. Fecha y Hora: 2026-01-24T10:07Z
MoneyString decimal con 2 decimales y punto como separador, en BRL. Ej.: "100.00". Siempre enviado/recibido como string (nunca número), para preservar la precisión de los centavos; hasta 13 dígitos enteros. Los asientos y títulos son siempre positivos — la dirección (débito/crédito, costo/ingreso) va en type/polaridad, nunca en el signo. Los saldos de cuenta pueden ser negativos
UUIDIdentificadores de recursos en formato UUID v4

Convenciones​

Convenciones usadas en esta documentación:

ConvenciónDescripción
:variableNombre de variable que debe ser reemplazada en una URL.
#{variable}Nombre de variable que debe ser reemplazada por valores de tu cuenta.
...Contenido de la respuesta truncado para facilitar la lectura.
$KOBANA_TOKENToken de acceso. Para pruebas en línea de comandos, expórtalo: export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx y pega los comandos de la documentación en la terminal.

Códigos de respuesta​

La API devuelve códigos HTTP estándar:

CódigoDescripción
✅200 OKSolicitud exitosa con cuerpo de respuesta.
✅201 CreatedRecurso creado exitosamente.
✅204 No ContentSolicitud exitosa, sin cuerpo de respuesta.
❌400 Bad RequestSolicitud inválida, generalmente contenido malformado.
❌401 UnauthorizedToken de acceso ausente o inválido.
❌403 ForbiddenAcceso a la API bloqueado o usuario sin permiso.
❌404 Not FoundLa dirección solicitada no existe.
❌422 Unprocessable EntitySolicitud válida, pero los datos enviados no lo son.
❌429 Too Many RequestsLímite de solicitudes alcanzado.
❌500 Internal Server ErrorError interno en el procesamiento. Consulta el estado de los servidores.

El envoltorio y el vocabulario estable de códigos de error están en Errores.

ID de solicitudes (Request-Id)​

Cada solicitud tiene un identificador asociado, disponible en el encabezado Request-Id de la respuesta. Este valor ayuda en la depuración y auditoría — las solicitudes y sus IDs pueden consultarse en el panel del sistema. El registro de solicitudes está disponible por 30 días. Al abrir un ticket de soporte sobre una solicitud específica, informa el Request-Id para agilizar la investigación.

Seguridad​

La API de Kobana usa certificados SSL de 2048 bits. Toda solicitud debe realizarse a través de HTTPS — las llamadas en el puerto 80 son redirigidas al 443.

Los clientes deben soportar TLSv1.2 o TLSv1.3 con uno de los siguientes cifrados: 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 los encabezados HTTP de caché para reducir la 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 ha cambiado, la respuesta será 304 Not Modified, sin cuerpo y sin reprocesamiento. Más información: HTTP Cache Docs.

Manejo de errores​

Los errores 5xx indican fallas en el servidor: 500 Internal Server Error (aplicación no disponible), 502 Bad Gateway, 503 Service Unavailable y 504 Gateway Timeout (fallas puntuales de infraestructura). Tu aplicación debe identificar estos códigos y reprogramar la solicitud después de unos minutos con backoff. Estado de los servidores: https://status.kobana.com.br.

Próximos pasos​