Saltar al contenido principal

Introducción

Si eres dev, ¡diviértete! ✨

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
MoneyNúmero decimal en reales (BRL), con hasta 4 decimales. Ej.: 100.5 = R$ 100,50
UUIDIdentificadores de recursos en formato UUID v4

Convenciones​

Convenciones usadas en esta documentación:

ConvenciónDescripción
:variableNombre de variable que debe sustituirse en una URL.
#{variable}Nombre de variable que debe sustituirse 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 con éxito.
✅204 No ContentSolicitud exitosa, sin cuerpo de respuesta.
❌400 Bad RequestSolicitud inválida, en general contenido mal formado.
❌401 UnauthorizedToken de acceso ausente o inválido.
❌403 ForbiddenAcceso a la API bloqueado o usuario sin permiso.
❌404 Not FoundLa dirección accedida 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.

ID de las Solicitudes (Request ID)​

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

Seguridad​

La API de Kobana usa certificados SSL de 2048 bits. Toda solicitud debe hacerse por HTTPS — las llamadas al puerto 80 se redirigen al 443.

Los clientes deben soportar TLSv1.2 o TLSv1.3 con una de las 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 están soportados.

Caché HTTP​

Usa los headers HTTP de caché para reducir la carga y ganar velocidad. La mayoría de las respuestas incluye ETag y/o Last-Modified — guarda esos 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. Más información: HTTP Cache Docs.

Manejo de Errores​

Los errores 5xx indican fallos en el 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 después de unos minutos con backoff. Estado de los servidores: https://status.kobana.com.br.

Valores monetarios​

Todo valor monetario — en la solicitud y en la respuesta — es un número decimal en reales (BRL), con hasta 4 decimales. No hay campos en centavos: envía 100.5 para R$ 100,50 y 0.0125 para R$ 0,0125. Los campos de precios aceptan los 4 decimales; los demás se redondean a 2.

Próximos pasos​