Emisores Tributarios y Emisores DTE

TL;DR - Acceso Rápido

Endpoint principal: POST /{tenantSlug}/tokenizacion/init-session

El alta de emisores por API se hace con Tokenización SII, no con endpoints de creación directa. El flujo termina entregándote el emisorId, que es el mismo emisorTributarioId que piden POST /{tenantSlug}/bhe y POST /{tenantSlug}/bhet.

👉 Ver documentación completa en Swagger

El Sistema de Gestión de Emisores de Redcumbre permite administrar las entidades autorizadas para realizar operaciones tributarias ante el SII de Chile. Ya sea que necesites delegar credenciales de tus usuarios o gestionar múltiples sucursales para emitir documentos tributarios, nuestra plataforma lo resuelve de forma segura y eficiente.

---

Tipos de Emisores

Redcumbre ofrece dos tipos de emisores según tu caso de uso:

Aspecto	Emisores Tributarios	Emisores DTE
Propósito	Delegación de credenciales SII (OAuth2-like)	Gestión de emisores para documentos tributarios
Autenticación	Clave tributaria O Certificado digital	SOLO Certificado digital
Uso principal	BHE, consultas SII, reportes	Facturas, boletas, notas de crédito
Estructura de datos	Simple (RUT, razón social)	Compleja (direcciones, actividades, zona SII)
Control del usuario	Usuario final controla sus credenciales	Administrador gestiona emisores
Múltiples direcciones	No	Sí (sucursales, casa matriz)

---

Qué se hace por API y qué desde el panel

El alta de un emisor sí se puede hacer íntegramente por API, pero el camino es Tokenización SII: tú abres la sesión desde tu backend, el contribuyente entrega sus credenciales en un wizard de Redcumbre, y tú recibes el emisorId de vuelta. No existen —ni están previstos— endpoints de creación directa de emisores con API key: la clave tributaria y el certificado digital nunca viajan por tu integración.

Operación	Por API	Cómo
Dar de alta un emisor tributario, o uno o dos emisores DTE	✅	POST /{tenantSlug}/tokenizacion/init-session o /invite
Obtener el emisorId tras la autorización	✅	POST /{tenantSlug}/tokenizacion/exchange o el webhook tokenizacion.completada
Actualizar credenciales / renovar certificado	✅	Nueva sesión de tokenización sobre el mismo RUT (emitterOperation: "UPDATE")
Revocar un emisor	✅	POST /{tenantSlug}/tokenizacion/revoke
Consultar datos SII de un RUT	✅	POST /{tenantSlug}/herramientas/lookup-rut — ver Lookup RUT
Listar los emisores del tenant	❌	Panel web (Configuración → Emisores)
Consultar o eliminar el certificado almacenado	❌	Panel web
Editar direcciones, sucursales y actividades económicas	❌	Panel web

Guarda el emisorId cuando lo recibas

Hoy no hay endpoint de listado de emisores con API key. Los ids te llegan una sola vez, al completarse la tokenización: guárdalos en tu sistema junto al RUT. Una sesión DTE que pide facturación y boletas devuelve dos emisores en el campo emisores, y los dos hay que guardarlos. Si los pierdes, tienes que consultarlos en el panel web o volver a tokenizar el mismo RUT (que devuelve los mismos emisores con emitterOperation: "UPDATE").

---

Flujos de Integración

Existen 4 flujos para integrar la tokenización de credenciales, según cómo quieras recibir la confirmación. Estos flujos aplican tanto para Emisores Tributarios como para Emisores DTE.

¿Cuál flujo elegir?

• Redirect: Cuando necesitas feedback inmediato al usuario en tu app
• Webhook: Cuando el procesamiento es backend y el usuario puede cerrar la ventana
• Dual: Cuando necesitas ambos (redundancia)
• Invite: Cuando prefieres que Redcumbre envíe el email de invitación

---

Flujo 1: Redirect con Code (OAuth2 clásico)

Ideal cuando tu aplicación necesita feedback inmediato al usuario después de autorizar.

Tu App                    Redcumbre                   Usuario
  │                           │                          │
  │── POST /init-session ────▶│                          │
  │   (returnUrl)             │                          │
  │◀── authorizationUrl ──────│                          │
  │                           │                          │
  │── Redirige usuario ───────┼─────────────────────────▶│
  │                           │                          │
  │                           │◀── Completa wizard ──────│
  │                           │    (ingresa credenciales)│
  │                           │                          │
  │◀── Redirect returnUrl?code=xyz ─────────────────────│
  │                           │                          │
  │── POST /exchange ────────▶│                          │
  │   (code)                  │                          │
  │◀── emisorId, rut, etc ────│                          │

Cuándo usarlo:

• Quieres mostrar confirmación inmediata al usuario en tu app
• Necesitas el emisorId para continuar un flujo en tu frontend
• Patrón OAuth2 tradicional

Configuración:

{
  "returnUrl": "https://tu-app.com/callback",
  "tipoAutenticacion": "CLAVE_TRIBUTARIA",
  "tipoEmisor": "tributario"
}

---

Flujo 2: Webhook (Server-to-Server)

Ideal para procesamiento backend sin necesidad de redirect.

Tu App                    Redcumbre                   Usuario
  │                           │                          │
  │── POST /init-session ────▶│                          │
  │   (webhookUrl)            │                          │
  │◀── authorizationUrl ──────│                          │
  │                           │                          │
  │── Comparte enlace ────────┼─────────────────────────▶│
  │   (email, WhatsApp, etc)  │                          │
  │                           │◀── Completa wizard ──────│
  │                           │                          │
  │                           │── Muestra éxito ────────▶│
  │                           │                          │
  │◀── POST webhook ──────────│                          │
  │   (emisorId, rut, etc)    │                          │

Cuándo usarlo:

• No necesitas redirect al usuario (puede cerrar la ventana)
• Procesamiento asíncrono en tu backend
• Flujos donde compartes el enlace manualmente (WhatsApp, SMS)

Configuración:

{
  "webhookUrl": "https://tu-app.com/webhooks/tokenizacion",
  "webhookHeaders": {
    "Authorization": "Bearer tu-secret"
  },
  "tipoAutenticacion": "CLAVE_TRIBUTARIA",
  "tipoEmisor": "tributario"
}

---

Flujo 3: Dual (Redirect + Webhook)

Ideal cuando necesitas ambos: feedback al usuario Y procesamiento backend.

Tu App                    Redcumbre                   Usuario
  │                           │                          │
  │── POST /init-session ────▶│                          │
  │   (returnUrl + webhookUrl)│                          │
  │◀── authorizationUrl ──────│                          │
  │                           │                          │
  │── Redirige usuario ───────┼─────────────────────────▶│
  │                           │◀── Completa wizard ──────│
  │                           │                          │
  │◀── Redirect returnUrl?code=xyz ─────────────────────│
  │◀── POST webhook ──────────│  (en paralelo)           │

Cuándo usarlo:

• Frontend necesita confirmar al usuario
• Backend necesita procesar sin depender del frontend
• Redundancia: si el redirect falla, el webhook llega igual

Configuración:

{
  "returnUrl": "https://tu-app.com/callback",
  "webhookUrl": "https://tu-app.com/webhooks/tokenizacion",
  "tipoAutenticacion": "CLAVE_TRIBUTARIA",
  "tipoEmisor": "tributario"
}

---

Flujo 4: Invitación por Email

Ideal para onboarding masivo o cuando prefieres que Redcumbre envíe el email.

Tu App                    Redcumbre                   Usuario
  │                           │                          │
  │── POST /invite ──────────▶│                          │
  │   (rut, email)            │                          │
  │◀── sessionId, url ────────│                          │
  │                           │── Email invitación ─────▶│
  │                           │                          │
  │                           │◀── Completa wizard ──────│
  │                           │                          │
  │◀── POST webhook ──────────│                          │
  │   (usa config del tenant) │                          │

Cuándo usarlo:

• Quieres que Redcumbre envíe el email (con tu branding)
• Onboarding de múltiples usuarios
• No quieres gestionar el envío de enlaces

Configuración:

{
  "rut": "77438768-4",
  "email": "usuario@empresa.cl",
  "tipoAutenticacion": "CLAVE_TRIBUTARIA",
  "tipoEmisor": "tributario"
}

Nota

El flujo de invitación no lleva webhookUrl: al completarse, el evento va a la URL por defecto de tu empresa (General → Webhooks) si existe, «Enviar a esta URL» está encendido y tokenizacion.completada está en la lista de eventos habilitados (vacía = todos). La invitación no copia la URL al crearse: lo que cuenta es tu configuración al momento de completar.

---

Resumen de Flujos

Flujo	returnUrl	webhookUrl	Usa /exchange?	Usuario ve
Redirect	✅	Config tenant	✅ Sí	Redirect a tu app
Webhook	❌	✅	❌ No	Pantalla de éxito
Dual	✅	✅	Opcional	Redirect a tu app
Invite	❌	Config tenant	❌ No	Pantalla de éxito

De dónde sale la URL del webhook

Si envías webhookUrl en init-session, el evento va a esa URL y no se filtra por los eventos que hayas habilitado en el panel: pedirla en el body ya es la suscripción.

Si no la envías, el evento va a la URL por defecto de General → Webhooks, siempre que «Enviar a esta URL» esté encendido y tokenizacion.completada esté habilitado (la lista vacía habilita todos). Es decir: con la URL por defecto encendida recibes el webhook aunque uses el flujo Redirect.

En los dos casos el evento va firmado con el secreto de tu empresa y lleva los headers del panel; los webhookHeaders de la sesión van encima y ganan si el nombre se repite.

---

Emisores Tributarios

¿Qué son?

Los Emisores Tributarios permiten que tus usuarios finales autoricen el uso de sus credenciales SII de forma segura, sin que tu plataforma las vea directamente. Funciona como un flujo OAuth2 donde el usuario mantiene control total.

Ideal para plataformas SaaS que necesitan realizar operaciones tributarias en nombre de sus usuarios (consultas al SII, emisión de BHE, etc.) sin comprometer la seguridad de sus credenciales.

Sistema de Invitación (Dual Mode)

Invita a tus clientes a autorizar sus credenciales de forma profesional.

Modo Email Directo

• Sistema envía email automático al usuario final
• Incluye información de tu empresa (nombre, logo)
• Enlace único y seguro al wizard de autorización
• Enlace de revocación para control total

Modo “Copiar Enlace”

• Sistema genera enlace único
• Tú decides cómo y cuándo compartirlo (WhatsApp, email manual, SMS, etc.)
• Ideal para flujos personalizados o comunicación directa
• Mismo nivel de seguridad que modo email

Ventajas:

• ✅ Flexibilidad: Elige el modo que mejor se adapte a tu flujo de trabajo
• ✅ Branding: Todos los emails incluyen tu información empresarial
• ✅ Notificaciones automáticas: Usuario recibe confirmación al autorizar

Sistema de Revocación

El usuario final tiene control TOTAL sobre sus credenciales en todo momento.

¿Cómo funciona?

1. Usuario accede al enlace de revocación (recibido por email)
2. Wizard muestra información de la autorización
3. Usuario confirma revocación validando su identidad con clave tributaria SII
4. Sistema elimina credenciales y notifica a ambas partes

Ventajas:

• ✅ Control total del usuario: Puede revocar en cualquier momento sin contactar a tu empresa
• ✅ Tokens de un solo uso: Cada enlace de revocación es único y expira en 24 horas
• ✅ Validación de identidad: Requiere clave tributaria SII para confirmar la revocación
• ✅ Notificaciones bidireccionales: Usuario y empresa reciben confirmación
• ✅ Webhooks: Tu sistema se entera instantáneamente vía webhook

Revocación por API (Administrador)

Además de la revocación por el usuario final, puedes revocar emisores directamente desde tu backend usando la API.

POST /tu-tenant/tokenizacion/revoke
Content-Type: application/json
Authorization: Bearer tu-api-key

{
  "emisorId": "uuid-del-emisor",
  "tipoEmisor": "tributario",
  "motivoRevocacion": "Cambio de proveedor de servicios"
}

Parámetros:

Campo	Tipo	Requerido	Descripción
emisorId	UUID	✅	ID del emisor a revocar
tipoEmisor	string	✅	tributario o dte
motivoRevocacion	string	❌	Motivo (max 500 chars). Se incluye en el email de notificación

Response:

{
  "success": true,
  "message": "Emisor revocado exitosamente. Se ha enviado una notificación al usuario.",
  "emisor": {
    "id": "uuid-del-emisor",
    "rut": "77438768-4",
    "razonSocial": "EMPRESA EJEMPLO SPA",
    "revokedAt": "2025-01-15T10:30:00Z"
  },
  "sandbox": false
}

Comportamiento:

• Marca el emisor como revocado (revokedBy: 'ADMIN')
• Envía email de notificación al usuario final del emisor
• Encola webhook emisor.revocado a tu sistema
• NO valida credenciales SII (autoridad del API Key/Admin)

Importante

La revocación por API es una acción administrativa. El usuario final recibirá un email informando que su autorización fue revocada por el administrador.

Métodos de Autenticación

Los emisores tributarios soportan dos métodos de autenticación con el SII:

Método	Campo	Descripción
Clave Tributaria	CLAVE_TRIBUTARIA	Clave web del SII. Más simple, la mayoría de usuarios la tiene
Certificado Digital	CERTIFICADO_DIGITAL	Archivo PFX/P12 + contraseña. Más seguro, usado por empresas con firma electrónica avanzada

El método se elige al abrir la sesión de tokenización, con el campo tipoAutenticacion de init-session o invite. Queda registrado en el emisor y determina qué se le pide al titular en el wizard: su clave del SII, o el archivo .pfx con su contraseña.

Integración Rápida

1️⃣ Iniciar Sesión de Tokenización

Con clave tributaria:

POST /tu-tenant/tokenizacion/init-session
Content-Type: application/json
Authorization: Bearer tu-api-key

{
  "rut": "77438768-4",
  "email": "usuario@empresa.cl",
  "tipoAutenticacion": "CLAVE_TRIBUTARIA",
  "webhookUrl": "https://tu-app.com/webhooks/tokenizacion"
}

Con certificado digital:

POST /tu-tenant/tokenizacion/init-session
Content-Type: application/json
Authorization: Bearer tu-api-key

{
  "rut": "77438768-4",
  "email": "usuario@empresa.cl",
  "tipoAutenticacion": "CERTIFICADO_DIGITAL",
  "tipoEmisor": "tributario",
  "webhookUrl": "https://tu-app.com/webhooks/tokenizacion"
}

Nota

Cuando tipoAutenticacion es CERTIFICADO_DIGITAL y tipoEmisor es tributario, el certificado se almacena en un vault independiente exclusivo para emisores tributarios (separado del vault de emisores DTE).

Response:

{
  "success": true,
  "data": {
    "sessionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "authorizationUrl": "https://app.redcumbre.cl/p/tokenizacion/a1b2c3d4-5678-90ab-cdef-1234567890ab/authorize",
    "emitterOperation": "CREATE",
    "lookupData": {
      "rut": "77438768-4",
      "razonSocial": "EMPRESA EJEMPLO SPA",
      "portalMipymeHabilitado": true,
      "tipoContribuyente": "EMPRESA"
    }
  },
  "sandbox": false
}

emitterOperation te dice de antemano si el RUT va a crear un emisor nuevo (CREATE) o actualizar uno que ya existe en tu tenant (UPDATE).

2️⃣ Compartir Enlace con Usuario

Recibes authorizationUrl para compartir con tu usuario (email, WhatsApp, SMS, etc.)

El wizard incluye:

• CAPTCHA proof-of-work (Altcha) para protección contra bots
• Consentimiento explícito (Ley 21.719) para tratamiento de credenciales

3️⃣ Recibir Confirmación

Tu webhook recibe notificación cuando el usuario completa el proceso:

{
  "event": "tokenizacion.completada",
  "sessionId": "c6c53392-bdb0-4053-8b9d-5b34296d63a3",
  "code": "83aK0esV0V21u8-krvuMiXx1OqheSVy56E6tBG3OjX8",
  "emisorId": "cmikf6ei00001sek0mxzcf668",
  "rut": "77438768-4",
  "tipoAutenticacion": "CLAVE_TRIBUTARIA",
  "tipoEmisor": "tributario",
  "timestamp": "2025-01-15T10:30:00Z"
}

4️⃣ Canjear el código (flujo Redirect)

Si usaste returnUrl, el usuario vuelve a tu aplicación con ?code=.... Ese código se canjea una sola vez:

POST /tu-tenant/tokenizacion/exchange
Content-Type: application/json
Authorization: Bearer tu-api-key

{
  "code": "83aK0esV0V21u8-krvuMiXx1OqheSVy56E6tBG3OjX8"
}

Response:

{
  "success": true,
  "data": {
    "emisorId": "cmikf6ei00001sek0mxzcf668",
    "rut": "77438768-4",
    "tipoAutenticacion": "CLAVE_TRIBUTARIA",
    "tipoEmisor": "tributario"
  },
  "sandbox": false
}

De dónde sale el emisorTributarioId

Es la pregunta que traba la primera integración, así que va explícita:

emisorId (tokenización) === emisorTributarioId (emisión)

El emisorTributarioId que piden POST /{tenantSlug}/bhe y POST /{tenantSlug}/bhet es el emisorId que devuelve el flujo de tokenización. Lo obtienes de dos formas, y ambas entregan el mismo valor:

• En la respuesta de POST /{tenantSlug}/tokenizacion/exchange → data.emisorId
• En el webhook tokenizacion.completada → emisorId (“ID del emisor tributario creado/actualizado”)

También está visible en el panel web, en Configuración → Emisores.

POST /tu-tenant/tokenizacion/init-session   (o /invite)
        │
        ▼  el titular autoriza en el wizard
        │
        ├── webhook tokenizacion.completada → emisorId
        └── POST /tu-tenant/tokenizacion/exchange → data.emisorId
                       │
                       ▼
        POST /tu-tenant/bhe   { "emisorTributarioId": "<ese mismo id>", ... }

Es un identificador opaco: trátalo como texto, no lo construyas ni lo interpretes. Es estable para ese RUT dentro de tu tenant, así que si el contribuyente vuelve a autorizar, el flujo devuelve el mismo emisorId con emitterOperation: "UPDATE".

Sólo sirve el id de un emisor tributario

El campo se llama emisorTributarioId literalmente: acepta el emisorId de una tokenización con tipoEmisor: "tributario". El id de un emisor DTE identifica otra entidad y no se puede usar para emitir BHE ni BHET. El webhook te dice cuál es cuál en el campo tipoEmisor.

Certificado Digital del Emisor Tributario

Para emisores con tipoAutenticacion: "CERTIFICADO_DIGITAL", el archivo PFX entra siempre por el wizard de tokenización: lo sube el propio titular del certificado, en el enlace que tú le compartes. Tu integración nunca manipula el .pfx ni su contraseña.

No hay carga de certificados por API

Redcumbre no expone endpoints para subir, consultar ni eliminar el certificado con API key. Es una decisión de diseño: un PFX es la firma electrónica avanzada del contribuyente, y el modelo de la plataforma es que sólo él lo entregue, en el wizard, con consentimiento explícito.

Alta con certificado digital

Una sola llamada — el certificado lo aporta el titular en el wizard:

POST /tu-tenant/tokenizacion/invite
Content-Type: application/json
Authorization: Bearer tu-api-key

{
  "rut": "77438768-4",
  "email": "titular@empresa.cl",
  "tipoAutenticacion": "CERTIFICADO_DIGITAL",
  "tipoEmisor": "tributario"
}

Al completar el wizard, el sistema valida el PFX (RUT, emisor, vigencia), lo cifra con AES-256-GCM en el vault de emisores tributarios y te avisa por webhook con el emisorId.

Renovar el certificado

No hay operación de “renovación” aparte: abres una sesión de tokenización nueva sobre el mismo RUT y el titular sube el PFX vigente. El emisor no se duplica, el certificado anterior se reemplaza (UPSERT, sin histórico) y la respuesta trae emitterOperation: "UPDATE" con el mismo emisorId de siempre.

Consultar o eliminar el certificado

Son operaciones del panel web (Configuración → Emisores → Certificado): ahí ves la metadata —emisor de la firma, vigencia, serie— y puedes eliminarlo. No están disponibles por API.

Vencimiento

Un cron diario (06:00 AM Chile) detecta certificados por vencer (30 días) y desactiva automáticamente los vencidos. Cuando un certificado vence, el emisor queda con tieneCredenciales: false hasta que se suba uno nuevo mediante una nueva sesión de tokenización.

Reautorización

¿Qué pasa si un usuario ya autorizó previamente y quiere actualizar sus credenciales?

El sistema lo maneja automáticamente:

• Detecta si el emisor ya existe
• Actualiza las credenciales (no crea duplicado)
• Limpia estado de revocación previo
• Genera nuevo token de revocación
• Envía notificación de reautorización

Ventaja: Usuario puede actualizar credenciales sin intervención de tu soporte.

Estados del Emisor Tributario

Estado	Descripción
PENDIENTE	Invitación enviada, esperando autorización del usuario
ACTIVO	Credenciales válidas, puede realizar operaciones tributarias
REVOCADO	Usuario revocó sus credenciales
EXPIRADO	Credenciales expiraron o fueron invalidadas

---

Emisores DTE

¿Qué son?

Los Emisores DTE son entidades habilitadas para emitir Documentos Tributarios Electrónicos (facturas, boletas, notas de crédito) ante el SII de Chile. La plataforma permite gestionar múltiples emisores de forma centralizada, segura y eficiente.

Ideal para empresas con múltiples sucursales, holdings empresariales, o cualquier organización que necesite administrar varios RUTs emisores desde un solo lugar.

Características Principales

Gestión Centralizada

Administre todos los RUTs emisores de su organización desde un solo lugar:

• Múltiples sucursales: Registre cada sucursal como un emisor independiente
• Datos completos: Razón social, giro, direcciones, actividades económicas
• Certificados digitales: Asocie certificados digitales a cada emisor
• Emisor por defecto: Marque el emisor principal para operaciones automáticas

Consulta Automática al SII

Simplifique la creación de emisores con integración directa al SII:

• Búsqueda por RUT: Consulte cualquier contribuyente registrado en el SII
• Prellenado automático: Los datos se cargan automáticamente desde el SII
• Información actualizada: Razón social, direcciones, actividades económicas verificadas
• Zona tributaria: Identificación automática de la unidad SII correspondiente

Gestión de Direcciones y Sucursales

Administre todas las ubicaciones de su empresa:

• Múltiples direcciones: Registre todas las sucursales y puntos de venta
• Casa matriz: Identifique claramente su domicilio legal
• Dirección por defecto: Configure la dirección principal para facturación
• Zona SII automática: Sistema inteligente de asignación de zona tributaria

Actividades Económicas

Gestione las actividades económicas de cada emisor:

• Códigos ACTECO: Base de datos completa con 674 actividades económicas
• Búsqueda inteligente: Encuentre rápidamente la actividad correcta
• Múltiples actividades: Registre todas las actividades de su empresa
• Actividad por defecto: Marque la actividad principal

Creación de Emisor DTE

Un emisor DTE siempre se da de alta por tokenización con certificado digital: es el único modo de que el certificado del representante legal llegue a la plataforma sin pasar por tu integración. Redcumbre resuelve por ti el lookup al SII, las direcciones, las actividades económicas y el representante legal a partir del certificado.

Paso 1 (opcional): Verificar el RUT en el SII

Antes de invitar puedes consultar los datos del contribuyente —incluido si tiene Portal MiPyme habilitado— con el endpoint de lookup:

POST /tu-tenant/herramientas/lookup-rut
Content-Type: application/json
Authorization: Bearer tu-api-key

{
  "rut": "77438768-4"
}

Detalle de la respuesta, caché y modo sandbox en la guía de Lookup RUT.

Paso 2: Declarar qué emisores quieres

La configuración de emisión tiene dos dimensiones independientes, y tienes que pedir al menos una:

Dimensión	Campo	Valores
Facturación	tipoIntegracion	PORTAL_MIPYME (emisión vía Portal MiPyme del SII) o FULL_DTE (API oficial del SII)
Boletas	boletas	true para pedir además el emisor de boletas del mismo RUT

Combinan libremente:

Lo que pides	Emisores que quedan
"tipoIntegracion": "FULL_DTE"	uno de facturación
"boletas": true	uno de boletas
"tipoIntegracion": "FULL_DTE" + "boletas": true	dos emisores para el mismo RUT

El sistema no elige el carril por ti

Una configuración a medias —emailEmpresa sin tipoIntegracion ni boletas: true, por ejemplo— se rechaza con 400, y por /invite también se rechaza un cuerpo DTE que no declare ninguno de los dos. Es deliberado: el emisor que quedaría creado no sería el que pediste, y lo descubrirías después de que el titular ya subió su certificado.

Paso 3: Invitar al emisor DTE

POST /tu-tenant/tokenizacion/invite
Content-Type: application/json
Authorization: Bearer tu-api-key

{
  "rut": "77438768-4",
  "email": "autorizador@empresa.cl",
  "emailEmpresa": "facturacion@empresa.cl",
  "tipoAutenticacion": "CERTIFICADO_DIGITAL",
  "tipoEmisor": "dte",
  "tipoIntegracion": "FULL_DTE",
  "boletas": true,
  "contactoCertificacionEmail": "certificacion@empresa.cl"
}

Campo	Requerido para DTE	Descripción
tipoAutenticacion	✅	Siempre CERTIFICADO_DIGITAL: los emisores DTE no aceptan clave tributaria
tipoIntegracion	⚠️	El carril de facturación. Obligatorio salvo que la sesión pida únicamente boletas
boletas	⚠️	true para pedir el emisor de boletas. Obligatorio si no pides facturación
email	✅	Email del autorizador: recibe la invitación y el enlace de revocación
emailEmpresa	✅	Email de la empresa, el que aparece en la factura. Es distinto del anterior
contactoCertificacionEmail	—	Contacto para la correspondencia de la certificación ante el SII. Si lo omites, se usa el email de la empresa
contactoCertificacionTelefono	—	Teléfono de contacto para la certificación

init-session acepta exactamente la misma configuración

Si prefieres el flujo Redirect en vez del email de invitación, init-session recibe los mismos campos, con las mismas validaciones y los mismos rechazos. Lo único que cambia es cómo llega el titular al formulario y cómo vuelve el resultado: en init-session el RUT es opcional y decides entre returnUrl, webhookUrl o los dos.

Si pides PORTAL_MIPYME y el RUT no lo tiene habilitado en el SII, la respuesta es 400 antes de enviar nada. Lo mismo si tu tenant no tiene contratado el servicio del carril que pides, o si el RUT ya tiene un emisor incompatible con la configuración.

Paso 4: Recibir los emisores creados

El webhook tokenizacion.completada (o el /exchange si usaste returnUrl) trae el emisorId del emisor DTE, con tipoEmisor: "dte", y el arreglo emisores con todos los que creó la sesión:

{
  "emisorId": "cmikf6ei00001sek0mxzcf668",
  "emisores": [
    {
      "emisorId": "cmikf6ei00001sek0mxzcf668",
      "carril": "FULL_DTE",
      "estado": "ESPERA_CERTIFICACION",
      "motivoInactivo": "PENDIENTE_CERTIFICACION",
      "tiposHabilitados": []
    },
    {
      "emisorId": "cmr8b52zn000fseodrcbqvr62",
      "carril": "SOLO_BOLETA",
      "estado": "ESPERA_CERTIFICACION",
      "motivoInactivo": "PENDIENTE_CERTIFICACION",
      "tiposHabilitados": []
    }
  ]
}

emisorId sigue apuntando a un emisor: el de facturación si pediste uno; si la sesión fue sólo boletas, el de boletas. emisores es la única forma de conocer el id del segundo.

La certificación tarda días, y cada carril termina por su cuenta

FULL_DTE y SOLO_BOLETA exigen certificación ante el SII. El emisor nace inactivo (estado: "ESPERA_CERTIFICACION", tiposHabilitados: []) y queda operativo cuando el SII resuelve, lo que se mide en días. PORTAL_MIPYME no certifica: nace operativo, y su tiposHabilitados trae los tipos que el SII tiene autorizados y vigentes para ese RUT, entre los que se emiten por el Portal MiPyme. Varía de una empresa a otra: no supongas que un emisor PORTAL_MIPYME emite todos los tipos del carril. El detalle por carril está en la guía de webhooks.

Dos carriles son dos certificaciones, y no terminan juntas

Si pediste facturación y boletas, son dos procesos independientes. Recibes un webhook emisor.certificado por cada uno, en momentos distintos, y el payload trae el tipoIntegracion para que sepas cuál llegó. No esperes un único aviso de cierre, y no bloquees la emisión de un carril esperando al otro.

El campo pronostico de la respuesta del alta te dice, carril por carril y antes de que el titular haga nada, cuál va a nacer operativo y cuál va a quedar esperando.

Las direcciones, sucursales y actividades económicas se cargan automáticamente desde el SII y se administran después desde el panel web — no hay endpoints de edición con API key.

De dónde sale el emisorDteId

Es el campo obligatorio de POST /{tenantSlug}/dte, así que va explícito — igual que su equivalente tributario.

emisorId (tokenización) === emisorDteId (emisión)

El emisorDteId que pide POST /{tenantSlug}/dte es el emisorId del emisor DTE. Lo obtienes de dos formas, según cómo se dio de alta el emisor:

• Panel web — Configuración → Emisores: abre el emisor y copia el campo ID. Es el camino cuando el emisor ya estaba provisionado en tu tenant.
• Tokenización — en la respuesta de POST /{tenantSlug}/tokenizacion/exchange (data.emisorId) o en el webhook tokenizacion.completada, en ambos casos con tipoEmisor: "dte".

Es un CUID (por ejemplo clxyz123abc456def), estable para ese RUT y ese tipoIntegracion dentro de tu tenant: si el titular vuelve a autorizar, el flujo devuelve el mismo emisorId con emitterOperation: "UPDATE".

Es configuración: guárdalo una vez

No hay endpoint de listado de emisores con API key. El emisorDteId se fija al dar de alta el emisor y no cambia, así que guárdalo en tu sistema junto al RUT. Si lo pierdes, tienes que consultarlo en el panel web o volver a tokenizar el mismo RUT.

Un mismo RUT puede tener más de un emisor DTE en el tenant: 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 exactamente por cuál de ellos sale el documento.

El emisor de boletas no anula boletas

La nota de crédito que anula una boleta es un documento de facturación: la emite el emisor de facturación del mismo RUT, no el de boletas. Si tu cliente sólo tiene el emisor de boletas, la anulación la hace directamente en el Portal MiPyme del SII — no hay forma de hacerla por API.

Es la razón práctica para pedir los dos carriles cuando el cliente anula boletas con alguna frecuencia.

No confundir con el emisorTributarioId

El id de un emisor DTE identifica otra entidad que el de un emisor tributario: no sirve para emitir BHE ni BHET, y al revés tampoco. Ver De dónde sale el emisorTributarioId.

Estados del Emisor DTE

Estado	Descripción
PENDIENTE	Creado, pendiente de configuración completa
ACTIVO	Certificado válido, puede emitir documentos
REVOCADO	Administrador revocó el emisor
EXPIRADO	Certificado expirado o inválido

---

Sincronizar un emisor con el SII

Vuelve a leer del SII los datos del contribuyente y los deja en el emisor: razón social, giro, actividades económicas y sucursales. En un emisor PORTAL_MIPYME también vuelve a leer los tipos de documento que el SII le tiene autorizados, que son los que ese emisor puede emitir.

curl -X POST "https://api.redcumbre.cl/mi-tenant/emisores/cmikf6ei00001sek0mxzcf668/sincronizar" \
  -H "X-API-Key: $RCAPI_API_KEY"

Llámalo cuando el SII le autorice o le quite un tipo a tu cliente. Si el SII no responde, la operación falla entera y el emisor queda como estaba. Con una API key de prueba se rechaza, porque consulta el SII real.

Responde 200 con lo que quedó guardado:

{
  "emisorId": "cmikf6ei00001sek0mxzcf668",
  "rut": "76123456-7",
  "razonSocial": "COMERCIAL DEMO SPA",
  "giroGlosa": "VENTA AL POR MENOR",
  "tipoIntegracion": "PORTAL_MIPYME",
  "tiposAutorizadosSii": [33, 34, 52, 56, 61],
  "conflictos": []
}

Campo	Qué es
tipoIntegracion	El carril por el que emite el emisor. Explica el campo siguiente.
tiposAutorizadosSii	Sólo en PORTAL_MIPYME: los tipos DTE que el SII le tiene autorizados y que el Portal MiPyme emite, recién consultados. Son los mismos que acepta la emisión y que informa tiposHabilitados. Viene null en los demás carriles, o si el SII no informó documentos autorizados.
conflictos	Lo que la sincronización dejó por resolver: ACTIVIDAD_DEFAULT_REMOVIDA, SUCURSAL_DEFAULT_DESACTIVADA, CASA_MATRIZ_DESACTIVADA o SUCURSAL_ACTECO_HUERFANA. Se resuelven desde la plataforma web. Una lista vacía significa que no hay nada pendiente.

Cómo saber si un emisor puede emitir un tipo

• Al autorizarlo: emisores[].tiposHabilitados del webhook tokenizacion.completada, carril por carril.
• Al emitir: si el emisor es PORTAL_MIPYME y el SII no le tiene autorizado el tipo, rCAPI vuelve a consultar al SII una vez antes de responder. Si sigue sin estar autorizado, la emisión responde 400 con la razón social, el RUT, el tipo pedido y los tipos que sí puede emitir. No se envía nada al SII.

---

Reintentar la credencial del SII

Cuando el SII deja de aceptar la credencial de un contribuyente, rCAPI abre un episodio: detiene lo que depende de esa credencial, avisa a la empresa por correo y te manda el evento de webhook correspondiente (dte.credencial_portal_rechazada, bhe.credencial_rechazada o bhet.credencial_rechazada — ver la guía de webhooks).

Cuando tu cliente te avise que ya la corrigió en el portal del SII, estas dos operaciones disparan un intento de login y te dicen en qué quedó. Son la salida del episodio.

Carril	Operación
Emisor DTE	POST /:tenantSlug/emisores/:id/credencial-portal/reintentar
Emisor tributario (BHE/BHET)	POST /:tenantSlug/emisores-tributarios/:id/credencial/reintentar

Ninguna de las dos acepta cuerpo: el emisor va en la ruta.

curl -X POST "https://api.redcumbre.cl/mi-tenant/emisores/cmikf6ei00001sek0mxzcf668/credencial-portal/reintentar" \
  -H "X-API-Key: $RCAPI_API_KEY"

Respuesta

El mismo cuerpo en los dos carriles, para que no tengas que ramificar:

{
  "restablecida": false,
  "motivo": "El certificado digital no se encuentra habilitado para este RUT",
  "intentado": true
}

Campo	Descripción
restablecida	true si después del intento la credencial quedó sana. Cuando pasa a true sale el evento de restablecimiento
motivo	Lo que dijo el SII. null cuando no dio motivo, o cuando restablecida es true
intentado	false cuando no había credencial que probar: ningún emisor activo la usa. No es un error

Responde 200 aunque la credencial siga rechazada

El intento se hizo; su desenlace es el cuerpo. Un 4xx se reserva para el emisor que no existe o que no pertenece a tu tenant — y las dos respuestas son idénticas a propósito, para que la diferencia no permita descubrir emisores ajenos.

La operación tampoco se corta mientras el episodio esté abierto: es la puerta de salida, y cerrarla te dejaría adentro.

Un intento, no más

Cada llamada hace un solo login al portal del SII. No reintentes en un bucle: el SII bloquea la cuenta del contribuyente tras varios fallos seguidos, y eso convierte una clave caducada en una cuenta bloqueada. Espera a que tu cliente confirme que la corrigió.

rCAPI ya hace un intento automático diario por su cuenta mientras el episodio siga abierto.

---

Características Compartidas

🔒 Seguridad

Almacenamiento Cifrado

• Claves tributarias se almacenan cifradas con AES-256-GCM + PBKDF2
• Certificados digitales (PFX) se almacenan cifrados con AES-256-GCM en vault independiente
• Salt único por credencial, key derivation basada en RUT
• Certificados de emisores tributarios y emisores DTE usan vaults separados (cero acoplamiento)
• Nunca se almacenan en texto plano

Validación en Tiempo Real

• Todas las credenciales se validan contra el SII ANTES de aceptarlas
• No se almacenan credenciales inválidas
• Validación de vigencia de certificados digitales
• Verificación de coincidencia de RUT entre certificado y emisor

Protección del Wizard Público

• CAPTCHA Altcha (proof-of-work): protección contra bots en el endpoint de completar sesión
• Consentimiento explícito (Ley 21.719): checkbox obligatorio con texto específico al tratamiento de credenciales. Se registra timestamp, IP y texto completo del consentimiento para cumplimiento legal

Tokens de Seguridad

Token	Uso	Expiración
Tokens de revocación	Un solo uso	24 horas
Authorization codes	Un solo uso para intercambio	10 minutos
Sesiones de tokenización	Múltiple hasta completar	7 días

📧 Transparencia Total

• Usuario recibe email al autorizar (con enlace de revocación)
• Usuario recibe email al revocar
• Empresa recibe webhook en ambos eventos
• Trazabilidad completa de todas las acciones

🛡️ Control de Acceso y Auditoría

• Roles y permisos: Control granular de acceso (Administradores, Operadores)
• Registro de actividades: Auditoría completa de todas las operaciones
• Trazabilidad: Histórico de cambios con usuario y fecha
• Multi-tenant: Aislamiento total entre organizaciones

---

Webhooks

Eventos Disponibles

Evento	Descripción	Aplica a
tokenizacion.completada	Usuario completó la autorización (sólo al cerrar una sesión)	Ambos
emisor.actualizado	El emisor cambió fuera de una sesión (edición, reactivación, etc.). Opt-in estricto	Ambos
emisor.creado	Alta directa del emisor, fuera de una sesión. Opt-in estricto	Ambos
emisor.revocado	Usuario/admin revocó credenciales	Ambos
emisor.certificado	El emisor quedó productivo ante el SII	DTE
dte.credencial_portal_rechazada / _restablecida	El SII dejó de aceptar —o volvió a aceptar— la credencial del portal	DTE
bhe.credencial_rechazada / _restablecida	Lo mismo en el carril de boletas de honorarios	Tributario
bhet.credencial_rechazada / _restablecida	Lo mismo en el carril de boletas de terceros	Tributario

Payload: tokenizacion.completada

{
  "event": "tokenizacion.completada",
  "tenantId": "8",
  "sessionId": "c6c53392-bdb0-4053-8b9d-5b34296d63a3",
  "code": "83aK0esV0V21u8-krvuMiXx1OqheSVy56E6tBG3OjX8",
  "emisorId": "cmikf6ei00001sek0mxzcf668",
  "rut": "77438768-4",
  "tipoAutenticacion": "CLAVE_TRIBUTARIA",
  "tipoEmisor": "tributario",
  "correlationId": "proceso-interno-123",
  "lookupData": {
    "razonSocial": "EMPRESA EJEMPLO SPA",
    "giro": "SERVICIOS INFORMATICOS",
    "direcciones": [
      {
        "ciudad": "SANTIAGO",
        "comuna": "PROVIDENCIA",
        "direccion": "AV. PROVIDENCIA 1234",
        "comunaId": 180
      }
    ],
    "actividadesEconomicas": [
      {
        "codigo": "620900",
        "descripcion": "ACTIVIDADES DE TECNOLOGÍA DE LA INFORMACIÓN"
      }
    ],
    "tipoContribuyente": "EMPRESA",
    "portalMipymeHabilitado": true
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

Campo	Descripción
tipoAutenticacion	CLAVE_TRIBUTARIA o CERTIFICADO_DIGITAL
tipoEmisor	tributario o dte
code	Authorization code (usar con /exchange si aplica)
correlationId	ID de correlación enviado en init-session (opcional)
lookupData	Datos del contribuyente obtenidos del SII (puede ser null)

Payload: emisor.revocado

{
  "event": "emisor.revocado",
  "data": {
    "emisorId": "cmikf6ei00001sek0mxzcf668",
    "emisorType": "tributario",
    "rut": "77438768-4",
    "razonSocial": "EMPRESA EJEMPLO SPA",
    "tenantId": "8",
    "revokedBy": "USER",
    "motivoRevocacion": null
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

Campo	Descripción
emisorType	tributario o dte
revokedBy	USER (usuario final) o ADMIN (administrador del tenant)
motivoRevocacion	Motivo de revocación (solo cuando revokedBy: ADMIN)

Payload: emisor.actualizado / emisor.creado

tokenizacion.completada sale sólo del cierre de una sesión. Si editas o creas un emisor por el panel o por la API fuera de una sesión, lo que recibes es esto — opt-in, la lista de eventos vacía no los habilita:

{
  "event": "emisor.actualizado",
  "tenantId": "8",
  "emisorId": "cmikf6ei00001sek0mxzcf668",
  "tipoEmisor": "dte",
  "rut": "77438768-4",
  "razonSocial": "EMPRESA EJEMPLO SPA",
  "operation": "UPDATE",
  "camposModificados": ["giroGlosa"],
  "origen": "TENANT",
  "timestamp": "2026-01-15T11:02:44.318Z"
}

Campo	Descripción
operation	UPDATE, REACTIVATE (el emisor estaba inactivo o revocado y queda activo) o CREATE (sólo en emisor.creado)
camposModificados	Nombres de los campos que cambiaron; nunca sus valores. Vacío en emisor.creado
origen	PLATAFORMA (MASTER o reseller) o TENANT (usuario del tenant o llave de API)

Detalle completo, con ambos ejemplos separados, en la guía de Webhooks.

Configuración de Webhooks

Tu sistema puede recibir notificaciones en tiempo real configurando:

• URL por defecto: Endpoint HTTPS donde recibirás los eventos que no traen su propia webhookUrl
• Headers personalizados: Para autenticación (ej: Authorization: Bearer token); van a todo destino
• Eventos habilitados: Qué eventos van a la URL por defecto

El detalle está en la guía de Webhooks.

Reintentos

Los webhooks se reintentan hasta 6 veces con backoff exponencial si tu endpoint no responde con 2xx.

---

Casos de Uso

📄 Boletas de Honorarios Electrónicas

Tipo: Emisores Tributarios

Permite a profesionales independientes autorizar credenciales para que puedas emitir BHE en su nombre.

• Usuario autoriza vía wizard seguro
• Validación automática contra SII
• Usuario mantiene control total

📊 Plataformas de Facturación Electrónica

Tipo: Ambos

Gestiona emisores para emitir DTEs (facturas, boletas, notas de crédito) en nombre de tus clientes.

• Emisores Tributarios: para delegación de credenciales
• Emisores DTE: para gestión centralizada

🏦 Sistemas Financieros

Tipo: Emisores Tributarios

Consulta información tributaria del SII para validación de clientes o scoring crediticio.

• Lookup automático de datos SII
• Validación de credenciales en tiempo real
• Sin almacenamiento de credenciales sensibles

🏢 Empresas Multi-Sucursal

Tipo: Emisores DTE

Ejemplo: Cadena de retail con 50 tiendas

• Registre cada tienda como emisor independiente
• Mantenga certificados digitales centralizados
• Administre permisos por sucursal
• Consulte actividad histórica por ubicación

🏛️ Holdings Empresariales

Tipo: Emisores DTE

Ejemplo: Grupo empresarial con 10 sociedades

• Administre todas las sociedades desde una plataforma
• Certificados digitales centralizados
• Visión consolidada de operaciones
• Control de acceso por empresa

📈 Software de Contabilidad

Tipo: Emisores Tributarios

Automatiza la obtención de información tributaria de tus usuarios.

• Integración simple vía API
• Datos verificados del SII
• Webhooks para sincronización

---

Resumen de Ventajas

Característica	Beneficio
Validación contra SII	Solo se aceptan credenciales válidas
Control del usuario	Usuario puede revocar en cualquier momento
Dual mode	Email automático o compartir enlace manual
Tokens de seguridad	Un solo uso, con expiración
Cifrado AES-256-GCM	Credenciales y certificados protegidos en reposo
Certificado digital	Emisores tributarios pueden autenticarse con PFX además de clave tributaria
CAPTCHA + Consentimiento	Wizard protegido contra bots y conforme a Ley 21.719
Webhooks en tiempo real	Tu sistema se entera al instante de cambios
Pre-carga de datos	Agiliza proceso para el usuario final
Lookup automático SII	Obtiene datos del contribuyente automáticamente
Marca blanca	Tu logo y nombre en todos los puntos de contacto
Múltiples sucursales	Sin límite de direcciones por emisor DTE
Zona SII automática	Cálculo automático según ubicación
Auditoría completa	Registro de todas las operaciones

---

Tokenización en el modo de prueba

Con una API Key de prueba (isSandbox: true) recorres el flujo completo de tokenización —abrir la sesión, invitar, completar el asistente, canjear el código y revocar— sin ninguna llamada al SII. No hace falta tener contratado el servicio.

El contribuyente de prueba

En prueba el asistente no le pregunta al SII si la clave es correcta, así que sólo completa una sesión el contribuyente de prueba de la plataforma, con su clave publicada:

RUT	Clave tributaria
12345678-5	clave-de-prueba

Son valores fijos y los puedes escribir en tus tests. Cualquier otro RUT, o una clave distinta, sale por el mismo camino que un rechazo real: la sesión queda fallida con el mismo código de credencial inválida y la respuesta es el mismo 400, con el mismo texto. Así ensayas también el camino de error.

Completar el asistente deja un emisor tributario de prueba para 12345678-5, con el servicio de boletas de honorarios habilitado y sin credenciales. Su emisorId te llega como siempre —en POST /{tenantSlug}/tokenizacion/exchange y en el webhook tokenizacion.completada— y es el emisorTributarioId con el que emites BHE de prueba. Si el emisor ya existía, el resultado es el mismo que en real (emitterOperation: "UPDATE").

Lo que se rechaza al abrir la sesión

En prueba el asistente acepta sólo clave tributaria. Estos dos pedidos se rechazan con 400 al crear la sesión, sin dejar sesión creada y sin enviar ningún correo:

• tipoAutenticacion: "CERTIFICADO_DIGITAL": no existe un certificado digital de prueba que se pueda publicar. El mensaje te dice que uses CLAVE_TRIBUTARIA con el contribuyente de prueba.
• tipoEmisor: "dte": ese carril exige certificado digital, y el emisor de documentos tributarios de prueba ya viene precargado en tu empresa, así que no hay nada que tokenizar.

Tampoco se abre una sesión de prueba para un RUT que no está en el catálogo de RUT de prueba: el mensaje te indica usar 12345678-5.

Lo demás, igual que en real

• Verificación anti-automatización y consentimiento explícito del titular: se exigen igual, con el mismo rechazo. Son parte del flujo que tu titular real va a recorrer.
• Correo de invitación: no sale a ninguna persona. Queda en la bandeja de mensajes simulados de tu empresa (GET /{tenantSlug}/modo-prueba/bandeja), y la URL de autorización que te devuelve invite sigue abriendo el asistente.
• Webhooks: tokenizacion.completada y los de revocación llegan al endpoint de prueba de tu empresa, con sandbox: true.
• Revocar un emisor de prueba se simula: sin correo a nadie —queda en la bandeja— y con su webhook.
• Tope diario: completar el asistente cuenta una en el tope de 200 tokenizaciones de prueba al día. Crear la sesión, invitar, canjear y revocar no cuentan. Cuánto te queda: GET /{tenantSlug}/modo-prueba/tope-diario/{servicio} con servicio = tokenizacion.

---

API Reference

Para detalles técnicos de implementación y especificaciones de endpoints:

👉 Ver endpoints de Tokenización SII en Swagger — alta, canje, invitación y revocación de emisores

👉 Ver el endpoint de Lookup RUT en Swagger — consulta de datos del contribuyente en el SII

Los emisores tributarios y los emisores DTE no tienen endpoints propios en la API pública: se crean y actualizan por tokenización, y el resto de su administración vive en el panel web.