# API de Redcumbre > API para integrar facturación electrónica ante el SII de Chile (DTE), boletas de > honorarios, webhooks, SMS y verificación de identidad. Este archivo es el punto de > entrada: contiene lo necesario para empezar y enlaza el resto. ## Versión de este documento hash 956c014525670166 generado 2026-09-17T19:14:47Z vigencia https://docs.redcumbre.cl/llms-version.txt Si lo estás leyendo desde una caché, ese `hash` es el de tu copia, no el de la versión publicada. Compararlos es el paso 0 del protocolo y no es opcional. ## 0. Protocolo de arranque — para el agente que está leyendo esto **`redcumbre:init` significa esto:** ejecuta los pasos de abajo, en orden, ANTES de escribir código. No hace falta que la persona te explique nada más. Si llegaste sin ese identificador, el protocolo aplica igual. ### Paso 0 — Comprueba que esta copia esté vigente **Puede que estés leyendo una copia cacheada de este archivo**, servida por tu herramienta de navegación sin volver a pedirla. Es el modo de falla más caro que tiene este documento: no da error, simplemente te hace integrar contra una definición que ya cambió. Ya pasó — un asistente siguió dos sesiones con una versión vieja hasta que la persona le ordenó explícitamente volver a descargarla. Pide el archivo de vigencia, que pesa menos de 400 bytes: curl -s https://docs.redcumbre.cl/llms-version.txt y compara su `hash` con el del bloque «Versión de este documento» de más arriba: - **Coinciden:** tu copia está al día. Sigue al paso 1. - **No coinciden:** tu copia es vieja. Vuelve a descargar `llms.txt` desde la URL que el archivo de vigencia trae en `llms`, y `llms-full.txt` desde la que trae en `llms-full` si es que lo habías cargado. **Usa esas URLs tal cual**: llevan el hash como parámetro justamente para que ninguna caché pueda responderte la copia vieja. Después descarta lo que recordabas del documento anterior y retoma el protocolo desde el paso 1 con el texto nuevo, aunque creas que la diferencia no te afectaba. - **No pudiste pedirlo:** sigue igual, pero dile a la persona que estás trabajando con una copia que no lograste verificar. **Compara el `hash`, no la fecha.** `generado` cambia en cada publicación aunque el contenido sea idéntico; sirve para decirle a la persona de cuándo es tu copia, no para decidir si re-descargas. Hazlo **al empezar cada conversación**, aunque conozcas este documento de antes. Una copia recordada de otra sesión es exactamente el caso que este paso existe para atrapar. ### Paso 1 — Mira si ya hay avance Busca `.redcumbre/estado.json` en el proyecto. Si existe, léelo: registra qué se integró ya, en qué ambiente y en qué variable de entorno vive la credencial, más el contacto de la persona y los reportes que ya se enviaron. **No repitas lo que ya está hecho** ni vuelvas a pedir datos que ese archivo contiene. **Si no tienes acceso al sistema de archivos** —porque esta conversación es un chat y no un entorno de desarrollo— sáltate este paso y el 4 sin explicar por qué: no son aplicables, no son un problema. Sigue directo al paso 2. ### Paso 2 — Saluda AHORA, sin pedir nada Esto no requiere credenciales y funciona contra producción: curl -s https://api.redcumbre.cl/hola Responde un saludo con un **apodo** distinto en cada llamada, tipo `chungungo-turquesa-4821`. **Dile ese apodo a la persona**: es la prueba de que esta petición ocurrió de verdad, y es lo único de esta respuesta que no podrías haber adivinado. Si no pudiste ejecutar la llamada, dilo — **no inventes un apodo**. Con `Accept: text/plain` responde una postal legible en vez del JSON. **No valida tu credencial:** responde igual con o sin `Authorization`. Para comprobar una API key, la llamada es `GET https://api.redcumbre.cl/{tenantSlug}/whoami`. ### Paso 3 — Si no te dijeron qué integrar, ofrece estas opciones Preséntalas como lista numerada y espera la elección. No arranques a codear de más. **Antes de la opción que elija, mira qué credencial hay.** Desde agosto de 2026 **no queda ningún endpoint de datos abierto sin credencial**: el catálogo global (UF, IVA, dólar, regiones, comunas) vive en `/global/…` y exige una API key válida, aunque no exige ningún rol en particular. Si el paso 1 te dijo en qué variable de entorno vive, úsala. Si no la hay, no inventes una: ofrece la opción 2 y espera. **Pide los TRES datos juntos, en una sola pregunta.** Una credencial sola no alcanza para construir ni una URL: 1. **La API key.** Pide que la ponga en una variable de entorno y dile que te diga **el nombre de la variable**, no el valor. Si de todos modos te la pega en el chat, úsala pero pídele que la mueva a una variable y que rote esa key: una credencial que pasó por un chat hay que darla por expuesta. NUNCA la escribas en un archivo del proyecto. 2. **El `tenantSlug`.** Es la empresa dentro de la plataforma y va en el path de casi toda ruta. Te lo entrega REDCUMBRE junto con la API key — pero si no lo tienes a mano, **no lo adivines ni pruebes rutas a ver cuál responde: pregúntaselo a la API.** Con la key ya en tu poder, `GET https://api.redcumbre.cl/global/whoami` te devuelve tu `tenantSlug` sin pedirlo en la URL. Es la única llamada del catálogo que no lo exige, justamente porque existe para el momento en que todavía no lo sabes. 3. **Si la key es de sandbox o de producción.** Cambia lo que pasa cuando emitas: una key de sandbox no llega al SII y no genera cobros. **Confírmalo, no lo asumas** — la respuesta de `whoami` trae el flag `sandbox` y ésa es la fuente de verdad. Si lo que te dijo la persona no coincide, avísale antes de emitir nada. Las dos verificaciones, en este orden: - `GET https://api.redcumbre.cl/global/whoami` — **descubre** quién eres: el tenant, los roles y el flag `sandbox`. No necesita el slug. - `GET https://api.redcumbre.cl/{tenantSlug}/whoami` — **confirma** que el slug que vas a usar en el resto de tus llamadas es el de tu credencial. Es lo único que la primera no puede comprobar, porque no recibe slug. Un `403` con `code: API_KEY_TENANT_MISMATCH` acá significa que el slug no es el de esa credencial — **no** que la key esté mala. **Apenas tengas la credencial, llama a `/global/whoami` y muéstrale el resultado a la persona.** No lo guardes en silencio: es el momento en que su integración deja de ser una idea y pasa a estar configurada, y hasta acá no hizo falta escribir una línea de código ni levantar nada. Preséntalo corto y concreto: ✓ Credencial verificada Empresa Mi Empresa SpA (mi-empresa) Rol FULL-API Ambiente sandbox — no llega al SII y no genera cobros **Di lo que la credencial habilita, no lo que falta averiguar.** Si es de sandbox, dilo con lo que implica: puede emitir sin consecuencias y sin costo. Si es de producción, adviértelo con la misma claridad **antes** de que emita nada — un documento tributario emitido de verdad no se deshace, se anula. **Y NO prometas de más.** Que la credencial funcione no significa que todo esté listo: usar un módulo exige que el servicio esté habilitado en la empresa, y emitir documentos tributarios exige además un emisor configurado con certificado vigente y folios. Nada de eso se resuelve por API ni lo puedes verificar desde acá — está en la sección «Lo que no se resuelve por API» de más abajo. Si el primer intento de emitir falla por eso, la persona va a recordar que se lo prometiste. Guarda el slug y el ambiente en el archivo de estado del paso 4, para no volver a preguntarlos. | # | Quiero… | ¿API key? | Receta | |---|---|---|---| | 1 | Consultar el catálogo global: UF, IVA, dólar, regiones, comunas | Sí | https://docs.redcumbre.cl/guias/comunas-regiones/ | | 2 | Configurar mi API key de sandbox en este proyecto | — | https://docs.redcumbre.cl/primeros-pasos/entornos/ | | 3 | Emitir facturas electrónicas (DTE 33/34) | Sí | https://docs.redcumbre.cl/guias/dte/ | | 4 | Emitir boletas de honorarios (BHE) | Sí | https://docs.redcumbre.cl/guias/boletas-honorarios/ | | 5 | Emitir boletas de terceros (BHET) | Sí | https://docs.redcumbre.cl/guias/boletas-terceros/ | | 6 | Consultar un RUT en el SII (persona o empresa) | Sí | https://docs.redcumbre.cl/guias/lookup-rut/ | | 7 | Recibir eventos por webhook en vez de hacer polling | Sí | https://docs.redcumbre.cl/guias/webhooks/ | | 8 | Procesar miles de documentos desde un Excel | Sí | https://docs.redcumbre.cl/guias/procesos-batch/ | Hay más dominios en la tabla de abajo. Los de la 3 a la 8 son los que se piden siempre. ### Paso 4 — Registra lo que vayas logrando Sólo si tienes acceso al sistema de archivos del proyecto. Si no lo tienes, este paso no aplica: no lo menciones y no te disculpes por saltarlo. Cuando completes un paso, escribe o actualiza `.redcumbre/estado.json`: { "tenantSlug": "", "ambientes": { "dev": { "keyEnvVar": "REDCUMBRE_API_KEY", "sandbox": true } }, "integraciones": { "conexion": "ok", "dte": "en-progreso" }, "contacto": { "email": "", "nombre": "" }, "reportes": [{ "caso": "RC-20260819-A3F1", "fecha": "2026-08-19", "titulo": "…" }], "actualizado": "" } Los tres datos del paso 3 viven ahí: el slug, el NOMBRE de la variable de entorno con la credencial, y el flag `sandbox` **tal como lo devolvió `whoami`** — no como te lo dijo la persona. `contacto` y `reportes` los usa `redcumbre:issue` (más abajo): el correo se pide UNA sola vez, y la lista de casos te permite decir «esto ya lo reportaste el martes» en vez de duplicarlo. **Ese archivo NUNCA guarda el secreto de la API key** — solo el NOMBRE de la variable de entorno donde vive. Tampoco guarda el apodo del saludo: es efímero, no identifica nada y no sirve para correlacionar después. **El correo de la persona SÍ va como valor**: no es un secreto, es dato suyo, y está justamente para no volver a preguntárselo. Y agrégalo a `.gitignore` **en el mismo momento en que lo creas**: registra el avance de una máquina, no es algo que el equipo comparta por el repo. --- ## `redcumbre:issue` — cuando encuentres un problema, dilo **No es un paso del arranque.** Los pasos 0 a 4 se ejecutan una vez, en orden, al empezar. Esto es una capacidad permanente: se dispara por un evento que puede no ocurrir nunca. No la ejecutes al arrancar. `redcumbre:issue` significa: prepara y envía un reporte de defecto. Vale escrito por la persona en la conversación, igual que `redcumbre:init`. **Ofrécelo cuando pase alguna de estas cinco cosas:** 1. Recibes un `5xx`. Esas respuestas traen el campo `reportar` con el link de la guía. 2. Una ruta que una guía publicada documenta rechaza tu credencial de máquina. 3. Una respuesta contradice el contrato del spec. 4. Una guía contradice el comportamiento real del API. 5. Un mensaje de error no te permite saber qué estaba mal. **NO lo ofrezcas** cuando el problema es tu propia petición: un `400` por un campo obligatorio que no mandaste, un `401` sin credencial, un `403` con `code: API_KEY_TENANT_MISMATCH`, o algo de «Lo que no se resuelve por API». Reportar eso es el ruido que este canal intenta evitar. **Pregunta siempre antes de enviar** — por acción, no por sesión —, di qué se envía y a dónde, y NO ofrezcas seguimiento del reporte: el repositorio donde queda es interno. Después dile el número de caso a la persona: es su único identificador para citarlo. **Guarda el `x-trace-id` de toda respuesta, también de las exitosas.** Cuando adviertes el defecto, la traza de la llamada anterior ya se perdió, y es el dato que más rinde del reporte entero. El contrato completo, el árbol de decisión y un ejemplo de `curl`: https://docs.redcumbre.cl/guias/reportar-issue/ --- ## Cómo usar el resto de este documento Si ya sabes qué vas a integrar, lee en este orden y no cargues más de lo que necesites: 1. **Este archivo** — entornos, autenticación, dominios y reglas que valen para todo. 2. **La guía del dominio que te toca** — enlazada en la tabla de abajo. Si prefieres todas juntas: https://docs.redcumbre.cl/llms-full.txt (~290 KB, el texto completo de cada guía). 3. **La especificación OpenAPI** — https://api.redcumbre.cl/api-docs-json (~410 KB). Campos, tipos, constraints y códigos de respuesta. Es la fuente de verdad del contrato: si algo acá contradice al spec, gana el spec. **Precedencia, cuando dos fuentes no coinciden:** el spec le gana a cualquier guía —una guía explica, el spec define—, y los valores que cambian por año tributario (tasa de PPM, retención de BHET, IVA) los manda el catálogo `https://api.redcumbre.cl/global/…` consultado en runtime, nunca un número escrito en una guía o en este archivo. Para ubicarte sin bajar el spec entero: https://api.redcumbre.cl/api-docs/index.txt lista todas las rutas en texto plano, agrupadas por dominio. ## Entornos URL base única: https://api.redcumbre.cl No existe un host de sandbox. **El modo sandbox es una propiedad de la API key**, sobre esa misma URL: una key de sandbox no llega al SII, no genera facturación y marca sus respuestas con `sandbox: true`. El flag se fija al crear la key y no se puede editar; para producción se emite una key nueva. Verifica en cuál estás con `GET https://api.redcumbre.cl/{tenantSlug}/whoami`, que devuelve el tenant, los roles de la credencial y su flag de sandbox. Conviene que sea tu primera llamada. Detalle: https://docs.redcumbre.cl/primeros-pasos/entornos/ ## Autenticación API Key como Bearer token, para integraciones server-to-server: Authorization: Bearer El `tenantSlug` va en el path de casi todas las rutas. La API key está asociada a un tenant: si el slug del path no le corresponde, la respuesta es 403. Detalle, y el carril OAuth2: https://docs.redcumbre.cl/primeros-pasos/autenticacion/ ## Reglas que valen para todos los endpoints - **Paginación:** `limit` (default 20, máximo 300) y `offset`. No hay número de página. Los totales vienen al nivel raíz de la respuesta: `{ data, total, limit, offset }`. - **Idempotencia:** `idempotencyKey` (máx. 128 chars) en las emisiones. Si repites la clave para el mismo emisor y tipo, devuelve el documento original sin consumir folio. - **Errores:** formato nativo de NestJS, `{ statusCode, message, error }`. `message` puede ser string **o array de strings** cuando falla la validación del payload. - **Campo `reportar`, sólo en errores del SERVIDOR:** las respuestas con `statusCode >= 500` agregan `reportar` con la URL de https://docs.redcumbre.cl/guias/reportar-issue/. Los rechazos de cliente (`4xx`) NO lo llevan, a propósito: un `400` es casi siempre tu petición, y ofrecerte reportarlo produciría reportes de defectos que no existen. - **Lookups vacíos NO son 404:** una búsqueda por identificador que no encuentra nada responde `200` con `null`. El 404 es para un recurso por ID que debería existir. - **Sin límite de tasa global.** Los hay por caso de uso (OTP de SMS, PIN-RUT). Detalle: https://docs.redcumbre.cl/primeros-pasos/reglas-transversales/ ## Dominios de la API | Dominio | Prefijo | Qué hace | Documentación | |---|---|---|---| | `autorizaciones-v2` | `/{tenantSlug}/autorizaciones-v2` | Flujo de aprobación por supervisores para excepciones comerciales: descuentos fuera de política, precios especiales y excepciones a límites de crédito. | https://docs.redcumbre.cl/guias/autorizaciones/ | | `bhe` | `/{tenantSlug}/bhe` | Boletas de Honorarios Electrónicas: emisión, consulta, descarga y anulación ante el SII. | https://docs.redcumbre.cl/guias/boletas-honorarios/ , https://docs.redcumbre.cl/guias/anulacion-boletas/ | | `bhet` | `/{tenantSlug}/bhet` | Boletas de Honorarios de Terceros: el emisor es la empresa que contrata y paga los servicios prestados por un tercero. | https://docs.redcumbre.cl/guias/boletas-terceros/ , https://docs.redcumbre.cl/guias/anulacion-boletas/ | | `canales` | `/{tenantSlug}/canales` | Despacho de mensajes de plantilla por el número de WhatsApp del tenant, y consulta del estado de un despacho. Las dos rutas son superficie de máquina, con el rol WHATSAPP_MENSAJERIA_DESPACHO. | https://docs.redcumbre.cl/guias/whatsapp/ | | `clientes` | `/{tenantSlug}/clientes` | Cartera de clientes del tenant: alta, consulta por ID, bloqueo y desbloqueo, y administración de los correos y teléfonos a los que se envían los DTE. | https://api.redcumbre.cl/api-docs-json | | `dte` | `/{tenantSlug}/dte` | Documentos Tributarios Electrónicos ante el SII: facturas, notas de crédito y débito, guías de despacho, liquidaciones y boletas. | https://docs.redcumbre.cl/guias/dte/ | | `emisores` | `/{tenantSlug}/emisores` | Deliberado, resuelto en #463: los controllers `:tenantSlug/emisores` y `:tenantSlug/emisores-tributarios` tienen 0 handlers con @ApiKeyAccess y responden 403 a toda API key, y así se quedan. El alta de emisores por API existe por otra vía —Tokenización SII, dominio `tokenizacion`— donde la clave tributaria y el certificado los entrega el propio contribuyente en el wizard, sin pasar por el integrador. El resto de la administración de emisores (listado, edición de sucursales, borrado del certificado) es sólo panel web. guias/emisores.md quedó reescrita en esos términos, así que ya no cita ninguna ruta de este prefijo. | https://docs.redcumbre.cl/guias/emisores/ | | `global` | `/global` | Rutas que exigen credencial válida pero no empresa en la URL, y cuya respuesta es idéntica para toda empresa: el catálogo global de la plataforma —normativa tributaria vigente (IVA, PPM, retención BHET, impuestos adicionales), indicadores del día (UF, dólar) y catálogo territorial de Chile (regiones, comunas)— y el canal de reporte `redcumbre:issue`, por el que un integrador reporta un defecto de la plataforma o de su documentación. | https://docs.redcumbre.cl/guias/comunas-regiones/ , https://docs.redcumbre.cl/guias/reportar-issue/ | | `herramientas` | `/{tenantSlug}/herramientas` | Consulta de datos tributarios de un RUT chileno directamente en el SII: razón social, direcciones y actividades, con caché y modo sandbox. | https://docs.redcumbre.cl/guias/lookup-rut/ | | `hola` | `/hola` | Saludo de arranque del protocolo redcumbre:init. No requiere credencial: es la primera llamada que un agente puede ejecutar antes de que exista una API key. Devuelve un apodo distinto en cada invocación — ésa es la prueba de que la petición ocurrió, porque un asistente no puede inventarlo. No valida la credencial y no devuelve datos de negocio. | https://api.redcumbre.cl/api-docs-json | | `pin` | `/{tenantSlug}/pin` | Verificación de identidad de personas con RUT chileno mediante PIN numérico personal. | https://docs.redcumbre.cl/guias/pin-rut/ | | `procesos-batch` | `/{tenantSlug}/procesos-batch` | Carga masiva por Excel de hasta 5.000 registros, con validación, reintentos automáticos y seguimiento del avance. | https://docs.redcumbre.cl/guias/procesos-batch/ | | `proveedores` | `/{tenantSlug}/proveedores` | Cartera de proveedores del tenant: listado, consulta por ID o por RUT, bloqueo y desbloqueo, y administración de correos y teléfonos para DTE. | https://api.redcumbre.cl/api-docs-json | | `sms` | `/{tenantSlug}/sms` | Envío de mensajes de texto a números chilenos, con procesamiento asíncrono, routing, reintentos y tracking de entrega. | https://docs.redcumbre.cl/guias/sms/ | | `tokenizacion` | `/{tenantSlug}/tokenizacion` | Delegación de credenciales del SII por parte del contribuyente, sin que la clave viaje al integrador: init-session, exchange, invitación y revocación. Es también la única vía de alta de emisores por API — devuelve el emisorId que la emisión de BHE/BHET pide como emisorTributarioId. | https://docs.redcumbre.cl/guias/emisores/ | | `validacion-rut` | `/{tenantSlug}/validacion-rut` | Validación masiva de RUT: carga de archivo, precio por nivel, inicio y cancelación del proceso, y descarga de resultados. | https://api.redcumbre.cl/api-docs-json | | `whoami` | `/{tenantSlug}/whoami` | Verifica la credencial y devuelve el tenant, los roles y el flag de sandbox. Conviene como primera llamada de una integración. | https://api.redcumbre.cl/api-docs-json | Las rutas concretas de cada dominio no se listan acá: están en https://api.redcumbre.cl/api-docs/index.txt, que el API genera en runtime y por eso nunca queda desfasado. ## Otras guías No corresponden a un dominio de la superficie, pero forman parte de la integración: - **dte-xml-format1** — Endpoint SOAP de compatibilidad, aprobado como superficie de máquina pero marcado `oculta` en el snapshot: se sostiene para integradores que migran desde un sistema SOAP, no se promociona a integradores nuevos. → https://docs.redcumbre.cl/guias/dte-xml-format1/ - **identidad-acreditada** — Documenta un evento SALIENTE del carril PIN-RUT: el integrador lo recibe, no lo pide. No expone ninguna ruta propia en la superficie pública, así que no le corresponde un dominio. Su contraparte con rutas es guias/pin-rut. → https://docs.redcumbre.cl/guias/identidad-acreditada/ - **webhooks** — Documenta el mecanismo de notificaciones SALIENTES firmadas con HMAC: el tenant recibe las peticiones, no las emite. No expone rutas propias en la superficie pública, así que no le corresponde un dominio. → https://docs.redcumbre.cl/guias/webhooks/ ## Lo que no se resuelve por API Requiere contacto con REDCUMBRE: emisión de API keys, habilitación de servicios en el tenant, y configuración de un emisor DTE con su certificado digital y folios CAF. No hay auto-registro. - Solicitar una cuenta de integración: https://docs.redcumbre.cl/solicitar-cuenta/ - Guía para integrar con un asistente de IA: https://docs.redcumbre.cl/primeros-pasos/integrar-con-ia/ - Documentación completa: https://docs.redcumbre.cl - Sitio de REDCUMBRE: https://redcumbre.cl ## Primeros pasos - [Autenticación: API Keys y OAuth2](https://docs.redcumbre.cl/primeros-pasos/autenticacion/): Autentica tus llamadas a la API de Redcumbre con API Keys para integraciones server-to-server, u OAuth2 para aplicaciones que actúan en nombre de un usuario final. - [Entornos y modo sandbox](https://docs.redcumbre.cl/primeros-pasos/entornos/): La API de Redcumbre tiene una sola URL base. El modo sandbox no es un servidor distinto: es una propiedad de tu API Key sobre ese mismo host. - [Integrar con tu agente de IA](https://docs.redcumbre.cl/primeros-pasos/integrar-con-ia/): Pásale una URL a tu asistente y tendrá todo el contexto de la API de Redcumbre: entornos, autenticación, endpoints y ejemplos. Con prompts listos para copiar. - [Introducción a la API de Redcumbre](https://docs.redcumbre.cl/primeros-pasos/introduccion/resumen/): La API de Redcumbre permite integrar boletas de honorarios, emisores tributarios, webhooks y SMS en tu aplicación. Empieza la integración acá. - [Reglas transversales de la API](https://docs.redcumbre.cl/primeros-pasos/reglas-transversales/): Paginación, idempotencia, forma de los errores y límites de tasa. Lo que vale para todos los endpoints de la API, en un solo lugar.