Arranque: por dónde empezar según dónde esté la persona
Esta página es para ti, el agente, cuando la persona te pide algo con REDCUMBRE y todavía no sabes en qué estado está su proyecto. Léela entera una vez: te dice qué mirar primero, qué preguntar, a qué ficha ir y en qué orden trabajar. Las fichas explican un producto (qué emisor necesita, paso a paso, qué falla); las mecánicas explican algo que cruza productos (cómo se inscribe un emisor, cómo se emite, cómo se firma un webhook). Esta página sólo te orienta hacia ellas.
Reglas que valen siempre
Sección titulada «Reglas que valen siempre»- Empiezas siempre en el modo de prueba. Lo que emites no llega al SII y no consume folios. El modo de producción lo decide una persona, no tú (Modo de prueba y producción).
- Lo que se emite con la llave de producción es de producción ante el SII y se cobra según el plan. Los precios por operación los da
redcumbre tarifas(o el panel web, sección Mi suscripción); el aviso de cobros se le da a la persona una vez, al conectar el proyecto (lo traeinitenbienvenida.aviso). Antes de cualquier paso que lo haga, díselo a la persona con esas palabras y espera su sí. - Nunca leas, imprimas ni copies el contenido de
keys/, ni le pidas a la persona que pegue una llave o una clave en el chat. El CLI lee la llave por ti; tu código la lee de la ruta que apuntaREDCUMBRE_LLAVE_PRUEBA. - Nunca pidas la clave tributaria ni el certificado de nadie, ni le pidas a la persona que los pegue en el chat. La persona los escribe en el asistente del SII (tokenización) y tú recibes el identificador del emisor. Sólo si la empresa tiene el servicio «Alta de emisores con certificado por API», un
.pfxque la persona te indica por su ruta se sube con el CLI (--archivo), y su clave se lee con--clave-desde-stdino un prompt oculto, nunca como argumento: ver Alta directa y certificados. - No inventes campos ni operaciones. Lo que no encuentres en una ficha o en el contrato de la operación, no lo afirmes: pregunta o dilo.
- Cierra siempre con un reporte: qué quedó hecho, qué comandos corriste y con qué resultado, qué falta y quién lo hace, y en qué modo quedó el proyecto (prueba o producción).
Paso 0: deja listo el entorno
Sección titulada «Paso 0: deja listo el entorno»Lo primero de cada sesión es comprobar el CLI:
redcumbre --versionSi no responde, el CLI no está instalado: dilo al principio de tu respuesta e instálalo tú, sin preguntarle a la persona: npx @redcumbrecl/cli@latest instalar, y sigue con redcumbre …. Si la instalación falla, dile qué pasó y, mientras tanto, corre una vez npx @redcumbrecl/cli@latest --version y usa esa versión fija en todo comando que corras o le muestres (npx @redcumbrecl/cli@<versión> doctor), nunca redcumbre … a secas.
Después, antes de elegir un camino, comprueba que el proyecto está conectado:
redcumbre doctorResultado esperado: dice si la sesión, la empresa y la llave de prueba están en orden y, si falta algo, qué comando lo arregla (comando en la salida con --json).
- Falta la sesión:
redcumbre login --sin-navegadorentrega una dirección y un código. Pásaselos a la persona; cuando apruebe, correredcumbre login --completar. Aprueba sólo el código que la persona pidió con ese comando. - Falta conectar el proyecto:
redcumbre init --sin-navegador. Deja la llave de prueba enkeys/, un puntero en el.env, la skill del integrador y una comprobación con la llave. No emite nada y no escribe código del proyecto. - No hay cuenta ni empresa (el CLI lo dice con
SIN_EMPRESAS): tú no lo resuelves. La persona la pide enhttps://docs.redcumbre.cl/solicitar-cuenta/o corriendoredcumbre solicitar-cuentaen una terminal. No afirmes que se envió una solicitud: sin terminal el CLI no la envía, y una persona de REDCUMBRE responde la que llegue por el formulario, de modo que no es inmediato. Cuando llegue la cuenta, vuelve alogineinit. - Hay una versión más nueva del CLI (la respuesta con
--jsontraeactualizacion, y un aviso enavisos): actualízalo tú, antes de lo que te pidieron y sin preguntarle a la persona: córrelo conactualizacion.comando(redcumbre actualizar, o su forma por npx), que deja al día el CLI y la skill, y dilo al principio de tu respuesta. Si la actualización falla, dile qué pasó. - El CLI corre por npx (la respuesta trae
instalacionconinstalado: false): instálalo tú, antes de lo que te pidieron y sin preguntarle a la persona: córrelo coninstalacion.comando. Mientras no esté instalado, todo comando que corras o le muestres va coninstalacion.prefijo(npx @redcumbrecl/cli@<versión> …) en lugar deredcumbre. Si un aviso dice que la skill tiene cambios y está desactualizada, no la reemplaces por tu cuenta.
Entrevista antes de construir
Sección titulada «Entrevista antes de construir»Antes de escribir código o de correr una operación, entrevista a la persona, salvo que el contexto ya lo diga (su pedido, el código del proyecto, la conversación). Pregunta sólo lo que falta, de a una o dos preguntas a la vez:
- Qué quiere lograr, dicho como una tarea («emitir una boleta de honorarios cuando se paga un pedido») y en qué parte del proyecto vive.
- Dónde está hoy: ¿ya hay un sistema?, ¿el paso se hace a mano?, ¿ya usa otra API?, ¿ya integró REDCUMBRE?, ¿no hay proyecto? (es la bifurcación de la sección siguiente.)
- Quién emite. Si el profesional emite por sus propios servicios son boletas de honorarios (BHE, sólo personas naturales); si la empresa le paga a un tercero y emite en su nombre son boletas de terceros (BHET). La persona no siempre sabe nombrarlo: pregúntalo con el ejemplo concreto.
- Uno o varios RUT. Lo habitual en boletas de terceros es un solo RUT, el de la empresa; algunas emiten desde más de uno. En honorarios, a veces el profesional es la misma empresa y otras son externos que le prestan servicios (como en un marketplace) y cada uno tiene que autorizar su propia cuenta.
- Si hay emisores externos, cómo entran: por un enlace que la aplicación de la persona les entrega en ese momento, o por un correo de invitación que envía REDCUMBRE.
- Cómo se entera su sistema del resultado: ¿su servidor puede recibir webhooks, o prefiere una redirección con un código que se canjea?
- Qué PDF necesita: ¿basta el interno o necesita el del SII?
- Qué debe pasar cuando algo falla (un rechazo del SII, una entrega que no llega) y si se parte en el modo de prueba (siempre se parte ahí).
- Si no hay proyecto: qué quiere hacer a grandes rasgos, si quiere una interfaz web y dónde crear la carpeta. El lenguaje y el framework no se preguntan: los decides tú (lo más simple que ya esté instalado) y lo cuentas en el reporte final.
Las respuestas 3 a 7 eligen la variante, y cada una vive en una mecánica:
| La respuesta decide | Dónde está explicado |
|---|---|
| Qué clase de emisor hace falta (tributario o de documentos tributarios) | Emisores y tokenización, quién emite |
| Uno o varios emisores, y si son propios o de terceros | Uno o varios y Propios o externos |
| Enlace o correo para inscribirlos | Las dos entradas |
| Webhook o redirección con código | Los dos retornos y Webhooks |
| Crear el emisor y subir su certificado con la llave (servicio habilitado) | Alta directa y certificados |
| PDF interno o del SII | Documentos y PDF |
| Emitir sin esperar al SII, o esperándolo | Emisión, modos |
Con las respuestas, arma el flujo combinando la ficha del producto con esas mecánicas: un caso nuevo, como un marketplace que emite boletas de honorarios de cientos de profesionales, no necesita su propia receta; sale de la ficha de honorarios más la mecánica de tokenización en su variante «externos, por enlace, con retorno por webhook».
Los puntos de partida
Sección titulada «Los puntos de partida»Casi todo caso cae en uno de estos seis. Todos recorren el mismo flujo del producto; sólo cambia el paso 0 (leer lo que existe, o crearlo). Pasar a producción es igual en todos.
A. Hay un sistema y el paso se hace a mano
Sección titulada «A. Hay un sistema y el paso se hace a mano»Cómo lo reconoces: hoy, por ejemplo, emiten la boleta de honorarios en el sitio del SII, descargan el PDF y lo suben a mano a su sistema. Quieren emitirla automáticamente y guardar el PDF.
- Lee el proyecto antes de preguntar: el lenguaje y el marco, dónde se guarda hoy la boleta y su PDF, y cuál es el paso manual que se reemplaza. No toques código todavía.
- Entrevista (sección anterior), empezando por quién emite.
- Sigue el flujo de la ficha: Boletas de honorarios (o Boletas de terceros si emite la empresa a un tercero).
- Escribe el código en el lugar del paso manual, guarda el folio y el PDF donde el sistema guardaba el que subían a mano, y recibe el webhook.
B. No hay nada: la persona quiere probar una idea
Sección titulada «B. No hay nada: la persona quiere probar una idea»Cómo lo reconoces: carpeta vacía o sin integración, y una idea («quiero que mi sitio emita boletas»).
- Pregunta lo que falta: qué quiere hacer a grandes rasgos, si quiere una interfaz web y dónde crear el proyecto. No preguntes el lenguaje ni el framework: elige lo más simple que ya esté instalado y cuéntalo en el reporte final.
- Crea el proyecto con el generador habitual del lenguaje que elegiste; el CLI de REDCUMBRE no crea proyectos ni escribe código. Si quiere interfaz, una mínima.
- Corre el paso 0 de esta página (
doctor,login,init) dentro de esa carpeta. - Sigue el flujo de la ficha del producto, en modo de prueba, y déjalo corriendo.
El cuello de botella de este caso es la cuenta: si la persona no tiene una, la integración se detiene en el paso 0 hasta que una persona de REDCUMBRE responda. Dilo desde el principio.
C. Migrar desde otro proveedor
Sección titulada «C. Migrar desde otro proveedor»Cómo lo reconoces: ya emiten automáticamente con otra API. No se reemplaza un paso manual: se cambia una llamada por otra.
- Lee el código que llama al proveedor actual y haz una lista de campos, estados y webhooks que usa.
- Por cada uno, busca su equivalente en REDCUMBRE (ficha del producto y Emisión, Webhooks) y escribe la tabla de correspondencias. Lo que no tenga equivalente, díselo a la persona antes de cambiar nada.
- Inscribe los emisores en REDCUMBRE (Emisores y tokenización): cada titular autoriza su cuenta del SII en el asistente de tokenización; tú no manejas su clave tributaria. Con el servicio «Alta de emisores con certificado por API» habilitado, también puedes crear el emisor y subir su certificado con la llave: si no está habilitado, esas operaciones responden
403también en prueba y el servicio lo activa REDCUMBRE o el reseller de la empresa. - Cambia la llamada en modo de prueba, verifica estados y webhooks, y recién entonces propón pasar a producción.
D. Ya integrado con REDCUMBRE
Sección titulada «D. Ya integrado con REDCUMBRE»Cómo lo reconoces: el proyecto ya tiene llaves en keys/, un .redcumbre/ o código que llama a la API. Quieren agregar otro servicio (por ejemplo, boletas de terceros a quien ya emite documentos tributarios), pasar a producción o diagnosticar algo que falla.
- Parte leyendo lo que hay:
redcumbre doctor,redcumbre estado(en qué modo está cada llave y cuánto queda del tope diario de prueba),redcumbre llaves(las llaves de la empresa, marcando las de este proyecto) y el código que ya usa la API. - Para diagnosticar,
redcumbre llamadasmuestra las últimas llamadas hechas con la llave del proyecto. Mira la ficha del producto, su tabla «Qué puede fallar» y la mecánica que corresponda antes de proponer un cambio. - Para agregar un servicio, ve a su ficha. Para pasar a producción, a Modo de prueba y producción.
E. Operar sin proyecto
Sección titulada «E. Operar sin proyecto»Cómo lo reconoces: la persona quiere hacer algo ahora, sin escribir código: emitir una boleta, consultar un RUT, subir una carga masiva. El CLI es la herramienta y no hay integración.
- Usa una carpeta de trabajo y el paso 0 (
initno escribe código del proyecto). - Ve a la ficha del producto: Boletas de honorarios, Consulta de RUT, Carga masiva, SMS.
- Ejecuta con
redcumbre api(orden de la sección siguiente). En modo de prueba, con los emisores y RUT deredcumbre escenarios. Si lo que pide es emitir de verdad, es un paso a producción: confírmalo con la persona.
F. Reseller
Sección titulada «F. Reseller»Cómo lo reconoces: construye un producto para sus propios clientes y tiene que crear empresas, asignarles planes, medir su consumo y administrarlas. Es un flujo propio, con una credencial de máquina distinta de la llave del proyecto.
Ve a la ficha Reseller. Si lo que necesita es emitir documentos de un cliente, además la del producto que corresponda; para las liquidaciones, Liquidaciones.
El ejemplo completo: boletas de honorarios
Sección titulada «El ejemplo completo: boletas de honorarios»Los puntos A y B terminan en el mismo flujo. Con boletas de honorarios (BHE) se ve así; el detalle y los comandos exactos están en la ficha Boletas de honorarios.
- Arranque: leer el proyecto (A) o crearlo (B), y preguntar quién emite.
- Cuenta y llave de prueba:
redcumbre login --sin-navegadoreinit; sin cuenta,solicitar-cuenta. - Ver cómo responde: emitir una boleta con el emisor de prueba (
redcumbre escenarioslo lista) antes de escribir código. - Emitir desde el código: la operación
emitirBoletaHonorarios, con unaidempotencyKeypropia, y guardar el folio que devuelve. - Guardar el PDF: el interno al emitir y el del SII cuando llegue, donde el sistema guardaba el que subían a mano.
- Recibir los webhooks
bhe.emitida,bhe.emision_terminada,bhe.pdf_sii_fallido,bhe.emision_falliday los de credencial rechazada y restablecida, con la firma verificada. - Probar de punta a punta en modo de prueba, webhook incluido (
redcumbre prueba verificar). - Pasar a producción: inscribir el emisor de producción (el profesional autoriza su clave del SII sin entregártela, con
redcumbre tokenizar), guardar suemisorId(se recupera conredcumbre emisores tributarios listar), crear la llave de producción y hacer la primera emisión de producción. - Operar: anular, el resultado incierto de una emisión y la credencial rechazada.
El orden de trabajo con el CLI: buscar, describir, api
Sección titulada «El orden de trabajo con el CLI: buscar, describir, api»Para cada cosa que el proyecto necesite de REDCUMBRE, en este orden:
-
Carga la ficha del producto (y las mecánicas que nombra):
redcumbre guiasin tema lista los disponibles, yredcumbre guia boletas-honorariostrae la ficha en Markdown, sin sesión ni llave. Sin red entrega su última copia y dice su fecha. -
Buscar la operación por lo que se quiere hacer («emitir una boleta de honorarios»), sin datos de una persona: la búsqueda encuentra operaciones por la tarea, y un RUT, un nombre, un correo o un teléfono no ayudan a encontrarlas:
Ventana de terminal redcumbre buscar "emitir una boleta de honorarios"Resultado esperado: guías y operaciones de la API que calzan, con su
operationId. (Si tu versión del CLI no traebuscar, usaredcumbre api buscar "<texto>".) -
Describir su contrato:
Ventana de terminal redcumbre api describir emitirBoletaHonorariosResultado esperado: parámetros, cuerpo, efecto (
consulta,crea,modificaoenvia), métrica, qué hace en modo de prueba y los roles que pide. No inventes campos: usa los del contrato. -
Ejecutar con
redcumbre api, primero con--ensayo(muestra la petición sin hacerla) y recién después sin él, con la llave de prueba:Ventana de terminal redcumbre api emitirBoletaHonorarios --cuerpo @boleta.json --ensayoredcumbre api emitirBoletaHonorarios --cuerpo @boleta.jsonResultado esperado: el ensayo imprime el método, la ruta y el cuerpo; la ejecución, la respuesta del API en modo de prueba. Los datos van con
--param clave=valory--cuerpo(JSON,@archivoo-). Una escritura que lleva clave de repetición recibe una del CLI, que la imprime; para reintentar sin duplicar, repite el comando con--clave <esa clave>. -
Verificar el sitio de la persona:
redcumbre prueba verificarcomprueba que recibe los webhooks, valida la firma y no repite el efecto de una entrega duplicada.
Con --json el CLI no pregunta y deja un solo JSON en la salida; el código de salida dice qué pasó (0 listo, 3 falta una confirmación, 4 falta la sesión, 5 la llave falla, 6 la API respondió un error 4xx, 7 la API no respondió, 9 la verificación falló). Cuando un error trae comando, es lo que corres a continuación.
Otros comandos útiles en el modo de prueba: redcumbre escenarios (emisores y RUT de prueba), redcumbre bandeja (los correos y mensajes que la prueba retuvo en vez de enviar), redcumbre eventos y redcumbre eventos disparar <evento>, redcumbre restaurar (limpia lo emitido en prueba; pide confirmar).
Pasar a producción
Sección titulada «Pasar a producción»Lo decide la persona. Cuando todo funciona en modo de prueba, díselo con estas palabras antes de correr nada: «lo que se emita con la llave de producción es de producción ante el SII y se cobra según tu plan; ¿quieres que pase?». Los precios por operación los da redcumbre tarifas (o el panel web, sección Mi suscripción); el aviso de cobros ya se le dio una vez, al conectar el proyecto (lo trae init en bienvenida.aviso). Con su sí:
redcumbre pasar-a-produccion --confirmar <slug-de-la-empresa>Resultado esperado: el CLI revisa que todo esté en orden y agrega la llave de producción al proyecto (keys/redcumbre-produccion.json), sin mostrarla. Con otro slug no hace nada. Desde ahí, cada llamada a producción lleva --produccion y las escrituras --confirmar <slug>. La llave de producción tampoco la lees ni la copias. El detalle de qué cambia y qué verificar está en Modo de prueba y producción.
Todas las piezas
Sección titulada «Todas las piezas»Mecánicas (cómo funciona algo que cruza productos):
| Pieza | De qué trata |
|---|---|
| Emisores y tokenización | Quién emite, uno o varios, propios o externos, cómo se inscribe un emisor (por tokenización o con el certificado por API), actualizar, revocar y credencial rechazada |
| Emisión | Modos de emisión, idempotencia y qué hacer con un resultado incierto |
| Documentos y PDF | El PDF interno y el del SII, cómo se descargan y dónde guardarlos |
| Webhooks | Firma, eventos y reintentos |
| Modo de prueba y producción | Las dos llaves, los escenarios de prueba y cómo se pasa a producción |
| Reglas comunes | Paginación, forma de los errores y límites |
Fichas (un producto cada una):
| Ficha | Para qué |
|---|---|
| Boletas de honorarios | Emitir y anular boletas de honorarios de una persona natural |
| Boletas de terceros | Emitir y anular boletas de terceros |
| Documentos tributarios | Facturas, boletas, notas de crédito y de débito, guías de despacho |
| Consulta de RUT | Consultar un RUT en el SII |
| Validación masiva de RUT | Validar muchos RUT en un proceso |
| SMS | Enviar mensajes de texto a teléfonos chilenos |
| PINRUT | Verificar la identidad de una persona con su RUT y un PIN |
| Carga masiva | Emisión masiva desde una planilla |
| Clientes y proveedores | Mantener los clientes y proveedores de la empresa |
| Liquidaciones | Liquidaciones entre reseller y clientes |
| Reseller | Administrar la cartera de un reseller, con el servicio de alta de emisores con certificado y su retiro |
| Comunicación | Recibir solicitudes en los formularios de la empresa |
| Configuración de Comunicación | Perfiles y marcas; crear, archivar y restaurar asistentes; su perfil y encendido; vincular sus fuentes y declarar su propósito |
| Despachar mensajes de plantilla por el número de la empresa | |
| Compras y libros | Leer, aceptar o reclamar los documentos que recibe la empresa, y sincronizar y descargar los libros de compras y de ventas |
| Folios y CAF | Subir un CAF, solicitar folios al SII, anular folios y configurar la solicitud automática |
| Configuración de la empresa | Clave de ValidaFirma (se escribe y no se lee), logo, modos de emisión, información de pago y plantillas |
| Usuarios y organización | Invitar y administrar personas, roles, grupos, áreas, puestos y sucursales, con los límites de lo que una llave no puede hacer |
| aguaSSR | Cargar y mantener el padrón de una cooperativa de agua potable rural con lotes de fichas |
Si lo que necesitas no calza con ninguna, busca en la referencia (redcumbre buscar) y lee el contrato de la operación antes de afirmar nada.