API de Facturación Automática
¡Tú que eres dev, diviértete! ✨
Índice de la documentación — accede al índice completo en https://docs.billing.kobana.com.br/llms.txt. Usa este archivo para descubrir todas las páginas disponibles antes de explorar.
Atención a las versiones de la API — estás en la documentación de la v1.0 de la API de Facturación Automática, que cubre los endpoints de Suscripciones (creación, cambio de plan, pausa, cancelación, facturación manual, sincronización de ítems) y recursos relacionados. Recursos como Pagos, Transferencias, Extracto y Recepción por Pix están disponibles en otras APIs de Kobana — usa el selector de producto en el menú superior para acceder.
Formato
La API solo acepta 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:07Z |
Money (_cents) | Entero en centavos (÷100). Ej.: 10000 = R$ 100,00 |
Money (_subcents) | Entero en subcentavos (÷10000), usado en precios. Ej.: 1000000 = R$ 100,00 |
| UUID | Identificadores de recursos en formato UUID v4 |
Convenciones
Convenciones usadas en esta documentación:
| Convención | Descripción |
|---|---|
:variable | Nombre 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_TOKEN | Token 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 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, generalmente contenido mal formado. |
| ❌ | 401 Unauthorized | Token de acceso ausente o inválido. |
| ❌ | 403 Forbidden | Acceso a la API bloqueado o usuario sin permiso. |
| ❌ | 404 Not Found | El recurso no existe. |
| ❌ | 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. |
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 — 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 acelerar la investigación.
Seguridad
La API de Kobana usa certificados SSL 2048 bits. Toda solicitud debe hacerse vía HTTPS — las llamadas al puerto 80 son redirigidas 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 son soportados.
Caché HTTP
Usa las cabeceras HTTP de caché para reducir carga y ganar velocidad. La mayoría de las respuestas incluye ETag y/o Last-Modified — guarda estos valores y reenvíalos en las siguientes solicitudes vía 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 fallas del servidor: 500 Internal Server Error (aplicación indisponible), 502 Bad Gateway, 503 Service Unavailable y 504 Gateway Timeout (fallas puntuales de infraestructura). Tu aplicación debe identificar estos códigos y reintentar la solicitud después de algunos minutos con backoff. Estado de los servidores: https://status.kobana.com.br.
Valores monetarios
Los valores monetarios siguen dos convenciones: campos con sufijo _cents (÷100) y campos de precios con sufijo _subcents (÷10000). Usa estas convenciones para convertir a reales (BRL) antes de mostrar al usuario final.