Boletas de Honorarios de Terceros (BHET)

Flujo disponible solo en la aplicación web

Los borradores, la solicitud de autorización, la clonación y el envío manual por email se operan desde la aplicación web de Redcumbre, no por API. La API cubre el flujo de emisión directa, la consulta y la descarga de documentos.

TL;DR - Acceso Rápido

Endpoint: POST /{tenantSlug}/bhet

👉 Ver endpoints de BHET en Swagger

Las Boletas de Honorarios de Terceros son documentos tributarios que emiten las empresas cuando contratan servicios de terceros (personas naturales o jurídicas). A diferencia de las BHE donde el emisor presta el servicio, en las BHET el emisor es quien contrata y paga, mientras que el tercero es quien presta el servicio.

---

Diferencias con BHE

Aspecto	BHE	BHET
Emisor	Persona natural (presta servicio)	Empresa (contrata servicio)
Receptor	Destinatario (recibe servicio)	Tercero (presta servicio)
Retención	PPM — tasa vigente en GET /global/ppm	Retención — tasa vigente en GET /global/bhet-retencion
Sin receptor	sinDestinatario soportado	Siempre requiere tercero
Campo monto	montoLiquido	montoNeto
Campo impuesto	ppm	impuesto

---

Requisitos Previos

Antes de emitir una BHET necesitas:

1. Un Emisor Tributario activo con clave tributaria delegada y servicio BOLETAS_TERCEROS habilitado
2. El emisorTributarioId de ese emisor — va en el cuerpo de toda emisión
3. Una API Key con uno de estos roles: ADMIN, SUPER-ADMIN, SII-EMISOR-BHET, o FULL-API
4. Los datos del tercero (siempre requerido, no existe opción sin tercero)

¿De dónde sale el emisorTributarioId?

Lo devuelve el flujo de tokenización: viene como emisorId en la respuesta de POST /{tenantSlug}/tokenizacion/exchange y en el webhook tokenizacion.completada. También está visible en el panel web. Guárdalo al recibirlo — no hay endpoint de listado de emisores con API key. Ver la guía de Emisores.

Importante

Las BHET requieren clave tributaria, no certificado digital. El emisor debe ser una empresa (persona jurídica) con el servicio BHET habilitado.

---

Modos de Emisión

El sistema soporta 3 modos de emisión que permiten balancear entre respuesta inmediata y tolerancia a fallas del SII.

Modo	Descripción	Respuesta	Recomendado
SINC_COMPLETO	Todo síncrono: emitir + PDF interno + PDF SII	BHET completa con ambos PDFs	Cuando necesitas todo inmediato
SINC_PARCIAL	Emitir + PDF interno síncronos, PDF SII en background	BHET con folio + PDF interno	Default recomendado
ASINCRONO	Solo valida y encola. Todo en background	ID de intento para consulta	Alta tolerancia a fallas

---

Flujo SINC_PARCIAL (Default)

Tu App                    Redcumbre                   SII
  │                           │                        │
  │── POST /bhet ────────────▶│                        │
  │   (modo: SINC_PARCIAL)    │                        │
  │                           │── Emitir BHET ────────▶│
  │                           │◀── folioSii ──────────│
  │                           │                        │
  │                           │── Genera PDF interno   │
  │                           │                        │
  │◀── Response ──────────────│                        │
  │   (folioSii + pdfInternoUrl)                       │
  │   (estadoPdfSii: PENDIENTE)                        │
  │                           │                        │
  │                      [Background]                  │
  │                           │── Descarga PDF SII ───▶│
  │                           │◀── PDF ───────────────│
  │                           │                        │
  │◀── Webhook ───────────────│                        │
  │   (bhet.emision_terminada)│                        │

Ventajas:

• Respuesta rápida con folio y PDF personalizado
• PDF SII se descarga en background con reintentos automáticos (hasta 7 días)
• Si el SII tiene problemas, ya tienes el folio y un PDF válido

---

Flujo ASINCRONO

Tu App                    Redcumbre                   SII
  │                           │                        │
  │── POST /bhet ────────────▶│                        │
  │   (modo: ASINCRONO)       │                        │
  │                           │── Valida datos         │
  │                           │── Encola emisión       │
  │                           │                        │
  │◀── Response ──────────────│                        │
  │   (intentoId, estado: PENDIENTE)                   │
  │                           │                        │
  │                      [Background]                  │
  │                           │── Emitir BHET ────────▶│
  │                           │◀── folioSii ──────────│
  │                           │── Genera PDF interno   │
  │                           │                        │
  │◀── Webhook ───────────────│                        │
  │   (bhet.emitida)          │                        │

Ventajas:

• Respuesta instantánea (solo valida y encola)
• Reintentos automáticos si el SII falla, durante 18–22,6 horas (10 intentos con espaciado creciente desde 5 min, máximo 6 h entre uno y otro). Ver la curva completa
• Ideal para procesos batch o cuando no necesitas el resultado inmediato

Consultar estado:

GET /{tenantSlug}/bhet/intento/{intentoId}

---

Modos de Tercero

Existen 4 formas mutuamente excluyentes de especificar el tercero:

Modo	Campo	Descripción	Cobra SII Lookup
1	terceroId	ID o RUT de contribuyente guardado en sistema	No
2	tercero	Datos completos on-the-fly	No
3	siiLookup	Objeto lookup SII ya obtenido	No
4	lookupRut	Solo RUT, sistema ejecuta lookup al SII	Sí

Sobre el cobro

El cobro en esta tabla se refiere únicamente a la consulta al SII para obtener datos del contribuyente. Los modos 1-3 no generan consulta al SII porque ya tienes los datos.

La emisión de la BHET siempre se cobra de acuerdo al plan contratado, independiente del modo de tercero utilizado.

Exclusividad

Solo puede especificarse UN modo. Si se envía más de uno, se retorna error MULTIPLE_TERCERO_MODES.

---

Diagrama de Decisión

¿Tienes datos completos del tercero?
├── SÍ → ¿Están guardados en el sistema?
│        ├── SÍ → Usar Modo 1 (terceroId)
│        └── NO → Usar Modo 2 (tercero)
└── NO → ¿Ya hiciste lookup al SII previamente?
         ├── SÍ → Usar Modo 3 (siiLookup)
         └── NO → Usar Modo 4 (lookupRut) ⚠️ Cobra SII Lookup

---

Modo 1: terceroId (Contribuyente Guardado)

El tercero ya está guardado en el sistema (ContribuyenteMaestro). Puedes usar el ID o el RUT.

{
  "emisorTributarioId": "tu-emisor-tributario-id",
  "terceroId": "78012039-8",
  "prestaciones": [
    { "descripcion": "Servicio de consultoría", "valor": "150000" }
  ]
}

---

Modo 2: tercero (Datos On-The-Fly)

Pasas todos los datos manualmente sin necesidad de lookup.

{
  "emisorTributarioId": "tu-emisor-tributario-id",
  "tercero": {
    "rut": "78012039-8",
    "nombres": "FIRERAISE SPA",
    "domicilio": "Av. Providencia 1234, Of. 501",
    "codigoRegion": "13",
    "codigoComuna": "13101",
    "email": "contacto@fireraise.cl"
  },
  "prestaciones": [
    { "descripcion": "Desarrollo de software", "valor": "250000" }
  ]
}

Campos del objeto tercero:

Campo	Tipo	Requerido	Descripción
rut	string	Sí	RUT del tercero (formato 12345678-9)
nombres	string	Sí	Razón social o nombre completo
domicilio	string	Sí	Dirección completa
codigoRegion	string	Sí	Código de región SII (ej: "13")
codigoComuna	string	Sí	Código de comuna SII (ej: "13101")
email	string	No	Email para envío de boleta

---

Modo 3: siiLookup (Objeto Lookup Completo)

Ya tienes el resultado de un lookup previo al SII.

{
  "emisorTributarioId": "tu-emisor-tributario-id",
  "siiLookup": {
    "rut": "78012039-8",
    "razonSocial": "FIRERAISE SPA",
    "direcciones": [
      {
        "direccion": "AV PROVIDENCIA 1234 OF 501",
        "codigoComuna": "13101",
        "comuna": "SANTIAGO"
      }
    ],
    "email": "contacto@fireraise.cl"
  },
  "prestaciones": [
    { "descripcion": "Consultoría estratégica", "valor": "180000" }
  ]
}

Consejo

Usa este modo cuando emites múltiples BHET al mismo tercero. El lookup se reutiliza sin costo adicional.

---

Modo 4: lookupRut (Ejecutar Lookup)

Solo pasas el RUT y el sistema ejecuta el lookup al SII.

{
  "emisorTributarioId": "tu-emisor-tributario-id",
  "lookupRut": "78012039-8",
  "prestaciones": [
    { "descripcion": "Asesoría legal", "valor": "200000" }
  ]
}

Cobro por SII Lookup

Este modo cobra por la consulta al SII para obtener los datos del contribuyente.

---

Emitir Boleta

Request Completo

POST /{tenantSlug}/bhet
Content-Type: application/json
Authorization: Bearer tu-api-key

{
  "emisorTributarioId": "tu-emisor-tributario-id",
  "tercero": {
    "rut": "78012039-8",
    "nombres": "FIRERAISE SPA",
    "domicilio": "Av. Providencia 1234, Of. 501",
    "codigoRegion": "13",
    "codigoComuna": "13101",
    "email": "contacto@fireraise.cl"
  },
  "prestaciones": [
    { "descripcion": "Servicio de consultoría en sistemas", "valor": "150000" },
    { "descripcion": "Desarrollo de software", "valor": "75000" }
  ],
  "modo": "SINC_PARCIAL",
  "enviarBoletaPorEmail": true,
  "correlationId": "mi-referencia-123"
}

Campos del Request:

Campo	Tipo	Requerido	Descripción
emisorTributarioId	string	Sí	ID del emisor tributario
prestaciones	array	Sí	Lista de servicios (mín 1)
modo	enum	No	SINC_COMPLETO, SINC_PARCIAL (default), ASINCRONO
enviarBoletaPorEmail	boolean	No	Enviar PDF al email del tercero
templateId	string	No	Template con que se representa el PDF interno de esta boleta. Si no lo envías, se usa el de tu empresa (ver Elegir el template del PDF interno)
correlationId	string	No	ID de correlación para tracking. No es una clave: puedes repetirlo entre boletas distintas
idempotencyKey	string	No	Clave de idempotencia, máx. 128 caracteres. Protege contra emisiones duplicadas por reintentos (ver Idempotencia)
fechaEmision	string	No	Fecha de emisión personalizada (ver sección siguiente)

---

Idempotencia

Si tu sistema puede reintentar una emisión —por timeout, error de red o doble click— usa idempotencyKey para que un reintento no genere una segunda boleta ante el SII.

{
  "emisorTributarioId": "cm5abc123",
  "idempotencyKey": "orden-compra-4471",
  "tercero": { "rut": "12345678-9", "nombres": "Juan Pérez", "domicilio": "Av. Principal 123", "codigoRegion": "13", "codigoComuna": "13101" },
  "prestaciones": [{ "descripcion": "Servicio de diseño", "valor": "150000" }]
}

Cómo funciona:

• El alcance de la clave es por emisor tributario: dos emisores pueden usar el mismo valor sin colisionar.
• Si repites la clave y ya hay una boleta emitida con ella, se retorna esa misma boleta —mismo id, mismo folioSii— sin volver a emitir ante el SII ni consumir un folio nuevo.
• En ese caso se vuelve a disparar el webhook bhet.emitida, porque si repetiste la clave lo más probable es que no hayas recibido la notificación anterior.
• Si la emisión falló, la clave no queda reservada: puedes corregir el dato que el SII rechazó y reenviar con la misma clave.
• Si la boleta se anula, la clave se libera y puede volver a usarse.
• En modo ASINCRONO la protección cubre también la emisión en vuelo: si reintentas mientras la primera todavía está en la cola o entre reintentos, recibes el intentoId original en vez de encolar una segunda. Con la ventana de reintentos de 18–22,6 h, esa protección puede estar activa durante horas — usa idempotencyKey si tu sistema reintenta por su cuenta.

No uses correlationId para esto

correlationId es solo trazabilidad y no tiene ninguna restricción de unicidad — puedes mandar el mismo valor en cien boletas distintas. La protección contra duplicados la da idempotencyKey, y son campos independientes que puedes usar juntos.

---

Fecha de Emisión Personalizada

Por defecto, las boletas se emiten con la fecha actual del servidor. Sin embargo, en casos excepcionales puedes especificar una fecha anterior usando el campo fechaEmision.

Uso Especial

Este campo debe usarse solo en casos excepcionales:

• Regularización de servicios prestados en fechas pasadas
• Corrección de emisiones pendientes por problemas técnicos

El usuario es responsable de cumplir con los plazos legales del SII para emisión de documentos tributarios.

Formato

El campo acepta formato ISO YYYY-MM-DD:

{
  "emisorTributarioId": "tu-emisor-tributario-id",
  "terceroId": "78012039-8",
  "prestaciones": [
    { "descripcion": "Servicio de consultoría", "valor": "150000" }
  ],
  "fechaEmision": "2025-12-01"
}

Restricciones

Restricción	Descripción
No futuras	La fecha no puede ser posterior a hoy
Sin validación de plazos	No se valida contra plazos legales del SII
Fecha oficial	El SII registra esta fecha como fecha oficial del documento

Comportamiento en PDFs

Campo en PDF	Valor
Fecha de Emisión	La fecha especificada (o fecha actual si no se especificó)
Fecha de Impresión	Siempre la fecha actual al generar/regenerar el PDF

Esto permite identificar cuándo se prestó el servicio vs cuándo se generó el documento físico.

Campos de prestaciones[]:

Cada prestación puede especificarse de dos formas mutuamente excluyentes:

Modo	Campos Permitidos	Campos Prohibidos
Item libre	descripcion, valor	productoId
Producto del catálogo	productoId, cantidad, descuentoPorcentaje	descripcion, valor, precioUnitario, unidadMedida, codigoSku

Exclusividad Mutua: Precio vs Descuento

Un producto puede tener O precio modificado O descuento, nunca ambos simultáneamente.

• Si envías precioUnitario, el descuentoPorcentaje debe ser 0 o no enviarse
• Si envías descuentoPorcentaje, el precioUnitario no debe enviarse

Cuándo se permite precioUnitario con productos del catálogo:

Condición del Producto	¿Permite precioUnitario?
esquemaPrecio: SIN_PRECIO	Sí (obligatorio)
permisoEdicion: LIBRE	Sí
permisoEdicion: DENTRO_RANGO_DESCUENTO	Sí (dentro del rango)
permisoEdicion: NO_PERMITIDA	No

---

Emisión con Productos del Catálogo

El catálogo se administra desde la aplicación web

Crear, editar y consultar productos y grupos se hace en la aplicación web de Redcumbre. La API usa el catálogo pero no lo administra: acá solo referencias un productoId que ya existe.

Modo 1: Items Libres (Sin Catálogo)

Especifica descripcion y valor directamente. Ideal para servicios únicos o personalizados.

{
  "prestaciones": [
    { "descripcion": "Servicio de consultoría", "valor": "150000" }
  ]
}

Modo 2: Productos del Catálogo

Usa productoId para referenciar un producto configurado en el catálogo. El sistema calcula precios, descuentos y cantidades automáticamente.

{
  "prestaciones": [
    {
      "productoId": "clxyz123abc",
      "cantidad": 3,
      "descuentoPorcentaje": 10
    }
  ]
}

Modo Mixto

Puedes combinar ambos modos en una misma emisión:

{
  "prestaciones": [
    {
      "productoId": "clxyz123abc",
      "cantidad": 2
    },
    {
      "descripcion": "Servicio adicional personalizado",
      "valor": "75000"
    }
  ]
}

---

Response: Modo Síncrono (SINC_COMPLETO / SINC_PARCIAL)

La boleta NO está en la raíz de data — cuelga de data.bhet

data es el resultado de la emisión, no la boleta. Ahí viven modo, descargas, mensaje, correlationId y pdfInternoUrl; la boleta va anidada en data.bhet.

El folio se lee en data.bhet.folioSii, no en data.folioSii. Leerlo del lugar equivocado no falla: devuelve undefined sobre una emisión que sí funcionó.

{
  "success": true,
  "data": {
    "modo": "SINC_PARCIAL",
    "descargas": {
      "pdfInterno": "https://app.redcumbre.cl/acme/tributario/boletas-terceros/cm5abc123def456/descargar?tipo=interno",
      "pdfSii": "https://app.redcumbre.cl/acme/tributario/boletas-terceros/cm5abc123def456/descargar?tipo=sii"
    },
    "bhet": {
      "id": "cm5abc123def456",
      "folioSii": "12345678",
      "codigoBarras": "1234567800388FB4702C",
      "estado": "EMITIDA",
      "estadoPdfSii": "PENDIENTE",
      "modoEmision": "SINC_PARCIAL",
      "pdfInternoUrl": "https://app.redcumbre.cl/p/boleta/eyJhbGciOiJIUzI1NiJ9...",
      "montoBruto": 150000,
      "tasaImpuesto": 15.25,
      "impuesto": 22875,
      "montoNeto": 127125,
      "terceroNombreSii": "FIRERAISE SPA"
    },
    "correlationId": "mi-referencia-123",
    "mensaje": "BHET emitida exitosamente",
    "pdfInternoUrl": "https://app.redcumbre.cl/p/boleta/eyJhbGciOiJIUzI1NiJ9..."
  }
}

El tasaImpuesto del ejemplo —y por lo tanto el impuesto y el montoNeto— corresponde a la tasa vigente en 2026 (15,25%). No la copies como constante: viene en cada respuesta, y también puedes pedirla por adelantado en GET /global/bhet-retencion (ver Cálculo de montos).

SINC_COMPLETO responde lo mismo, con cuatro diferencias: modo y bhet.modoEmision valen SINC_COMPLETO; mensaje deja de ser "BHET emitida exitosamente" y pasa a describir el estado del respaldo ("BHET emitida exitosamente con respaldo SII disponible" si alcanzó a quedar listo, "BHET emitida. El respaldo SII se está generando (se notificará via webhook)" si no); y si alcanzó a quedar listo dentro del request aparece data.pdfSiiUrl (también en data.bhet.pdfSiiUrl) con bhet.estadoPdfSii: "DISPONIBLE". Si no alcanzó, queda en PENDIENTE y se genera en background, igual que en SINC_PARCIAL.

No decidas nada leyendo mensaje

mensaje es texto para mostrar, no un código de estado: cambia entre modos y puede cambiar de redacción. Para ramificar usa modo, bhet.estado y bhet.estadoPdfSii.

Lo que la respuesta de emisión NO trae

Emisor, tercero, prestaciones y fechas no vienen acá: la respuesta de emisión es acotada a propósito. El documento completo se obtiene con GET /{tenantSlug}/bhet/{id}.

Dos canales de descarga, para dos públicos distintos

pdfInternoUrl / pdfSiiUrl son enlaces públicos: sirven para cualquier destinatario, y piden RUT + CAPTCHA antes de entregar el documento.

descargas son enlaces para usuarios de Redcumbre con sesión: descargan directo, sin gate, y quedan registrados en el historial de la boleta. Ver Enlaces de descarga para tus usuarios.

---

Response: Modo ASINCRONO

El modo ASINCRONO valida y encola: la respuesta llega antes de que la boleta exista. Trae un intentoId para consultar el avance.

{
  "success": true,
  "data": {
    "modo": "ASINCRONO",
    "intentoId": "cm5xyz789abc123",
    "correlationId": "mi-referencia-123",
    "estado": "PENDIENTE",
    "mensaje": "Emisión encolada para procesamiento. Consulte el estado con GET /bhet/intento/{intentoId}"
  }
}

El bloque descargas no viene en esta respuesta: todavía no existe el id de la boleta, y las URLs se calculan a partir de él. Llega en GET /bhet/intento/{intentoId} una vez emitida, y en el webhook bhet.emitida.

---

Response: el SII rechaza la emisión

Cambio de contrato — si ya tienes una integración, léelo

Hasta ahora un rechazo del SII respondía 400 con este cuerpo:

{ "success": false, "error": { "code": "SII_EMISOR_BUSY", "message": "…" }, "bhetId": "cm5…" }

Ahora el status distingue la causa (422, 502 o 503) y el cuerpo usa el formato estándar de la plataforma: error pasa a ser texto y aparece message en la raíz. Si tu código lee error.code, muévelo a errorCode; si distingue el fallo por status === 400, ese chequeo deja de dispararse.

Cuando el SII no acepta la boleta, la BHET igual se persiste en estado ERROR con su motivo, para que quede consultable y auditable. Cómo te lo comunicamos depende de quién llama:

Quien emite	Qué recibe
La aplicación web de Redcumbre (sesión de usuario)	201 con success: false — el formulario conserva lo escrito y muestra el motivo
Tu integración (API key)	Un status de error HTTP según la causa: 422, 502 o 503

Tu integración nunca recibe un 2xx por una boleta rechazada. Si la respuesta es 2xx, se emitió.

{
  "statusCode": 422,
  "message": "El tercero no es válido para recibir una boleta de terceros…",
  "error": "Unprocessable Entity",
  "errorCode": "SII_TERCERO_INVALIDO",
  "boletaId": "cm5abc123def456"
}

Campo	Para qué sirve
errorCode	Lo único que conviene programar: es estable y clasifica la causa
message	Texto legible, apto para mostrarle a tu usuario
boletaId	El id de la fila que sí se persistió: GET /{tenantSlug}/bhet/{boletaId} responde 200 con la boleta en ERROR

Qué hacer con cada status

Status	Significa	Qué hacer
422	El SII entendió la solicitud y la rechazó por su contenido o por el estado del contribuyente	No reintentar sin corregir
502	El SII respondió algo que no se puede usar (error interno suyo, sesión caída, servicio degradado)	Reintentar con backoff exponencial
503	El emisor tiene demasiadas emisiones en curso ante el SII y hay que esperar turno	Reintentar después de los segundos del header Retry-After
500	Un defecto nuestro. Dos formas, según el errorCode	Ver abajo

El 500 tiene dos formas, y una de ellas no se reintenta

errorCode	Qué pasó	Qué hacer
(ausente)	La emisión falló con un motivo que la plataforma no tiene clasificado. La boleta quedó persistida en ERROR	Reportarlo con el boletaId
BHET_EMITIDA_NO_PERSISTIDA	La boleta SÍ se emitió ante el SII y la plataforma no pudo guardarla. El cuerpo trae folioSii y codigoBarras en vez de boletaId	No reintentar: emitirías una segunda boleta real. Reportar el folioSii a soporte

{
  "statusCode": 500,
  "message": "La boleta se emitió ante el SII con el folio 489, pero la plataforma no pudo guardarla…",
  "error": "Internal Server Error",
  "errorCode": "BHET_EMITIDA_NO_PERSISTIDA",
  "folioSii": "489",
  "codigoBarras": "77438768004898E5E12E"
}

Es el único caso en que un error no significa “no se emitió”. Por eso el cuerpo trae el folio: es el documento que ya existe ante el SII.

La idempotencia es tu red de seguridad

Un reintento sin idempotencyKey puede emitir una boleta duplicada y quemar un folio. Ver Idempotencia antes de armar tu loop de reintentos.

---

Consultar Estado Asíncrono

Para el modo ASINCRONO, consulta el estado del intento:

GET /{tenantSlug}/bhet/intento/{intentoId}
Authorization: Bearer tu-api-key

Response

{
  "success": true,
  "data": {
    "id": "cm5xyz789abc123",
    "estado": "EMITIDA",
    "bhet": {
      "id": "cm5abc123xyz",
      "folioSii": "123456789",
      "codigoBarras": "ABC123...",
      "estado": "EMITIDA",
      "estadoPdfSii": "DISPONIBLE",
      "pdfInternoUrl": "https://...",
      "pdfSiiUrl": "https://...",
      "descargas": {
        "pdfInterno": "https://app.redcumbre.cl/acme/tributario/boletas-terceros/cm5abc123xyz/descargar?tipo=interno",
        "pdfSii": "https://app.redcumbre.cl/acme/tributario/boletas-terceros/cm5abc123xyz/descargar?tipo=sii"
      }
    },
    "intentos": 1,
    "ultimoIntento": "2025-12-08T15:30:00Z",
    "correlationId": "mi-referencia-123",
    "createdAt": "2025-12-08T15:00:00Z",
    "updatedAt": "2025-12-08T15:30:00Z"
  }
}

Acá el intento va en data y la boleta en data.bhet, igual que en la emisión síncrona. Mientras el intento no llegue a EMITIDA, data.bhet no viene.

Estados del intento:

Estado	Descripción
PENDIENTE	Registrado en cola, pendiente de procesamiento
PROCESANDO	En proceso de emisión
EMITIDA	Emitido exitosamente (tiene BHET asociada)
REINTENTANDO	Un intento falló y el sistema va a volver a intentarlo. No es un desenlace: todavía hay algo que esperar
FALLIDA	Falló definitivamente: se agotaron los 10 intentos (18–22,6 h) o el error del SII no se recupera reintentando

---

Gestión de PDFs

El sistema genera dos tipos de PDF:

Tipo	Descripción	Disponibilidad
PDF Interno	Generado con template personalizado del tenant	Inmediato (modo síncrono)
PDF SII	Respaldo oficial descargado del SII	Depende de disponibilidad del SII

---

Elegir el template del PDF interno

El PDF interno se representa con un template. Si no eliges ninguno, se usa el que tenga configurado tu empresa y, en su defecto, el estándar de la plataforma — que es lo que ocurre hoy si nunca tocaste esto.

Para elegirlo explícitamente, manda templateId en la emisión:

{
  "emisorTributarioId": "cmrkobzro001psetmqwfyo7py",
  "prestaciones": [{ "descripcion": "Servicio prestado", "valor": "150000" }],
  "templateId": "tpl_bhet_002"
}

El identificador queda fijo en la boleta. Eso significa que toda representación posterior de ese documento usa el mismo template, incluido el comprobante con la marca de anulación que se genera después. Un cambio en la configuración de tu empresa NO altera boletas ya emitidas.

El template elegido también viaja por correo

El PDF interno es el que se adjunta al correo del tercero cuando usas enviarBoletaPorEmail. Si eliges un formato de rollo térmico para imprimir en mostrador, el tercero recibe ese mismo formato por correo.

Un templateId que no exista, o que pertenezca a otro tipo de documento, responde 400 y la boleta no se emite. No se resuelve en silencio a otro template.

Templates disponibles:

Identificador	Formato	Uso típico
tpl_bhet_001	Carta	Default de la plataforma
tpl_bhet_002	Rollo 80 mm	Impresora térmica de mostrador
tpl_bhet_003	Rollo 57 mm	Impresora POS

El template con que se generó cada archivo viene en templateId dentro de GET /{tenantSlug}/bhet/{id}/archivos. Tu empresa puede tener templates propios además de estos: los ves en la interfaz web, en el detalle de la boleta.

---

Estados del PDF SII

Estado	Descripción
NO_APLICA	Modo SINC_COMPLETO exitoso o sandbox
PENDIENTE	En cola para descarga
DISPONIBLE	Descargado exitosamente
FALLIDO	Agotó reintentos después de 7 días

---

Descargar PDF

# PDF Interno (template personalizado)
GET /{tenantSlug}/bhet/{id}/pdf/interno

# PDF SII (respaldo oficial)
GET /{tenantSlug}/bhet/{id}/pdf/sii

# Archivo específico del panel de archivos
GET /{tenantSlug}/bhet/{id}/archivos/{archivoId}/download

# PDF generado al momento con otro template (no se guarda)
GET /{tenantSlug}/bhet/{id}/pdf/custom?templateId=tpl_bhet_002

Todos streamean el archivo como application/pdf (Content-Disposition: attachment). No son redirects y nunca entregan una URL de bucket.

Si el documento pedido no existe todavía, responden 404 con el motivo:

{
  "success": false,
  "error": {
    "code": "PDF_SII_NOT_AVAILABLE",
    "message": "El PDF SII de esta boleta no está disponible. Estado: PENDIENTE",
    "estadoPdfSii": "PENDIENTE"
  }
}

Usa error.estadoPdfSii para distinguir “todavía se está generando” (PENDIENTE, reintenta más tarde) de “falló definitivamente” (FALLIDO, usa el PDF interno).

Modo sandbox

Con una API key en modo sandbox estos endpoints devuelven un PDF de ejemplo, nunca el documento real, aunque el id corresponda a una boleta real.

---

Enlaces de descarga para tus usuarios

Si tu sistema tiene una interfaz propia y tus usuarios también son usuarios de Redcumbre, el bloque descargas te da un enlace listo para pintar:

<a href="{{ descargas.pdfInterno }}" target="_blank">Descargar boleta</a>
<a v-if="estadoPdfSii === 'DISPONIBLE'" :href="descargas.pdfSii" target="_blank">Respaldo SII</a>

Campo	Para qué sirve
descargas.pdfInterno	Enlace al PDF interno. Descarga directa, sin RUT ni CAPTCHA
descargas.pdfSii	Ídem para el respaldo SII. Viene siempre, aunque el documento aún no exista
estadoPdfSii	Semáforo: con DISPONIBLE el respaldo ya está; con PENDIENTE el enlace muestra “se está generando”

Cómo funcionan:

• Son enlaces de navegación (<a href>, window.location). No funcionan con fetch ni axios desde tu dominio: la cookie de sesión de Redcumbre es SameSite=Lax y no viaja en peticiones XHR cross-site.
• Requieren un usuario con sesión en Redcumbre y rol del módulo (SUPER-ADMIN, ADMIN, SII-EMISOR-BHET o FULL-API). Si no hay sesión, el enlace pasa por el login y vuelve solo al documento.
• La descarga queda registrada en el historial de actividad de la boleta.
• Son estables: se calculan desde el id y sobreviven a la regeneración del PDF.

¿Tus usuarios no tienen cuenta en Redcumbre?

Entonces estos enlaces no les sirven. Usa pdfInternoUrl / pdfSiiUrl, que son públicos y piden RUT del tercero + CAPTCHA. Ambos canales vienen en la misma respuesta.

---

Listar Archivos PDF

GET /{tenantSlug}/bhet/{id}/archivos

El campo url de cada archivo es el enlace para el destinatario de la boleta: abre la página pública de descarga, que le pide su RUT antes de entregar el archivo, y es el mismo enlace que recibe por correo. No es una URL de bucket. Para descargar el archivo desde tu integración usa GET /{tenantSlug}/bhet/{id}/archivos/{archivoId}/download.

Response:

{
  "success": true,
  "data": [
    {
      "id": "archivo-001",
      "tipo": "INTERNO",
      "templateId": "template-001",
      "templateName": "Template Carta",
      "fileName": "bhet_12345678_interno.pdf",
      "url": "https://...",
      "sizeBytes": 125000,
      "createdAt": "2025-12-05T15:30:00Z",
      "createdBy": "Sistema"
    },
    {
      "id": "archivo-002",
      "tipo": "SII",
      "templateId": null,
      "templateName": null,
      "fileName": "bhet_12345678_sii.pdf",
      "url": "https://...",
      "sizeBytes": 98000,
      "createdAt": "2025-12-05T15:35:00Z",
      "createdBy": "SII"
    }
  ]
}

---

Listar y Consultar

Listar Boletas

GET /{tenantSlug}/bhet?fechaDesde=2025-01-01&estado=EMITIDA&limit=50
Authorization: Bearer tu-api-key

Filtros disponibles:

Parámetro	Tipo	Descripción
fechaDesde	ISO 8601	Fecha de inicio del rango
fechaHasta	ISO 8601	Fecha de fin del rango
emisorTributarioId	string	Filtrar por emisor
terceroRut	string	Filtrar por RUT del tercero
estado	enum	EMITIDA, ERROR
canalEmision	enum	UI, API_SYNC, API_ASYNC
folioSii	string	Buscar por folio (substring)
limit	number	Registros por página (default: 50, max: 100)
offset	number	Registros a saltar (default: 0)

---

Obtener Detalle

GET /{tenantSlug}/bhet/{id}
Authorization: Bearer tu-api-key

Es el documento completo, y es más de lo que devuelve la emisión: emisor, tercero, prestaciones con su desglose de descuentos, tasaImpuesto, fechas, descargas y el estado de una eventual anulación. Todo eso llega en data (acá sí, plano — la boleta es el recurso). El listado de campos con sus tipos está en Swagger.

---

Webhooks

El sistema envía webhooks para 4 eventos relacionados con BHET:

Evento	Descripción	Cuándo se dispara
bhet.emitida	BHET emitida exitosamente	Inmediatamente después de emitir
bhet.emision_terminada	PDF SII disponible	Cuando se descarga el PDF SII en background
bhet.pdf_sii_fallido	Descarga PDF SII falló	Después de 7 días de reintentos fallidos
bhet.emision_reintentando	Un intento falló y va a reintentarse	En cada intento intermedio — informativo, no reemitas
bhet.emision_fallida	Emisión asíncrona falló definitivamente	Una sola vez: al agotar los 10 intentos, o en el primero si el error es permanente

---

Payload: bhet.emitida

{
  "event": "bhet.emitida",
  "tenantId": "8",
  "bhetId": "cm5abc123",
  "folioSii": "12345678",
  "emisor": {
    "rut": "76123456-7",
    "razonSocial": "EMPRESA CONTRATANTE SPA"
  },
  "tercero": {
    "rut": "78012039-8",
    "nombre": "FIRERAISE SPA"
  },
  "montos": {
    "bruto": 150000,
    "impuesto": 22875,
    "neto": 127125
  },
  "canalEmision": "API_SYNC",
  "correlationId": "mi-referencia-123",
  "sandbox": false,
  "timestamp": "2025-12-05T15:30:00Z"
}

---

Cálculo de Montos

El sistema calcula automáticamente los montos:

Monto Bruto = Suma de todas las prestaciones
Impuesto    = Monto Bruto × tasa de retención   (redondeado al peso)
Monto Neto  = Monto Bruto - Impuesto

No hardcodees la tasa de retención

La tasa de retención de BHET cambia por año tributario. Consúltala en GET /global/bhet-retencion, que la devuelve como fracción y como porcentaje:

{ "success": true, "data": { "bhetTasaRetencion": 0.1525, "bhetTasaRetencionPercent": 15.25 } }

El valor del ejemplo es el vigente en 2026; el endpoint devuelve el que rija al momento de consultarlo.

Lo mismo aplica al PPM de las BHE, en GET /global/ppm. Ambos endpoints viven bajo /global/ y piden cualquier API Key válida, sin exigir un rol en particular.

Si calculas el neto para mostrárselo al usuario antes de confirmar una emisión —que es irreversible—, esa pantalla tiene que usar la tasa del endpoint, no una constante en tu código.

Las emisiones fechadas en 2025 usan la tasa de 2025

Si envías fechaEmision con una fecha de 2025, la boleta se calcula con la tasa fija de ese año (14,5%). Para cualquier otra fecha —incluido omitir el campo, que toma el día de hoy— se aplica la tasa vigente, la misma que devuelve GET /global/bhet-retencion.

Es una excepción puntual para 2025, no una tabla de tasas por año: no asumas que una fecha de otro año pasado va a recuperar la tasa que regía entonces.

Por eso conviene leer siempre data.bhet.tasaImpuesto de la respuesta: es la tasa que efectivamente se aplicó a esa boleta.

---

Códigos de Error

Errores de Validación (400)

Código	Descripción
MULTIPLE_TERCERO_MODES	Se especificó más de un modo de tercero
TERCERO_REQUIRED	No se especificó ningún modo de tercero
CONTRIBUYENTE_NOT_FOUND	ID/RUT no existe en ContribuyenteMaestro (modo 1)
INVALID_COMUNA_CODE	codigoComuna no existe en catálogo (modo 2)
SII_LOOKUP_FAILED	Lookup al SII falló (modo 4)
EMISOR_NO_HABILITADO	El emisor no tiene el servicio BHET habilitado

Errores del SII

El errorCode llega en el cuerpo del error (canal de máquina) y en data.bhet.errorCode (canal web). El status te dice si conviene reintentar sin tener que interpretar el código.

No reintentables — corrige antes de volver a intentar (422)

Código	Descripción
SII_RUT_INVALIDO	RUT del emisor o tercero no válido
SII_TERCERO_INVALIDO	El tercero no es válido para recibir una BHET
SII_DATOS_INVALIDOS	Datos de la boleta incorrectos
SII_FORM_ERROR	El formulario del SII rechazó los datos enviados
SII_NO_HABILITADO	El emisor no está habilitado ante el SII
SII_CERTIFICADO_ERROR	Error con certificado digital
SII_EMISION_FAILED	El SII rechazó la emisión con un mensaje propio (viene en message)

Reintentables con backoff — el problema es del SII (502)

Código	Descripción
SII_AUTH_FAILED	El SII no devolvió TOKEN y no explicó por qué. Suele ser un problema pasajero de su lado
SII_ERROR	Error genérico del SII durante la emisión
SII_RESPUESTA_INESPERADA	El SII respondió algo que no se pudo interpretar
SII_ERROR_INTERNO	Error interno declarado por el SII (código IMT…)
SII_SOLICITUD_FALLIDA	”No ha sido posible completar su solicitud”
SII_SESION_EXPIRADA	La sesión con el SII expiró durante la operación
SII_SERVICIO_NO_DISPONIBLE	El servicio del SII no está disponible

Reintentable con espera — hay turno por delante (503)

Código	Descripción
SII_EMISOR_BUSY	Demasiadas emisiones en curso para ese emisor. Respeta el header Retry-After

---

Estados de la Boleta

Estado	Descripción
EMITIDA	Emitida correctamente en el SII (tiene folio y código de barras)
ERROR	Error inmediato no reintentable

---

Testing (Sandbox)

Utiliza el modo sandbox para probar la integración sin costo:

• API Keys con isSandbox: true retornan datos de prueba
• No se realizan llamadas reales al SII
• No se genera billing
• Webhooks funcionan normalmente
• No sale ningún correo al destinatario, ni al emitir con enviarBoletaPorEmail: true, ni al reenviar el PDF manualmente desde la aplicación web. La supresión se decide por el folio de la boleta, así que una boleta emitida en sandbox no despacha correo nunca, tampoco meses después desde el panel. Ver Entornos y modo sandbox.

El sandbox no te ahorra dar de alta un emisor

El emisorTributarioId es obligatorio también en sandbox, y tiene que ser un emisor real de tu tenant: el que no existe responde 404 Emisor tributario no encontrado, y el de otro tenant, 400 El emisor no pertenece a este tenant. No hay identificador comodín ni emisor de prueba compartido. Da de alta el tuyo con Tokenización SII antes de probar.

---

RUTs de Prueba (Tercero)

RUT	Resultado	Descripción
78012039-8	✅ Éxito	Empresa completa (FIRERAISE SPA)
77425402-1	✅ Éxito	Empresa con múltiples direcciones
13830230-k	✅ Éxito	Persona natural (PDF SII pendiente)
99999999-9	❌ Error	Tercero no existe en SII

Ejemplo en sandbox:

POST /{tenantSlug}/bhet
Authorization: Bearer sandbox-api-key

{
  "emisorTributarioId": "tu-emisor-tributario-id",
  "lookupRut": "78012039-8",
  "prestaciones": [
    { "descripcion": "Servicio de prueba", "valor": "100000" }
  ]
}

Response (sandbox):

{
  "success": true,
  "data": {
    "id": "sandbox-bhet-001",
    "folioSii": "SBX1234567890",
    "codigoBarras": "78012039SBX1234567890SANDBOX",
    "estado": "EMITIDA",
    ...
  },
  "sandbox": true
}

---

API Reference

Para detalles técnicos completos y especificaciones de todos los endpoints:

👉 Ver endpoints de BHET en Swagger

---

¿Necesitas anular una BHET?

La anulación ante el SII tiene su propia guía: causas, seguimiento por webhook, comprobante al tercero y los límites de 10 días / $1.000.000.

👉 Anulación de Boletas