Entornos y modo de prueba

Antes de escribir la primera llamada conviene despejar esto, porque no funciona como en la mayoría de las APIs.

Una sola URL base

https://api.redcumbre.cl

No hay sandbox.redcumbre.cl, ni un path /sandbox, ni un subdominio de staging para integradores. Todas las llamadas —de prueba y reales— van al mismo host.

El modo de prueba es una propiedad de tu llave

Lo que decide si una llamada es de prueba o real no es la URL: es la credencial. Cada llave se crea como llave de prueba o como llave real, y eso no se puede cambiar después.

La llave de prueba se crea de dos formas:

Con el CLI, en la carpeta de tu proyecto: npx @redcumbrecl/cli init deja una llave de prueba sin preguntar, en keys/redcumbre-prueba.json. --entorno prueba|real elige cuál instalas: la real, cuando estés listo, con npx @redcumbrecl/cli init --entorno real. Con el CLI instalado, redcumbre api opera la API desde la terminal con la llave del proyecto.
En el panel, en la pantalla de llaves de API, marcando «Llave de prueba» al crearla.

Con una llave de prueba:

No se llama a servicios externos reales. Nada llega al SII. Las respuestas se resuelven con datos de prueba.
No se genera facturación. Ningún evento de billing se emite.
Cada respuesta viene marcada. Toda respuesta JSON de éxito lleva sandbox en la raíz: true con una llave de prueba y false con una real, nunca ausente ni null. Así tu código distingue el modo sin depender de qué llave cargó el entorno. El detalle está en Reglas transversales.
Cada documento queda marcado con el modo en que se emitió. Esa marca, no el folio, decide todo lo que viene después: la anulación, el correo, la descarga y el enlace público. Una boleta de prueba lleva además un folio simulado con prefijo (SANDBOX- en BHE, SBX en BHET) como marca visible, así que si reprocesas un webhook viejo el folio te dice de dónde salió.
Una llave sólo ve los datos de su modo. Con la llave de prueba no ves nada real, y con la real no ves nada de prueba: pedir por su id un documento del otro modo responde exactamente lo mismo que un id que no existe.
No sale ningún correo a terceros. Ni la boleta recién emitida ni el comprobante de una anulación. Una boleta de prueba tampoco se puede reenviar por correo desde el panel: con el modo de prueba desactivado no aparece, y con el modo de prueba activado el panel es de sólo lectura. La supresión se decide por el modo del documento, no por la credencial que pide el envío: una boleta emitida en el modo de prueba nunca despacha correo. Lo que habría salido queda en la bandeja de mensajes simulados de tu empresa, con su destinatario, su canal y su contenido ya renderizado, y la lees por API con GET /{tenantSlug}/modo-prueba/bandeja.

Los webhooks sí se emiten en el modo de prueba, al endpoint de prueba que configures en tu empresa, con sandbox: true en el payload: son la mitad de lo que necesitas ejercitar. Si no configuras un endpoint de prueba, los eventos de prueba no llegan a ese endpoint: no se desvían a tu endpoint real. Un evento real nunca llega al endpoint de prueba. Lo que no ocurre es la comunicación con una persona real.
Hay un tope diario por servicio. Cada servicio admite hasta 200 operaciones de prueba al día por empresa (por ejemplo, 200 BHE y aparte 200 BHET). La operación que lo excede responde 400 con el código MODO_PRUEBA_TOPE_DIARIO, cuánto te queda y que el tope se renueva a las 00:00 en hora de Chile. Consultas cuánto te queda, sin consumirlo, con GET /{tenantSlug}/modo-prueba/tope-diario/{servicio} (bhe, bhet, tokenizacion, …).

El modo no se puede editar

Para operar de verdad se crea una llave real. No hay un endpoint ni una opción de panel que convierta tu llave de prueba en una llave real.

No es una omisión, es un control deliberado: el secreto de una llave de prueba ya está repartido por los entornos del integrador, y muy probablemente commiteado en algún repositorio. Si el modo fuera editable, esa credencial ya expuesta pasaría a emitir documentos reales ante el SII y a generar cobros, sin rotar el secreto y sin que nadie se entere.

Las dos llaves conviven en el mismo tenant. No son dos cuentas ni dos contratos: es una credencial más.

Cómo saber en qué modo estás

curl -s https://api.redcumbre.cl/{tenantSlug}/whoami \
  -H "Authorization: Bearer $REDCUMBRE_API_KEY"

{
  "success": true,
  "data": {
    "tenant":     { "slug": "tu-tenant", "nombre": "Tu Empresa SpA" },
    "credencial": { "tipo": "api_key", "nombre": "Integración ERP", "roles": ["FULL-API"], "sandbox": true },
    "timestamp":  "2026-08-18T14:32:10.512Z"
  }
}

Es la primera llamada que conviene hacer al integrar: confirma de una vez que la llave es válida, que el tenantSlug es el correcto, qué roles tienes y si es de prueba.

Hay dos marcas y dicen cosas distintas:

credencial.sandbox del whoami describe la llave: si fue creada de prueba o real. Por eso va dentro de credencial y la respuesta del whoami no lleva la marca de raíz.
sandbox en la raíz de cualquier otra respuesta describe la operación: si se atendió en modo de prueba (true) o en real (false).

`api.dev.redcumbre.cl` no es tu entorno de prueba

Vas a encontrar ese dominio si buscas. Es el entorno interno de desarrollo de REDCUMBRE, no está disponible para integradores y su contenido cambia sin aviso. La especificación OpenAPI de producción no lo declara como servidor, justamente para que nadie lo tome por un entorno de prueba público.

Para probar, la vía es una llave de prueba contra la URL de producción.

Boletas de honorarios y de terceros en el modo de prueba

Con una llave de prueba las boletas se emiten de punta a punta: la plataforma corre la misma validación, guarda la boleta, genera su PDF y te manda los mismos webhooks que en real. Lo único que no ocurre es lo que tiene efecto fuera: el SII, el cobro y el correo a una persona.

Ocurre en el modo de prueba	No ocurre
Emitir BHE y BHET con los emisores de prueba de tu empresa, sin clave del SII y sin el servicio contratado	Ninguna llamada al SII ni folio real consumido
Las mismas validaciones y los mismos rechazos que en real	Ningún cobro: tu consumo facturable no cambia
Folio simulado, estado, PDF generado de verdad con la marca «DOCUMENTO DE PRUEBA — SIN VALIDEZ TRIBUTARIA» en cada página	El respaldo del SII: su estado queda `NO_APLICA`
Anular, reintentar y llevar una anulación a «no anulable» con una acción de simulación	Ningún documento de prueba abre por un enlace público: el enlace se entrega igual y responde como uno inexistente
Emisión masiva por archivo (`procesos-batch`): el lote corre de verdad y cada fila cuenta una en el tope	Correo al destinatario: queda en la bandeja de mensajes simulados
Tokenizar al contribuyente de prueba, sólo con clave tributaria	Ninguna validación de clave contra el SII
Webhooks, al endpoint de prueba	Un webhook de prueba no se desvía a tu endpoint real

El catálogo de RUT de prueba, lo que simula cada servicio, el retiro de las API Keys de prueba anteriores y cuánto se conserva lo que creas están en Modo de prueba. Los valores de prueba que provocan cada camino —el emisor de cada boleta, el receptor que el SII simulado rechaza y el contribuyente de la tokenización con su clave— están además en las guías de Boletas de Honorarios, Boletas de Terceros, Anulación y Emisores.

Qué necesitas pedirle a REDCUMBRE

Estas cosas no se resuelven por API y ningún asistente las va a poder hacer por ti:

Para	Necesitas
Llamar cualquier endpoint	Una llave (de prueba o real) emitida para tu tenant
Usar un módulo concreto en real	Que el servicio esté habilitado en tu tenant. En el modo de prueba las boletas y la tokenización no lo exigen
Emitir documentos tributarios	Un emisor DTE configurado, con certificado digital vigente y folios CAF

Escribe a tu contacto en REDCUMBRE para cualquiera de las tres.

Siguiente paso

Autenticación — cómo firmar tus llamadas
Reglas transversales — paginación, idempotencia y errores
Integrar con tu agente de IA — si vas a delegarle la integración