Modo de prueba y producción
Todo se prueba primero en el modo de prueba, donde nada llega al SII, nada se cobra y nada se envía a una persona; después se pasa a producción, donde lo emitido llega al SII, se cobra y los avisos le llegan a las personas. Esta mecánica explica las dos llaves, qué simula la prueba y cómo se da el paso con una confirmación. Aplica a todas las fichas.
La URL es una sola: https://api.redcumbre.cl. No hay un servidor sandbox, ni una ruta /sandbox, ni un entorno de staging para integradores. Lo que decide si una llamada es de prueba o de producción es la credencial: cada llave nace como llave de prueba o como llave de producción, y eso no se puede cambiar después. Para operar de verdad se crea una llave de producción; no existe una operación que convierta una de prueba. (api.dev.redcumbre.cl es un entorno interno, no es tu entorno de prueba.)
Con el CLI, en la carpeta del proyecto:
redcumbre initResultado esperado: con la sesión iniciada (redcumbre login; un agente usa redcumbre login --sin-navegador y la persona aprueba el acceso), deja una llave de prueba en keys/redcumbre-prueba.json, apunta el .env a ese archivo con REDCUMBRE_LLAVE_PRUEBA=keys/redcumbre-prueba.json, deja la skill del integrador y comprueba la llave con una llamada. No escribe código ni emite nada. La llave de producción se agrega después, con redcumbre pasar-a-produccion (ver más abajo), en keys/redcumbre-produccion.json y REDCUMBRE_LLAVE_PRODUCCION. Sin terminal y sin sesión, init no crea nada: sale con 4 SIN_SESION y dice que corras redcumbre login.
- Crear llaves exige ser administrador de la empresa. Si la persona no tiene cuenta,
redcumbre solicitar-cuentala pide. keys/,.redcumbre/y.env(si no lo versionas ya) quedan fuera del control de versiones. Revísalo conredcumbre doctor.- El secreto de una llave se muestra una sola vez. No se pide pegar en una conversación, no va al repositorio, no se imprime en pantalla.
Cómo saber en qué modo estás:
redcumbre estadoredcumbre api verificarCredencialResultado esperado: estado muestra el modo de cada llave del proyecto y cuánto queda del tope diario de prueba. verificarCredencial (GET /{tenantSlug}/whoami) devuelve el tenant, el nombre de la credencial, sus roles y credencial.sandbox: true es una llave de prueba. Esa marca describe la llave; en cualquier otra respuesta, el campo sandbox de la raíz describe la operación (true si se atendió en prueba) y nunca falta ni es null. Para ver todas las llaves de la empresa: redcumbre llaves.
Qué es distinto con una llave de prueba:
- Nada llega al SII y no se genera facturación. Las respuestas se resuelven con datos de prueba.
- Cada documento queda marcado con el modo en que se emitió, y esa marca decide la anulación, el correo, la descarga y el enlace público.
- Una llave sólo ve los datos de su modo. Pedir por id un documento del otro modo responde igual que un id inexistente.
- No sale ningún correo, SMS ni WhatsApp a terceros: queda en la bandeja de mensajes simulados (
redcumbre bandeja). - Los webhooks sí se emiten, al destino de prueba de tu empresa y con
sandbox: true. Nunca se desvían al de producción. Ver Webhooks. - Las llaves de prueba que existían antes del modo de prueba actual se retiraron. Si una llave antigua responde
401conINVALID_JWT_TOKEN, la credencial ya no existe: crea una nueva conredcumbre init.
Escenarios
Sección titulada «Escenarios»Los escenarios son los datos y las simulaciones que fuerzan un resultado en prueba. Se leen del API, no se adivinan:
redcumbre escenariosResultado esperado: los emisores de prueba de tu empresa (con su id), los RUT de prueba con su rol y las simulaciones publicadas (operación consultarEscenariosModoPrueba). Con una llave de producción las listas vienen vacías.
RUT de prueba. El modo de prueba reconoce sólo estos diez; su identidad es sintética. Un RUT válido que no está aquí responde lo mismo que un RUT que el SII no conoce (404):
| RUT | Para qué sirve |
|---|---|
77777777-7 | Emisor de documentos tributarios (empresa); hay dos emisores con este RUT: facturación y sólo boletas |
11111111-1 | Emisor de boletas de honorarios propias (persona natural) |
88888888-8 | Emisor de boletas de terceros; también cliente y proveedor |
66666666-6 | Cliente genérico «público general» |
55555555-5 | Cliente genérico extranjero, sin domicilio en Chile |
22222222-2 y 33333333-3 | Clientes y proveedores personas naturales |
12345678-5 | Contribuyente de la tokenización de prueba (clave clave-de-prueba; ver Emisores y tokenización) |
44444444-4 | Receptor que el SII simulado siempre rechaza |
99999999-9 | Responde «no encontrado» |
Los emisores de prueba, con sus clientes, proveedores y productos de ejemplo, vienen precargados: no hay que crearlos. Para un documento tributario: el emisor de facturación de 77777777-7 emite los tipos 33, 34, 43, 46, 52, 56 y 61, y sus boletas (39 y 41) salen por el emisor de boletas del mismo RUT; una boleta por el emisor de facturación se rechaza.
Simulaciones. Hay operaciones que existen sólo en prueba y llevan un documento a un desenlace: reparos del SII, anulación, reclamo y aceptación del receptor en un documento tributario (simularReparosDte, simularAnulacionDte, simularReclamoReceptorDte, simularAceptacionReceptorDte) y la boleta «no anulable» (simularNoAnulableAnulacionBoletaHonorarios, simularNoAnulableAnulacionBoletaTerceros). Llamadas con una llave de producción responden 400 con OPERACION_SOLO_EN_MODO_DE_PRUEBA.
Lo que se comporta distinto. Cada operación declara en x-rcapi-prueba cómo responde en prueba: simulada (corre con datos de prueba), conjunto-de-ejemplo (responde con un conjunto de ejemplo y no escribe nada), sin-efecto (responde igual en los dos modos) o rechazada (no existe en prueba). redcumbre api describir <operación> lo imprime en la línea «En prueba».
Qué responde la copia de prueba y qué el conjunto de ejemplo. Una operación simulada corre sobre la copia de prueba de tu empresa: lo que escribe queda en esa copia, lo lees después y redcumbre restaurar lo borra. Una de conjunto-de-ejemplo valida tu pedido como en producción y responde con datos sintéticos, sin guardar nada: lo que «creaste» no aparece después en los listados, no se cobra, no llama al SII ni al portal y no avisa a nadie. Un caso es el alta directa de emisores y de certificados: ver Alta directa en el modo de prueba. En prueba sólo se rechazan dos cosas en esas operaciones: la falta del servicio exigido (por ejemplo «Alta de emisores con certificado por API», 403 antes de leer el cuerpo) y un .pfx cuya clave no lo abre (400, el mismo que en producción, sin guardar nada). Lo demás responde con el conjunto de ejemplo.
Una operación sin simulación responde 400 con OPERACION_NO_DISPONIBLE_EN_PRUEBA y el motivo; hoy es el caso de crear una verificación PINRUT y de bajar el PDF de respaldo del SII.
Eventos y bandeja.
redcumbre eventosredcumbre eventos disparar dte.emitidoredcumbre bandeja --canal correoResultado esperado: el catálogo de eventos con cuáles se pueden disparar; un evento de prueba enviado a tus webhooks; los mensajes que prueba retuvo en vez de enviar (--canal acepta correo, sms y whatsapp).
Tope diario. Cada servicio admite hasta 200 operaciones de prueba al día por empresa, contadas por separado: dte, bhe, bhet, validacion-rut, tokenizacion, sms, whatsapp, autorizaciones, clientes y proveedores. Cada documento de una emisión masiva cuenta uno en el tope de documentos. Al superarlo, la operación responde 400 con MODO_PRUEBA_TOPE_DIARIO, cuánto queda y que se renueva a las 00:00 de Chile. Se consulta sin consumirlo:
redcumbre api consultarTopeDiarioModoPrueba --param servicio=bheredcumbre consumoResultado esperado: consumidas, remanente, tope y dia. En prueba, consumo muestra los topes del día y no hay cobro.
Restaurar y retención. redcumbre restaurar --confirmar <slug> borra lo que creaste en prueba y vuelve a cargar los datos de ejemplo; no reinicia el tope diario y conserva la configuración del webhook de prueba. Lo creado en prueba se suprime a los 30 días. Usa sólo los RUT de prueba: no cargues datos de personas de verdad: el modo de prueba no los necesita.
Probar sin emitir. Un borrador de documento tributario (saveAsDraft: true) pasa por la misma validación que una emisión, sin consumir folio: sirve para validar un pedido incluso contra producción.
Producción: confirmar
Sección titulada «Producción: confirmar»En producción, lo que se emite llega al SII y se cobra según el plan. Por eso el paso tiene tres cerrojos: una revisión previa, una confirmación y la llave en un archivo que nunca se imprime.
Pasar a producción
Sección titulada «Pasar a producción»redcumbre pasar-a-produccion --servicios dte,bhe --confirmar <slug>Resultado esperado: el CLI revisa qué falta por servicio, crea la llave de producción junto a la de prueba (sin tocarla) y termina con el resumen. Cómo funciona:
- Revisión. Deduce los servicios que usa el proyecto de las llamadas de la llave de prueba. Si la llave no tiene llamadas,
--servicioslos indica (dte,bhe,bhet,procesos-batch,validacion-rut,tokenizacion,emisores,sms,whatsapp,panel-reseller,eventos-saas-reseller,comunicacion,pin-rut,agua-ingreso; sin terminal y sin ellos el comando termina conPASO_A_PRODUCCION_REQUIERE_SERVICIOS; con terminal te pregunta). Para cada servicio comprueba que esté habilitado en la empresa y que exista el emisor de producción que exige (un emisor activo, con credencial vigente y, en documentos tributarios, folios). - Si falta algo termina con
PASO_A_PRODUCCION_INCOMPLETO, muestra lo que falta y no crea la llave. Habilitar un servicio o dejar operativo un emisor no se hace por API: se pide a REDCUMBRE o lo hace la persona en el panel. - Confirmación. Una persona con terminal escribe el identificador (
slug) de la empresa. Sin terminal o con--json,--confirmar <slug>con elslugexacto. Sin esa confirmación, o con otroslug, sale con código 3 yFALTA_CONFIRMACION, imprime el comando completo y no crea ni ejecuta nada. - Instalación en tu sitio (opcional).
--instalar "<comando>"corre tu comando con la llave sólo en la variable de entornoREDCUMBRE_VALOR_LLAVE_PRODUCCION, no en su línea de comandos.--comprobar "<comando>"corre otro, sin la llave, que debe imprimir la respuesta dewhoamide tu sitio en producción: confirma que el sitio quedó con la llave de producción de esa empresa.
Un agente no debe dar este paso solo: pide a la persona el slug de la empresa, dile que lo que emita desde ahí es de producción ante el SII y se cobra según su plan (los precios por operación los da redcumbre tarifas), y recién ahí pásale --confirmar.
La llave de producción no se muestra
Sección titulada «La llave de producción no se muestra»- Queda en
keys/redcumbre-produccion.json(permisos restringidos al usuario) y el.envsólo apunta a ese archivo conREDCUMBRE_LLAVE_PRODUCCION. Ni el CLI ni--jsonimprimen su valor. - No la pidas, no la leas en voz alta, no la pegues en una conversación y no la subas al repositorio. Si se filtra, revócala con
redcumbre llaves revocar <id> --confirmar <slug>y crea otra. - Si la persona no es administradora, el CLI deja el lugar listo para el archivo que ella descarga de la web y explica cómo seguir.
Operar en producción
Sección titulada «Operar en producción»Por omisión, redcumbre api y los demás comandos usan la llave de prueba. Para producción se escribe --produccion, y una operación que escribe, envía o cobra exige además --confirmar <slug>:
redcumbre api emitirBoletaHonorarios --cuerpo @boleta.json --clave orden-compra-4471 --produccion --confirmar <slug>Resultado esperado: la boleta emitida de verdad ante el SII. Sin --confirmar, el comando sale con código 3, imprime el comando completo y no hace nada.
- Lo que sólo consulta (efecto
consulta) no pide confirmación, salvo que la siguiente unidad cruce el umbral de un tramo de precio: entonces avisa y pide confirmar. - Los actos que no se deshacen (pedirle algo al SII, archivar, revocar) piden además que la persona escriba el
slug. --ensayomuestra la petición sin hacerla; úsalo para revisar el pedido antes de confirmar.redcumbre consumo --produccionmuestra lo consumido del plan;redcumbre estado --produccionmuestra el estado de la llave de producción.
Qué hay que tener antes
Sección titulada «Qué hay que tener antes»| Para | Necesitas |
|---|---|
| Llamar cualquier operación | Una llave emitida para tu empresa |
| Usar un servicio en producción | Que el servicio esté habilitado en tu empresa (en prueba, las boletas y la tokenización no lo exigen; el alta de emisores con certificado por API sí lo exige también en prueba) |
| Emitir documentos tributarios | Un emisor DTE configurado, con certificado vigente y folios (CAF) |
Nada de esto se resuelve por API ni lo puede hacer un asistente por la persona: se pide a REDCUMBRE.