Ir al contenido

Emisores y tokenización

Todo documento tributario sale de un emisor: un contribuyente (un RUT) cuya autorización REDCUMBRE guarda para actuar ante el SII en su nombre. Esta mecánica explica cómo se inscribe, cómo se mantiene y cómo se corta esa autorización. La usan las fichas de boletas de honorarios, boletas de terceros y documentos tributarios.

Dos caminos, una regla. El camino de siempre es la tokenización: el titular entrega su clave o su certificado en un asistente de REDCUMBRE y tú recibes sólo el identificador del emisor. El segundo camino es el alta directa con certificado: tu llave FULL-API crea el emisor y sube el .pfx con su clave, pero sólo si tu empresa tiene el servicio «Alta de emisores con certificado por API» (ver El servicio del alta directa). La regla que no cambia en ninguno de los dos: la clave de un certificado entra una sola vez, en el pedido que sube el archivo, y no vuelve en ninguna respuesta, bitácora ni evento. La clave tributaria, en cambio, nunca entra por tu integración: sólo por el asistente.

Hay dos clases de emisor y no se intercambian:

Emisor tributarioEmisor DTE
Para qué sirveBoletas de honorarios (BHE) y de terceros (BHET), y consultas al SIIFacturas, boletas, notas de crédito y de débito, guías de despacho
Cómo se autentica ante el SIIClave tributaria o certificado digitalSólo certificado digital
Identificador que pide la emisiónemisorTributarioId (en emitirBoletaHonorarios y emitirBoletaTerceros)emisorDteId (en emitirDte)
Operaciones de administraciónredcumbre emisores tributarios …redcumbre emisores dte …

El identificador que te entrega la tokenización (emisorId) es el emisorTributarioId o el emisorDteId de la emisión, según el tipoEmisor con que abriste la sesión. El de una clase no sirve en la otra. Es un texto opaco: no lo construyas ni lo interpretes.

Si no tienes el emisorId, lístalo con tu llave:

Ventana de terminal
redcumbre emisores tributarios listar
redcumbre emisores dte listar

Resultado esperado: una fila por emisor con emisorId, rut, razonSocial y estado (el tributario muestra además credencialEstado; el DTE, tipoIntegracion).

  • Emisor tributario: uno por RUT dentro de tu empresa. Si el mismo RUT vuelve a autorizar, la tokenización devuelve el mismo emisorId.
  • Emisor DTE: un mismo RUT puede tener más de uno: uno de facturación (PORTAL_MIPYME o FULL_DTE, nunca los dos) y uno de boletas (SOLO_BOLETA). Por eso la emisión pide el id y no el RUT: el id dice por cuál de ellos sale el documento. Pedir facturación y boletas en la misma sesión devuelve dos emisores en emisores.
  • Con varios emisores, uno puede quedar por defecto: redcumbre emisores tributarios fijar-por-defecto <id> o redcumbre emisores dte fijar-por-defecto <id>. Sólo un emisor activo puede serlo; uno inactivo o revocado responde 409 con EMISOR_INACTIVO_NO_PUEDE_SER_DEFAULT.
  • Un emisor DTE tiene sucursales: redcumbre emisores sucursales listar <emisorId>.

Cada carril de un emisor DTE se certifica por su cuenta ante el SII. FULL_DTE y SOLO_BOLETA nacen inactivos (estado: ESPERA_CERTIFICACION, tiposHabilitados: []) y quedan operativos cuando el SII resuelve, lo que se mide en días; llega un evento emisor.certificado por cada carril. PORTAL_MIPYME nace operativo y sus tiposHabilitados son los que el SII le tiene autorizados: varían de una empresa a otra, no supongas que emite todos los tipos del carril. Para releer del SII los tipos autorizados: redcumbre emisores dte sincronizar <id>.

  • Propios: el RUT es de tu empresa. La persona de tu empresa que tiene la clave o el certificado completa el asistente.
  • Externos: el RUT es de un cliente tuyo (una plataforma que emite en nombre de sus usuarios). Cada cliente autoriza con su propia clave o certificado, en un enlace que tú le compartes o que REDCUMBRE le envía por correo. Tú nunca ves lo que escribe.

En los dos casos el titular conserva el control: recibe un correo con un enlace de revocación y puede quitar la autorización cuando quiera, sin pasar por ti (ver Revocar). Todo emisor externo debería saberlo antes de autorizar.

Cómo se autentica el emisor ante el SII se elige al abrir la sesión, con tipoAutenticacion:

tipoAutenticacionQué entrega el titular en el asistenteVale para
CLAVE_TRIBUTARIASu clave del SIIEmisor tributario
CERTIFICADO_DIGITALUn archivo .pfx y su contraseñaEmisor tributario y emisor DTE (el DTE sólo acepta esta)

Para abrir una sesión hay dos operaciones, con la misma configuración de emisor:

  • iniciarTokenizacionSii (POST /{tenantSlug}/tokenizacion/init-session): tú compartes la authorizationUrl que te devuelve. El RUT es opcional: el titular puede escribirlo en el asistente.
  • invitarTokenizacionSii (POST /{tenantSlug}/tokenizacion/invite): REDCUMBRE envía el correo de invitación. El RUT y el correo del autorizador son obligatorios y acepta idempotencyKey (hasta 128 caracteres) para reintentar sin duplicar la invitación.

Emisor tributario con clave tributaria, aviso por webhook:

{
"rut": "12345678-5",
"email": "persona@ejemplo.cl",
"tipoAutenticacion": "CLAVE_TRIBUTARIA",
"tipoEmisor": "tributario",
"webhookUrl": "https://tu-sitio.cl/webhooks/redcumbre",
"correlationId": "alta-cliente-4471"
}

Resultado esperado: 201 con data.sessionId, data.authorizationUrl (el enlace que abre el titular) y data.emitterOperation, que dice de antemano si el RUT va a crear un emisor nuevo (CREATE) o a actualizar uno que ya existe (UPDATE).

{
"success": true,
"data": {
"sessionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"authorizationUrl": "https://app.redcumbre.cl/p/tokenizacion/a1b2c3d4-5678-90ab-cdef-1234567890ab/authorize",
"emitterOperation": "CREATE"
},
"sandbox": true,
"cobro": { "modo": "prueba", "mensaje": "En modo de prueba no se cobra." }
}

Invitación por correo a un emisor tributario:

{
"rut": "12345678-5",
"email": "persona@ejemplo.cl",
"tipoAutenticacion": "CLAVE_TRIBUTARIA",
"tipoEmisor": "tributario",
"idempotencyKey": "invitacion-cliente-4471"
}

Emisor DTE: siempre CERTIFICADO_DIGITAL, y declaras qué emisores quieres con tipoIntegracion (facturación), boletas: true (boletas) o ambos. Una configuración que no pide ninguno, o que no trae emailEmpresa, responde 400 y no deja sesión creada. email es el del autorizador (recibe la invitación y el enlace de revocación); emailEmpresa es el que aparece en la factura. Son distintos.

{
"rut": "76123456-0",
"email": "autorizador@ejemplo.cl",
"emailEmpresa": "facturacion@ejemplo.cl",
"tipoAutenticacion": "CERTIFICADO_DIGITAL",
"tipoEmisor": "dte",
"tipoIntegracion": "FULL_DTE",
"boletas": true
}

El RUT de este ejemplo es ficticio: reemplázalo por el del contribuyente.

Quién completa el asistente: el titular, una persona. El asistente exige consentimiento explícito y una verificación anti-automatización, así que un agente no lo completa por ella: le pasa el enlace y espera el resultado.

Precio: abrir una sesión o invitar consulta el SII en producción (la operación declara la métrica sii_lookup). Lo que cuesta depende de tu plan: redcumbre tarifas iniciarTokenizacionSii --produccion e invitarTokenizacionSii, y canjearCodigoTokenizacion para el canje.

Ventana de terminal
redcumbre tokenizar --rut 12345678-5 --tipo tributario --autenticacion clave

Resultado esperado: abre el navegador en el asistente, espera a que la persona termine y muestra el emisor inscrito. Variantes:

Ventana de terminal
# Que REDCUMBRE le envíe la invitación por correo a quien autoriza, y termina
redcumbre tokenizar --rut 12345678-5 --tipo tributario --autenticacion clave --invitar persona@ejemplo.cl
# Modo agente: deja un solo JSON con el enlace para la persona
redcumbre tokenizar --rut 12345678-5 --tipo tributario --autenticacion clave --json

Por omisión usa la llave de prueba. Para un emisor en producción, --produccion --confirmar <slug>.

Cuando el titular termina, te enteras de dos maneras. Se eligen al abrir la sesión (init-session exige al menos una de las dos; sin ninguna responde 400):

RetornoCómo se declaraQué recibesÚsalo cuando
Redirección con códigoreturnUrlEl titular vuelve a tu sitio con ?code=…. Canjeas el código una sola vez con canjearCodigoTokenizacion y obtienes el emisorTu aplicación quiere mostrar la confirmación al instante
WebhookwebhookUrlUn POST firmado a tu servidor con el evento tokenizacion.completadaEl proceso corre en tu backend y el titular puede cerrar la ventana

Puedes declarar los dos. La invitación por correo no lleva webhookUrl: el evento va a la URL por defecto de tu empresa, si existe y tiene habilitado tokenizacion.completada. Cómo se firma y se verifica ese POST: Webhooks.

Canje del código (el código expira a los 10 minutos y sirve una vez):

{
"code": "83aK0esV0V21u8-krvuMiXx1OqheSVy56E6tBG3OjX8"
}
{
"success": true,
"data": {
"emisorId": "cmikf6ei00001sek0mxzcf668",
"rut": "12345678-5",
"tipoAutenticacion": "CLAVE_TRIBUTARIA",
"tipoEmisor": "tributario",
"emitterOperation": "CREATE"
},
"sandbox": true
}

En una sesión DTE la respuesta (y el webhook) traen además emisores: todos los que creó la sesión, cada uno con carril, estado, motivoInactivo y tiposHabilitados. emisorId apunta al de facturación si pediste uno; emisores es la única forma de conocer el id del segundo.

Sin navegador (por ejemplo, en una terminal remota), redcumbre tokenizar … --sin-navegador muestra la página final con un código; la persona lo pega en la terminal. Un agente que no puede esperar el navegador hace redcumbre tokenizar … --json, le entrega el enlace a la persona y termina con:

Ventana de terminal
redcumbre tokenizar canjear --codigo <código>

Resultado esperado: el emisor inscrito, con su emisorId.

Con una llave de prueba recorres el flujo completo (abrir, invitar, completar el asistente, canjear, revocar) sin ninguna llamada al SII y sin tener contratado el servicio. En prueba sólo completa una sesión el contribuyente de prueba, con su clave publicada:

RUTClave tributaria
12345678-5clave-de-prueba
  • Cualquier otro RUT o clave sale por el mismo camino que un rechazo de producción: la sesión queda fallida y la respuesta es el mismo 400. Sirve para ensayar el camino de error.
  • Completar el asistente deja un emisor tributario de prueba para 12345678-5, con boletas de honorarios habilitadas y sin credenciales. Su emisorId es el emisorTributarioId con el que emites boletas de honorarios de prueba.
  • En prueba el asistente acepta sólo clave tributaria y sólo emisor tributario: tipoAutenticacion: CERTIFICADO_DIGITAL y tipoEmisor: dte se rechazan con 400 al abrir la sesión. El emisor DTE de prueba viene precargado en tu empresa (redcumbre escenarios lo muestra), no hay nada que tokenizar.
  • invitarTokenizacionSii sólo acepta RUT del catálogo de prueba. El correo de invitación no sale a nadie: queda en redcumbre bandeja.
  • Completar el asistente cuenta una de las 200 tokenizaciones de prueba por día. Lo que queda: redcumbre api consultarTopeDiarioModoPrueba --param servicio=tokenizacion.
  • Los webhooks llegan al destino de prueba con sandbox: true.

Hay dos cosas distintas:

  • Cambiar las credenciales o renovar el certificado: por tokenización, abres una sesión nueva sobre el mismo RUT y el titular entrega la clave o el .pfx vigente (con el servicio del alta directa, además, puedes subir tú el .pfx nuevo: ver Alta directa y certificados). El emisor no se duplica, el certificado anterior se reemplaza y la respuesta trae emitterOperation: UPDATE con el mismo emisorId. Un certificado vencido deja al emisor sin credenciales hasta que se hace esto.
  • Cambiar los datos del emisor (nombre, giro, logo, información de pago, sucursales, tipos habilitados): con tu llave FULL-API.
Ventana de terminal
redcumbre emisores tributarios editar <id> --cuerpo @cambios.json
redcumbre emisores dte editar <id> --cuerpo @cambios.json
redcumbre emisores dte sincronizar <id>

Resultado esperado: el emisor actualizado. sincronizar vuelve a leer del SII razón social, giro, actividades, sucursales y, en PORTAL_MIPYME, los tipos autorizados; si el SII no responde, no cambia nada. Si deja conflictos, se resuelven con redcumbre emisores dte resolver-conflictos <id>. sincronizar consulta el SII de producción, así que se rechaza con una llave de prueba.

Para consultar la vigencia del certificado de un emisor tributario: redcumbre emisores tributarios certificado <id> (nunca entrega serie, huella ni titular). Subir, reemplazar o borrar el certificado con tu llave es posible sólo con el servicio del alta directa; ver Alta directa y certificados.

Archivar y reactivar cambian cuántos emisores cuenta tu plan (el emisor archivado deja de contar); su precio: redcumbre tarifas archivarEmisorDte --produccion. El emisor DTE se archiva repitiendo su RUT: redcumbre emisores dte archivar <id> --rut <rut>. Los actos ante el SII del emisor DTE (certificación, migración, Portal MiPyme) los ejecuta el RUT del representante legal, dejan una solicitud registrada y su avance se consulta con redcumbre emisores dte solicitudes <id>; en el modo de prueba se rechazan todos, salvo el cambio de ambiente, que se simula. Quién representa a la empresa: redcumbre emisores representantes listar.

Las diez operaciones de esta sección exigen que la empresa tenga habilitado el servicio «Alta de emisores con certificado por API» (código EMISORES_CON_CERTIFICADO_API). Es un servicio manual, sin cobro y sin módulos del panel: sólo abre estas operaciones a la llave. Quién lo activa:

  • Una empresa sin reseller: lo activa el equipo master de REDCUMBRE (y lo apaga).
  • Una empresa con reseller: lo activa el reseller en cada hija, siempre que lo tenga en su catálogo de servicios. El master no lo activa en una empresa que tiene reseller: responde 400.

Rige desde la llamada siguiente. Sin el servicio, la llave recibe 403 en las diez operaciones, también con una llave de prueba y antes de leer el cuerpo, así que la respuesta no dice si un RUT, un emisor o un certificado existen. Una persona administradora que opera desde el panel no necesita el servicio.

Con el servicio habilitado y tu llave FULL-API, las diez operaciones son:

OperaciónQué haceComando
crearEmisorDteDirectoCrea un emisor DTE asociado al certificado de un representante legal que ya está cargadoredcumbre emisores dte crear
crearEmisorTributarioDirectoCrea un emisor tributario con metodoAutenticacion: CERTIFICADO_DIGITAL (con llave no se acepta claveTributaria: 400)redcumbre emisores tributarios crear
subirCertificadoDeEmisorTributarioSube o reemplaza el .pfx de un emisor tributario (campos file y password)redcumbre emisores tributarios certificado-subir <id>
eliminarCertificadoDeEmisorTributarioBorra el certificado de un emisor tributarioredcumbre emisores tributarios certificado-quitar <id>
renovarCertificadoDeRepresentanteLegalReemplaza el certificado de un representante legal (campos pfxFile y password)redcumbre emisores representantes renovar-cert <id>
subirCertificadoSube un certificado a Certificados de tu empresa (campos certificate y password)redcumbre certificados subir
listarCertificadosLista los certificados con su vigenciaredcumbre certificados listar
obtenerCertificadoMetadatos de un certificadoredcumbre certificados ver <id>
verificarCertificadoDescifra el certificado y comprueba su huellaredcumbre certificados verificar <id>
eliminarCertificadoDesactiva un certificado de tu empresaredcumbre certificados eliminar <id>

El orden depende del emisor. Un emisor DTE se crea sobre un representante legal cuyo certificado ya está cargado (subirCertificado, que además prueba el ingreso al portal del SII). Un emisor tributario se crea primero y su certificado se sube después con subirCertificadoDeEmisorTributario. Las altas conservan el cobro de siempre (el emisor cuenta en tu plan); activar el servicio y subir o borrar certificados no cobra.

El .pfx y su clave:

  • El archivo viaja como multipart/form-data (--archivo en el CLI) y su clave en el mismo pedido. Nunca vuelven en una respuesta: ni el archivo, ni la clave, ni el RUT, el sujeto o la huella del certificado.
  • El CLI nunca recibe la clave como argumento (quedaría en el historial del terminal y en la lista de procesos): la lee de --clave-desde-stdin, de la variable de entorno REDCUMBRE_CLAVE_PFX o de un prompt oculto. El archivo sí va por --archivo.
  • Un campo que no existe en el cuerpo responde 400; una clave que no abre el archivo responde 400 y no guarda nada.

Un certificado compartido entre empresas. Un mismo representante legal puede operar en más de una empresa y su certificado es uno solo. Si lo renuevas, el certificado nuevo rige para todas, y los administradores de la otra empresa reciben un aviso (sin el nombre de la empresa que lo hizo). Por la misma razón, borrar con una llave un certificado que está activo en un emisor de otra empresa responde 403 sin decir cuál, y no cambia nada: eso se hace desde el panel.

Avisos a los administradores. Con llave y sólo en producción, REDCUMBRE avisa a los ADMIN y SUPER-ADMIN de la empresa (campana y correo) en siete casos: un emisor creado con certificado, un certificado subido, renovado o borrado, el certificado de un representante renovado en otra empresa, y el servicio apagado (a la empresa y, si tiene reseller, también al reseller). Cada aviso nombra la llave, la operación y el emisor o el representante; nunca datos del certificado. Lo que haces desde el panel no avisa por esta vía, y en el modo de prueba no sale ningún aviso.

Retirar el servicio. Si el servicio se apaga en una empresa, las diez operaciones vuelven a responder 403 a la llave y los administradores reciben un aviso. Lo ya creado (emisores, certificados) no se borra. Cuando el reseller lo quita de su catálogo, se apaga en todas sus hijas; ver Reseller.

Con una llave de prueba sólo se rechazan dos cosas: la falta del servicio (403) y un .pfx cuya clave no lo abre (400, el mismo rechazo que en producción). Todo lo demás se valida como en producción y responde con el conjunto de ejemplo: un emisor o un certificado sintético que no se guarda, no se cobra, no llama al SII ni al portal y no avisa. El emisor sintético de un alta directa de prueba no aparece después en el listado de emisores, y un certId que no es del conjunto responde como un certificado inexistente.

Revocar corta la autorización: el emisor queda revocado y no puede emitir. Puede hacerlo el titular (con su enlace de revocación, validando su identidad) o tú:

{
"emisorId": "cmikf6ei00001sek0mxzcf668",
"tipoEmisor": "tributario",
"motivoRevocacion": "El cliente terminó el contrato"
}
Ventana de terminal
redcumbre emisores revocar <emisorId> --tipo tributario --motivo "El cliente terminó el contrato"

Resultado esperado: 201 con el emisor y su revokedAt; el titular recibe un correo con el motivo y a ti te llega el evento emisor.revocado (con revokedBy: ADMIN si lo revocaste tú, USER si lo hizo el titular). Revocar no pide la clave del titular. Detalles que evitan sorpresas:

  • No se puede revocar el emisor tributario por defecto (400): fija otro antes. Revocar un emisor ya revocado también responde 400.
  • Una llave no deshace una revocación. Reactivar un emisor revocado responde 409 con EMISOR_REVOCADO_REQUIERE_TOKENIZACION: hace falta una tokenización nueva. Un emisor DTE suspendido por REDCUMBRE responde 409 con EMISOR_SUSPENDIDO_POR_MASTER y no se reactiva con una llave.
  • Archivar (archivarEmisorTributario, archivarEmisorDte) no revoca la autorización ni borra la credencial; para eso es revocar.
  • En producción, redcumbre emisores revocar pide escribir el identificador de la empresa: --produccion --confirmar <slug>.

A veces el SII deja de aceptar la clave o el certificado de un contribuyente (la cambió, venció, bloqueó la cuenta). REDCUMBRE abre un episodio, detiene lo que depende de esa credencial, avisa a la empresa por correo y te manda un evento, una sola vez por episodio:

CarrilRechazoRestablecimientoQué detiene
Emisor DTE (portal)dte.credencial_portal_rechazadadte.credencial_portal_restablecidaSólo la emisión por Portal MiPyme; FULL_DTE y SOLO_BOLETA siguen emitiendo
Boletas de honorariosbhe.credencial_rechazadabhe.credencial_restablecidaLa emisión de BHE
Boletas de tercerosbhet.credencial_rechazadabhet.credencial_restablecidaLa emisión de BHET

Qué hace un agente: no reintentes emitir. Avísale a la persona que su cliente debe corregir la credencial en el portal del SII. Cuando lo confirme, dispara un intento:

Ventana de terminal
redcumbre emisores tributarios credencial reintentar <id>
redcumbre emisores dte credencial reintentar <id>

Resultado esperado: 200 con el desenlace del intento, el mismo cuerpo en los dos carriles.

{
"restablecida": false,
"motivo": "El certificado digital no se encuentra habilitado para este RUT",
"intentado": true,
"sandbox": false
}
CampoSignificado
restablecidatrue si después del intento la credencial quedó sana (sale entonces el evento de restablecimiento)
motivoLo que dijo el SII; null si no dio motivo o si restablecida es true
intentadofalse cuando no había credencial que probar; no es un error
  • Responde 200 aunque la credencial siga rechazada: el desenlace es el cuerpo, no el status. Un 404 es un emisor que no existe o no es de tu empresa.
  • Un intento por confirmación, nunca un bucle. Cada llamada hace un login real al portal del SII, y el SII bloquea la cuenta del contribuyente tras varios fallos seguidos. REDCUMBRE ya hace un intento automático por día mientras el episodio siga abierto.
  • Si el emisor está revocado, reintentar responde 409 con EMISOR_REVOCADO_REQUIERE_TOKENIZACION: la salida es una tokenización nueva.
  • En el modo de prueba no existe una credencial rechazada: reintentar responde como un reintento exitoso.