Ir al contenido

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.

  • 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 trae init en bienvenida.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 apunta REDCUMBRE_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 .pfx que la persona te indica por su ruta se sube con el CLI (--archivo), y su clave se lee con --clave-desde-stdin o 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).

Lo primero de cada sesión es comprobar el CLI:

Ventana de terminal
redcumbre --version

Si 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:

Ventana de terminal
redcumbre doctor

Resultado 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-navegador entrega una dirección y un código. Pásaselos a la persona; cuando apruebe, corre redcumbre 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 en keys/, 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 en https://docs.redcumbre.cl/solicitar-cuenta/ o corriendo redcumbre solicitar-cuenta en 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 a login e init.
  • Hay una versión más nueva del CLI (la respuesta con --json trae actualizacion, y un aviso en avisos): actualízalo tú, antes de lo que te pidieron y sin preguntarle a la persona: córrelo con actualizacion.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 instalacion con instalado: false): instálalo tú, antes de lo que te pidieron y sin preguntarle a la persona: córrelo con instalacion.comando. Mientras no esté instalado, todo comando que corras o le muestres va con instalacion.prefijo (npx @redcumbrecl/cli@<versión> …) en lugar de redcumbre. Si un aviso dice que la skill tiene cambios y está desactualizada, no la reemplaces por tu cuenta.

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:

  1. Qué quiere lograr, dicho como una tarea («emitir una boleta de honorarios cuando se paga un pedido») y en qué parte del proyecto vive.
  2. 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.)
  3. 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.
  4. 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.
  5. 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.
  6. 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?
  7. Qué PDF necesita: ¿basta el interno o necesita el del SII?
  8. 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í).
  9. 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 decideDó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 tercerosUno o varios y Propios o externos
Enlace o correo para inscribirlosLas dos entradas
Webhook o redirección con códigoLos dos retornos y Webhooks
Crear el emisor y subir su certificado con la llave (servicio habilitado)Alta directa y certificados
PDF interno o del SIIDocumentos y PDF
Emitir sin esperar al SII, o esperándoloEmisió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».

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.

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.

  1. 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.
  2. Entrevista (sección anterior), empezando por quién emite.
  3. Sigue el flujo de la ficha: Boletas de honorarios (o Boletas de terceros si emite la empresa a un tercero).
  4. 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»).

  1. 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.
  2. 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.
  3. Corre el paso 0 de esta página (doctor, login, init) dentro de esa carpeta.
  4. 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ómo lo reconoces: ya emiten automáticamente con otra API. No se reemplaza un paso manual: se cambia una llamada por otra.

  1. Lee el código que llama al proveedor actual y haz una lista de campos, estados y webhooks que usa.
  2. 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.
  3. 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 403 también en prueba y el servicio lo activa REDCUMBRE o el reseller de la empresa.
  4. Cambia la llamada en modo de prueba, verifica estados y webhooks, y recién entonces propón pasar a producción.

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.

  1. 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.
  2. Para diagnosticar, redcumbre llamadas muestra 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.
  3. Para agregar un servicio, ve a su ficha. Para pasar a producción, a Modo de prueba y producción.

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.

  1. Usa una carpeta de trabajo y el paso 0 (init no escribe código del proyecto).
  2. Ve a la ficha del producto: Boletas de honorarios, Consulta de RUT, Carga masiva, SMS.
  3. Ejecuta con redcumbre api (orden de la sección siguiente). En modo de prueba, con los emisores y RUT de redcumbre escenarios. Si lo que pide es emitir de verdad, es un paso a producción: confírmalo con la persona.

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.

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.

  1. Arranque: leer el proyecto (A) o crearlo (B), y preguntar quién emite.
  2. Cuenta y llave de prueba: redcumbre login --sin-navegador e init; sin cuenta, solicitar-cuenta.
  3. Ver cómo responde: emitir una boleta con el emisor de prueba (redcumbre escenarios lo lista) antes de escribir código.
  4. Emitir desde el código: la operación emitirBoletaHonorarios, con una idempotencyKey propia, y guardar el folio que devuelve.
  5. Guardar el PDF: el interno al emitir y el del SII cuando llegue, donde el sistema guardaba el que subían a mano.
  6. Recibir los webhooks bhe.emitida, bhe.emision_terminada, bhe.pdf_sii_fallido, bhe.emision_fallida y los de credencial rechazada y restablecida, con la firma verificada.
  7. Probar de punta a punta en modo de prueba, webhook incluido (redcumbre prueba verificar).
  8. Pasar a producción: inscribir el emisor de producción (el profesional autoriza su clave del SII sin entregártela, con redcumbre tokenizar), guardar su emisorId (se recupera con redcumbre emisores tributarios listar), crear la llave de producción y hacer la primera emisión de producción.
  9. 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:

  1. Carga la ficha del producto (y las mecánicas que nombra): redcumbre guia sin tema lista los disponibles, y redcumbre guia boletas-honorarios trae la ficha en Markdown, sin sesión ni llave. Sin red entrega su última copia y dice su fecha.

  2. 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 trae buscar, usa redcumbre api buscar "<texto>".)

  3. Describir su contrato:

    Ventana de terminal
    redcumbre api describir emitirBoletaHonorarios

    Resultado esperado: parámetros, cuerpo, efecto (consulta, crea, modifica o envia), métrica, qué hace en modo de prueba y los roles que pide. No inventes campos: usa los del contrato.

  4. 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 --ensayo
    redcumbre api emitirBoletaHonorarios --cuerpo @boleta.json

    Resultado 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=valor y --cuerpo (JSON, @archivo o -). 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>.

  5. Verificar el sitio de la persona: redcumbre prueba verificar comprueba 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).

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í:

Ventana de terminal
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.

Mecánicas (cómo funciona algo que cruza productos):

PiezaDe qué trata
Emisores y tokenizaciónQuié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ónModos de emisión, idempotencia y qué hacer con un resultado incierto
Documentos y PDFEl PDF interno y el del SII, cómo se descargan y dónde guardarlos
WebhooksFirma, eventos y reintentos
Modo de prueba y producciónLas dos llaves, los escenarios de prueba y cómo se pasa a producción
Reglas comunesPaginación, forma de los errores y límites

Fichas (un producto cada una):

FichaPara qué
Boletas de honorariosEmitir y anular boletas de honorarios de una persona natural
Boletas de tercerosEmitir y anular boletas de terceros
Documentos tributariosFacturas, boletas, notas de crédito y de débito, guías de despacho
Consulta de RUTConsultar un RUT en el SII
Validación masiva de RUTValidar muchos RUT en un proceso
SMSEnviar mensajes de texto a teléfonos chilenos
PINRUTVerificar la identidad de una persona con su RUT y un PIN
Carga masivaEmisión masiva desde una planilla
Clientes y proveedoresMantener los clientes y proveedores de la empresa
LiquidacionesLiquidaciones entre reseller y clientes
ResellerAdministrar la cartera de un reseller, con el servicio de alta de emisores con certificado y su retiro
ComunicaciónRecibir solicitudes en los formularios de la empresa
Configuración de ComunicaciónPerfiles y marcas; crear, archivar y restaurar asistentes; su perfil y encendido; vincular sus fuentes y declarar su propósito
WhatsAppDespachar mensajes de plantilla por el número de la empresa
Compras y librosLeer, aceptar o reclamar los documentos que recibe la empresa, y sincronizar y descargar los libros de compras y de ventas
Folios y CAFSubir un CAF, solicitar folios al SII, anular folios y configurar la solicitud automática
Configuración de la empresaClave de ValidaFirma (se escribe y no se lee), logo, modos de emisión, información de pago y plantillas
Usuarios y organizaciónInvitar y administrar personas, roles, grupos, áreas, puestos y sucursales, con los límites de lo que una llave no puede hacer
aguaSSRCargar 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.