Ir al contenido

Reglas comunes de la API

Lo que vale para todas las operaciones y no se repite en cada ficha: cómo se recorre un listado, cómo se leen los errores y qué límites existen. Al final, tres llamadas de comprobación (whoami, hola y mi-suscripcion) que no pertenecen a ningún producto.

Los listados usan limit y offset; en la mayoría no hay número de página.

ParámetroQué es
limitRegistros por página. El máximo es 300 en toda la API; el valor por omisión cambia según la operación (10, 20, 50…)
offsetRegistros a saltar. Por omisión 0
  • Un limit sobre el máximo responde 400: no se recorta en silencio.
  • Tres listados paginan con page en lugar de offset: listarSolicitudesAutorizacion, listarLibrosGuiasDespacho y listarHistorialDeAvisos. redcumbre api describir <operación> muestra qué parámetros tiene cada una.
  • La respuesta trae los totales al nivel raíz, no dentro de data: data (la página), total, limit y offset, más sandbox.

Para recorrerlo todo, sube offset de a limit hasta que offset + data.length >= total. Cuando cambias un filtro, vuelve offset a 0: si no, la primera página del filtro nuevo sale vacía.

Con el CLI:

Ventana de terminal
redcumbre api listarBoletasHonorarios --param estado=<estado> --todas --campos id,folioSii,estado

Resultado esperado: un arreglo con todas las filas de todas las páginas (hasta un máximo de 10.000; si hay más, avisa y pide acotar con --param), con sólo los campos pedidos. --todas sólo sirve en un listado paginado; en otra operación sale con error de uso. Prefiere acotar con filtros (fechas, estado, emisor) antes que recorrer todo.

La API no envuelve los errores en success/data. El formato es el de NestJS:

{
"statusCode": 400,
"message": "El precio unitario debe ser al menos 1 en cada línea. 2 línea(s) tienen precio inválido.",
"error": "Bad Request"
}

Cuando falla la validación del cuerpo, message puede ser un arreglo de textos, uno por campo. Trata message como string | string[]: es la causa más común de que un manejador de errores se rompa en el primer 400. Algunos errores traen además un código estable, y el campo donde viaja depende de la operación: code (por ejemplo MODO_PRUEBA_TOPE_DIARIO y OPERACION_NO_DISPONIBLE_EN_PRUEBA), errorCode (por ejemplo SII_SIN_SEGUNDA_CATEGORIA en una boleta de honorarios), error.code (en ejecutarProcesoBatch y en el PDF del SII de una boleta) o el mismo campo error con el código en lugar de Bad Request (en las operaciones de reseller). Programa contra el código, no contra el texto del mensaje, y mira en cada ficha en qué campo lo entrega su operación; si no sabes cuál es, revisa los tres (code, errorCode y error.code) antes de caer en el texto.

Los errores del servidor (5xx) llevan además reportar, con el enlace a la guía de reporte. Los 4xx no: un 400 casi siempre es un problema del pedido, no un defecto.

Guarda el x-trace-id de la respuesta, también en las exitosas: permite abrir la traza completa de una llamada si hay que reportar un problema.

CódigoQué pasó¿Reintentar?
400El cuerpo no pasó validación o una regla de negocio lo rechazóNo. Corrige el pedido
401Falta la credencial o no es válidaNo. Revisa la llave
403La llave es válida pero no alcanza esa operación, o el tenantSlug no le correspondeNo. Es un problema de rol o de servicio no habilitado
404El recurso pedido por id no existe (o es del otro modo)No
409Conflicto de estado: ya se emitió, ya se anuló, el emisor está revocado…No. Consulta el estado actual antes de decidir
422La operación se entendió pero el contenido o el estado del contribuyente la hace imposible (rechazo del SII, sin folios)No, sin corregir antes
429Límite alcanzadoSí, respetando Retry-After
502Un servicio externo (el SII) respondió algo inutilizableSí, con espera creciente
503No se pudo verificar tu credencial ante el servidor de identidad, o el emisor tiene demasiadas emisiones en cursoSí, esperando los segundos de Retry-After. No rotes la llave: no fue rechazada ni revocada
500Defecto de la plataformaDepende: mira el código estable (code, errorCode o error.code, según la operación). En una emisión puede significar que el documento sí salió (ver Emisión)

Un lookup vacío no es un 404: los endpoints que buscan por un identificador (un RUT, un slug) responden 200 con null cuando no encuentran nada. El 404 se reserva para un recurso pedido por id que debería existir. Si tratas todo null como error, rompes flujos normales.

Un reintento sobre una operación que emite o cobra siempre lleva la misma clave de idempotencia (ver Emisión).

Si el problema parece de la plataforma o de la documentación (no de tu pedido), repórtalo con la operación reportarDefecto (POST /global/issues), que responde 202 con un número de caso. No mandes datos de tus clientes en el reporte, sólo la forma de la petición. redcumbre api describir reportarDefecto lista los campos.

Códigos de salida del CLI. Cuando un comando falla, --json deja un solo JSON con error.codigo y el proceso sale con:

SalidaSignificado
0Bien
1Error del CLI
2Uso incorrecto (una opción mal escrita o faltante)
3Falta una confirmación; el JSON trae el comando que la da
4Sin sesión: redcumbre login
5Sin llave, o la plataforma la rechazó
6La API rechazó el pedido (un 4xx)
7La API no está disponible (un 5xx o sin red)
8El modo no permite esa operación
9Falló una verificación

No hay un límite de tasa global en la API. Los límites son por caso de uso, donde el abuso tiene un costo real:

DóndeLímite
SMS de código de un solo uso (routeType: otp)1 mensaje por número cada 5 minutos
Verificación PINRUTLímite de intentos fallidos
Descarga de PDF de una boletaUn tope por identidad; al superarlo, 429
Búsqueda en la documentación (redcumbre buscar)Un tope por hora y por día por llave; las llaves de una empresa comparten uno diario
Reporte de defectos (reportarDefecto)Un tope por credencial; al superarlo, 429
Modo de prueba200 operaciones por día y por servicio (ver Modo de prueba y producción)

Otros topes del pedido:

  • idempotencyKey: hasta 128 caracteres.
  • limit de un listado: hasta 300.
  • Frase de buscar: hasta 300 caracteres.

Que no exista un límite global no es una invitación a paralelizar sin control: las emisiones tributarias dependen del SII, que tiene sus propios tiempos, y un emisor con demasiadas emisiones en curso recibe 503 hasta que haya turno. Para volumen alto, la vía es la carga masiva (ejecutarProcesoBatch), no muchas llamadas concurrentes. Ante un 429 o un 503, espera lo que dice Retry-After antes de volver a llamar.

whoami responde quién es la credencial con que llamas. Es la primera llamada de una integración: comprueba de una vez que la llave es válida, que el tenantSlug es el correcto, qué roles tiene y si es de prueba. No toca datos de negocio y no depende de ningún servicio contratado, así que un 200 descarta que el problema sea la credencial.

OperaciónRutaPara qué
verificarCredencialGET /{tenantSlug}/whoamiConfirma que el tenantSlug que vas a usar es el de la llave
verificarCredencialSinTenantGET /global/whoamiDescubre el tenantSlug cuando sólo tienes la llave

El CLI no tiene un comando whoami: usa la operación.

Ventana de terminal
redcumbre api verificarCredencial
redcumbre api verificarCredencialSinTenant

Resultado esperado: tenant (slug y nombre), credencial (tipo, nombre, roles y sandbox) y una marca de tiempo. credencial.sandbox: true es una llave de prueba; esa marca describe la llave, no la operación, y por eso la respuesta de whoami no lleva el sandbox de la raíz. redcumbre doctor hace esta comprobación con cada llave del proyecto.

Un 401 es una llave inexistente, revocada o expirada. Un 403 con code: API_KEY_TENANT_MISMATCH en GET /{tenantSlug}/whoami significa que el tenantSlug no es el de esa credencial, no que la llave esté mala: descubre el correcto con verificarCredencialSinTenant. Un 503 con Retry-After no significa que la llave sea inválida: reintenta.

GET /ping (verificarDisponibilidadApi) es otra cosa: un chequeo de disponibilidad anónimo que responde 200 sin credencial, así que no verifica nada de tu llave. No lo uses para comprobarla.

hola es la primera llamada de una integración asistida por un agente: demuestra que la plataforma responde de verdad. Es GET /hola (obtenerSaludoDeArranque), no necesita credencial y tampoco la valida: responde 200 con o sin Authorization, así que un saludo exitoso no confirma que tu llave sirva (para eso, whoami).

Ventana de terminal
curl -s -H "Accept: application/json" https://api.redcumbre.cl/hola

Resultado esperado: 200 con un saludo y un apodo distinto en cada llamada, del tipo chucao-ambar-3253, más hora (de Chile, con el desfase explícito) y ambiente. Sin Accept: application/json responde en texto plano, pensado para una terminal.

{
"success": true,
"data": {
"saludo": "Hola. Estás hablando con la API de Redcumbre.",
"apodo": "chucao-ambar-3253",
"hora": "2026-11-05T03:54:01-03:00",
"ambiente": "produccion",
"siguientePaso": {
"instruccion": "Dile a la persona el apodo de arriba: es la prueba de que esta llamada ocurrió de verdad. Si no pudiste ejecutar la petición, dilo — no lo inventes. Después lee el mapa y ofrécele el menú de tareas.",
"mapa": "https://docs.redcumbre.cl/llms.txt"
}
},
"sandbox": false
}

Qué hace un agente: le dice a la persona el apodo de esa llamada. Un asistente no puede inventarlo, así que es la prueba de que la petición ocurrió. Si no pudo ejecutarla, lo dice: no inventa un apodo. La respuesta no cambia según la llave ni según el modo, no devuelve datos de ninguna empresa y no se cachea (Cache-Control: no-store).

mi-suscripcion es lo consumido del plan. La operación es consultarConsumoDelPlan (GET /{tenantSlug}/mi-suscripcion/consumo): es de lectura y requiere el rol FULL-API.

Ventana de terminal
redcumbre consumo
redcumbre consumo --produccion

Resultado esperado: la respuesta cambia con el modo de la llave.

  • Llave de prueba: modo: "prueba", el mensaje «En modo de prueba no se cobra.» y los topes del día por servicio (consumidas, tope, remanente y dia). No consulta el sistema de cobro ni entrega números del plan.
  • Llave de producción: modo: "produccion", el periodo en curso y las metricas del plan: para cada una, lo usado, lo incluido, lo restante, lo cobrado (en CLP netos) y el precioSiguiente, que dice cuánto costará la próxima unidad y si cruza el umbral de un tramo.

Úsalo antes de una operación grande en producción para saber lo que cuesta, y en prueba para ver cuánto queda del tope diario. El CLI también lo consulta solo antes de confirmar una operación cobrada, para avisar si la siguiente unidad cruza un tramo.