Boletas de Honorarios

Boletas de Honorarios Electrónicas (BHE)

TL;DR - Acceso Rápido

Endpoint: POST /{tenantSlug}/bhe

👉 Ver endpoints de BHE en Swagger

Las Boletas de Honorarios Electrónicas son documentos tributarios que emiten las personas naturales por servicios profesionales prestados. Nuestra API permite emitir BHE con diferentes modos de emisión, gestionar PDFs y recibir notificaciones vía webhook.

---

Requisitos Previos

Antes de emitir una BHE necesitas:

1. Un Emisor Tributario activo con clave tributaria delegada (no certificado digital)
2. Una API Key con uno de estos roles: ADMIN, SUPER-ADMIN, SII-EMISOR-BHE, o FULL-API
3. Los datos del destinatario (o usar sinDestinatario: true para emitir sin destinatario)

Importante

Las BHE requieren clave tributaria, no certificado digital. Solo personas naturales pueden emitir BHE.

---

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	BHE completa con ambos PDFs	Cuando necesitas todo inmediato
SINC_PARCIAL	Emitir + PDF interno síncronos, PDF SII en background	BHE 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 /bhe ─────────────▶│                        │
  │   (modo: SINC_PARCIAL)    │                        │
  │                           │── Emitir BHE ─────────▶│
  │                           │◀── folioSii ──────────│
  │                           │                        │
  │                           │── Genera PDF interno   │
  │                           │                        │
  │◀── Response ──────────────│                        │
  │   (folioSii + pdfInternoUrl)                       │
  │   (estadoPdfSii: PENDIENTE)                        │
  │                           │                        │
  │                      [Background]                  │
  │                           │── Descarga PDF SII ───▶│
  │                           │◀── PDF ───────────────│
  │                           │                        │
  │◀── Webhook ───────────────│                        │
  │   (bhe.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 /bhe ─────────────▶│                        │
  │   (modo: ASINCRONO)       │                        │
  │                           │── Valida datos         │
  │                           │── Encola emisión       │
  │                           │                        │
  │◀── Response ──────────────│                        │
  │   (intentoId, estado: PENDIENTE)                   │
  │                           │                        │
  │                      [Background]                  │
  │                           │── Emitir BHE ─────────▶│
  │                           │◀── folioSii ──────────│
  │                           │── Genera PDF interno   │
  │                           │                        │
  │◀── Webhook ───────────────│                        │
  │   (bhe.emitida)           │                        │

Ventajas:

• Respuesta instantánea (solo valida y encola)
• Reintentos automáticos por hasta 7 horas si el SII falla
• Ideal para procesos batch o cuando no necesitas el resultado inmediato

Consultar estado:

GET /{tenantSlug}/bhe/intento/{intentoId}

---

Modos de Destinatario

Cuando sinDestinatario=false, existen 4 formas mutuamente excluyentes de especificar el destinatario:

Modo	Campo	Descripción	Cobra SII Lookup
1	destinatarioId	RUT de contribuyente guardado en sistema	No
2	destinatario	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 BHE siempre se cobra de acuerdo al plan contratado, independiente del modo de destinatario utilizado.

Exclusividad

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

---

Diagrama de Decisión

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

---

Modo 1: destinatarioId (Contribuyente Guardado)

El destinatario ya está guardado en el sistema (ContribuyenteMaestro).

{
  "emisorTributarioId": "cmitg28qt0009serjtjcrejci",
  "sinDestinatario": false,
  "destinatarioId": "12345678-9",
  "prestaciones": [
    { "descripcion": "Servicio de consultoría", "valor": "150000" }
  ],
  "tipoRetencion": "RETRECEPTOR"
}

---

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

Pasas todos los datos manualmente sin necesidad de lookup.

{
  "emisorTributarioId": "cmitg28qt0009serjtjcrejci",
  "sinDestinatario": false,
  "destinatario": {
    "rut": "12345678-9",
    "nombres": "EMPRESA CLIENTE SA",
    "direccion": "Av. Providencia 1234, Of. 501",
    "codigoRegion": "13",
    "codigoComuna": "13101",
    "email": "contacto@empresa.cl"
  },
  "prestaciones": [
    { "descripcion": "Servicio de consultoría", "valor": "150000" }
  ],
  "tipoRetencion": "RETRECEPTOR"
}

Campos del objeto destinatario:

Campo	Tipo	Requerido	Descripción
rut	string	Sí	RUT del destinatario (formato 12345678-9)
nombres	string	Sí	Razón social o nombre completo
direccion	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": "cmitg28qt0009serjtjcrejci",
  "sinDestinatario": false,
  "siiLookup": {
    "rut": "12345678-9",
    "razonSocial": "EMPRESA CLIENTE SA",
    "direcciones": [
      {
        "direccion": "AV PROVIDENCIA 1234 OF 501",
        "codigoComuna": "13101",
        "comuna": "SANTIAGO"
      }
    ],
    "email": "contacto@empresa.cl"
  },
  "prestaciones": [
    { "descripcion": "Servicio de consultoría", "valor": "150000" }
  ],
  "tipoRetencion": "RETRECEPTOR"
}

Consejo

Usa este modo cuando emites múltiples BHE al mismo destinatario. 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": "cmitg28qt0009serjtjcrejci",
  "sinDestinatario": false,
  "lookupRut": "12345678-9",
  "prestaciones": [
    { "descripcion": "Servicio de consultoría", "valor": "150000" }
  ],
  "tipoRetencion": "RETRECEPTOR"
}

Cobro por SII Lookup

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

---

Emitir Boleta

Request Completo

POST /{tenantSlug}/bhe
Content-Type: application/json
X-API-Key: tu-api-key

{
  "emisorTributarioId": "cmitg28qt0009serjtjcrejci",
  "sinDestinatario": false,
  "destinatario": {
    "rut": "12345678-9",
    "nombres": "EMPRESA CLIENTE SA",
    "direccion": "Av. Providencia 1234, Of. 501",
    "codigoRegion": "13",
    "codigoComuna": "13101",
    "email": "contacto@empresa.cl"
  },
  "prestaciones": [
    { "descripcion": "Servicio de consultoría en sistemas", "valor": "150000" },
    { "descripcion": "Desarrollo de software", "valor": "75000" }
  ],
  "tipoRetencion": "RETRECEPTOR",
  "modo": "SINC_PARCIAL",
  "enviarBoletaPorEmail": true,
  "correlationId": "mi-referencia-123"
}

Campos del Request:

Campo	Tipo	Requerido	Descripción
emisorTributarioId	string	Sí	ID del emisor tributario
sinDestinatario	boolean	Sí	true para emitir sin destinatario
prestaciones	array	Sí	Lista de servicios (mín 1, máx 4)
prestaciones[].descripcion	string	Sí	Descripción del servicio (máx 80 chars)
prestaciones[].valor	string	Sí	Monto en CLP (string numérico)
tipoRetencion	enum	Sí	RETRECEPTOR o RETCONTRIBUYENTE
modo	enum	No	SINC_COMPLETO, SINC_PARCIAL (default), ASINCRONO
enviarBoletaPorEmail	boolean	No	Enviar PDF al email del destinatario
correlationId	string	No	ID de correlación para tracking

---

Response: Modo Síncrono (SINC_COMPLETO / SINC_PARCIAL)

{
  "success": true,
  "data": {
    "id": "cm5abc123def456",
    "folioSii": "12345678",
    "codigoBarras": "1234567800388FB4702C",
    "fechaEmision": "2025-12-05T15:30:00Z",
    "fechaEmisionSii": "2025-12-05T15:30:00Z",
    "canalEmision": "API_SYNC",
    "emisor": {
      "rut": "78012039-8",
      "razonSocial": "JUAN PÉREZ GONZÁLEZ"
    },
    "destinatario": {
      "rut": "12345678-9",
      "nombres": "EMPRESA CLIENTE SA",
      "sinDestinatario": false
    },
    "prestaciones": [
      { "descripcion": "Servicio de consultoría en sistemas", "valor": "150000" },
      { "descripcion": "Desarrollo de software", "valor": "75000" }
    ],
    "tipoRetencion": "RETRECEPTOR",
    "montoBruto": 225000,
    "ppm": 30938,
    "montoLiquido": 194062,
    "estado": "EMITIDA",
    "modoEmision": "SINC_PARCIAL",
    "estadoPdfSii": "PENDIENTE",
    "pdfInternoUrl": "https://storage.googleapis.com/.../interno.pdf",
    "correlationId": "mi-referencia-123",
    "createdAt": "2025-12-05T15:30:00Z"
  }
}

---

Response: Modo ASINCRONO

{
  "success": true,
  "intentoId": "cm5xyz789abc123",
  "correlationId": "mi-referencia-123",
  "estado": "PENDIENTE",
  "mensaje": "Emisión encolada para procesamiento asíncrono. Consulte el estado o espere webhook."
}

---

Consultar Estado Asíncrono

Para el modo ASINCRONO, consulta el estado del intento:

GET /{tenantSlug}/bhe/intento/{intentoId}
X-API-Key: tu-api-key

Response

{
  "id": "cm5xyz789abc123",
  "estado": "EMITIDA",
  "bhe": {
    "id": "cm5abc123xyz",
    "folioSii": "123456789",
    "codigoBarras": "ABC123...",
    "estado": "EMITIDA",
    "estadoPdfSii": "DISPONIBLE",
    "pdfInternoUrl": "https://...",
    "pdfSiiUrl": "https://..."
  },
  "intentos": 1,
  "ultimoIntento": "2025-12-08T15:30:00Z",
  "correlationId": "mi-referencia-123",
  "createdAt": "2025-12-08T15:00:00Z",
  "updatedAt": "2025-12-08T15:30:00Z"
}

Estados del intento:

Estado	Descripción
PENDIENTE	Registrado en cola, pendiente de procesamiento
PROCESANDO	En proceso de emisión
EMITIDA	Emitido exitosamente (tiene BHE asociada)
FALLIDA	Falló después de agotar reintentos (~7 horas)

---

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

---

Estados del PDF SII

Estado	Descripción
NO_APLICA	Modo SINC_COMPLETO exitoso (ya tiene PDF) o boleta no emitida
PENDIENTE	En cola para descarga
DISPONIBLE	Descargado exitosamente
FALLIDO	Agotó reintentos después de 7 días

---

Descargar PDF

# Descarga automática (prioriza PDF SII > PDF Interno)
GET /{tenantSlug}/bhe/{id}/pdf

# PDF Interno específico (template personalizado)
GET /{tenantSlug}/bhe/{id}/pdf/interno

# PDF SII específico (respaldo oficial)
GET /{tenantSlug}/bhe/{id}/pdf/sii

Todos retornan redirect 302 a la URL del PDF.

---

Generar PDF con Template Específico

POST /{tenantSlug}/bhe/{id}/pdf/generate
Content-Type: application/json
X-API-Key: tu-api-key

{
  "templateId": "cm5template123"
}

Response:

{
  "success": true,
  "data": {
    "archivoId": "cm5archivo789",
    "url": "https://storage.googleapis.com/.../custom.pdf",
    "templateId": "cm5template123",
    "fileName": "bhe_12345678_custom.pdf"
  }
}

---

Reintentar Descarga PDF SII

Si el PDF SII está en estado FALLIDO, puedes forzar un reintento:

POST /{tenantSlug}/bhe/{id}/reintentar-pdf-sii
X-API-Key: tu-api-key

---

Listar Archivos PDF

GET /{tenantSlug}/bhe/{id}/archivos

Response:

{
  "success": true,
  "data": [
    {
      "id": "archivo-001",
      "tipo": "INTERNO",
      "templateId": "template-001",
      "templateName": "Template Carta",
      "fileName": "bhe_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": "bhe_12345678_sii.pdf",
      "url": "https://...",
      "sizeBytes": 98000,
      "createdAt": "2025-12-05T15:35:00Z",
      "createdBy": "SII"
    }
  ]
}

---

Listar y Consultar

Listar Boletas

GET /{tenantSlug}/bhe?fechaDesde=2025-01-01&estado=EMITIDA&limit=50
X-API-Key: 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
destinatarioRut	string	Filtrar por RUT del destinatario
estado	enum	EMITIDA, ANULADA, 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)

Response:

{
  "data": [
    { /* BheResponseDto */ }
  ],
  "total": 100,
  "limit": 50,
  "offset": 0
}

---

Obtener Detalle

GET /{tenantSlug}/bhe/{id}
X-API-Key: tu-api-key

---

Enviar por Email

Enviar Boleta al Destinatario

Envía el PDF de la boleta al email del destinatario configurado:

POST /{tenantSlug}/bhe/{id}/enviar-email
X-API-Key: tu-api-key

Requisitos:

• BHE debe estar en estado EMITIDA
• Debe tener destinatarioEmail configurado
• Debe tener al menos un PDF disponible

---

Enviar Archivo Específico a Email Arbitrario

POST /{tenantSlug}/bhe/{id}/archivos/{archivoId}/enviar-email
Content-Type: application/json
X-API-Key: tu-api-key

{
  "email": "otro@email.cl"
}

---

Webhooks

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

Evento	Descripción	Cuándo se dispara
bhe.emitida	BHE emitida exitosamente	Inmediatamente después de emitir
bhe.emision_terminada	PDF SII disponible	Cuando se descarga el PDF SII en background
bhe.pdf_sii_fallido	Descarga PDF SII falló	Después de 7 días de reintentos fallidos
bhe.emision_fallida	Emisión asíncrona falló	Después de ~7 horas de reintentos (modo ASINCRONO)

---

Payload: bhe.emitida

{
  "event": "bhe.emitida",
  "tenantId": "8",
  "bheId": "cm5abc123",
  "folioSii": "12345678",
  "emisor": {
    "rut": "78012039-8",
    "razonSocial": "JUAN PÉREZ GONZÁLEZ"
  },
  "destinatario": {
    "rut": "12345678-9",
    "nombre": "EMPRESA CLIENTE SA",
    "sinDestinatario": false
  },
  "montos": {
    "bruto": 225000,
    "ppm": 30938,
    "liquido": 194062
  },
  "tipoRetencion": "RETRECEPTOR",
  "canalEmision": "API_SYNC",
  "correlationId": "mi-referencia-123",
  "sandbox": false,
  "timestamp": "2025-12-05T15:30:00Z"
}

---

Payload: bhe.emision_terminada

Se envía cuando el PDF SII está disponible (solo para modos SINC_PARCIAL y ASINCRONO):

{
  "event": "bhe.emision_terminada",
  "tenantId": "8",
  "bheId": "cm5abc123",
  "folioSii": "12345678",
  "pdfInternoUrl": "https://storage.googleapis.com/.../interno.pdf",
  "pdfSiiUrl": "https://storage.googleapis.com/.../sii.pdf",
  "estadoPdfSii": "DISPONIBLE",
  "timestamp": "2025-12-05T15:35:00Z"
}

---

Payload: bhe.pdf_sii_fallido

Se envía después de 7 días de reintentos fallidos:

{
  "event": "bhe.pdf_sii_fallido",
  "tenantId": "8",
  "bheId": "cm5abc123",
  "folioSii": "12345678",
  "intentosRealizados": 30,
  "primerIntento": "2025-12-01T15:30:00Z",
  "ultimoIntento": "2025-12-08T15:30:00Z",
  "ultimoError": "SII_PDF_NO_DISPONIBLE",
  "timestamp": "2025-12-08T15:30:00Z"
}

---

Payload: bhe.emision_fallida

Se envía cuando una emisión asíncrona falla después de ~7 horas de reintentos:

{
  "event": "bhe.emision_fallida",
  "tenantId": "8",
  "correlationId": "mi-referencia-123",
  "intentosRealizados": 15,
  "primerIntento": "2025-12-08T10:00:00Z",
  "ultimoIntento": "2025-12-08T17:00:00Z",
  "ultimoError": "SII_SERVICE_UNAVAILABLE",
  "timestamp": "2025-12-08T17:00:00Z"
}

---

Cálculo de Montos

El sistema calcula automáticamente los montos:

Monto Bruto = Suma de todas las prestaciones
PPM = Monto Bruto × 13.75% (tasa actual 2024-2025)
Monto Líquido = Monto Bruto - PPM

Tipos de Retención:

Tipo	Descripción
RETRECEPTOR	El receptor/pagador retiene el PPM (más común)
RETCONTRIBUYENTE	El emisor retiene su propio PPM

---

Códigos de Error

Errores de Validación (400)

Código	Descripción
MULTIPLE_DESTINATARIO_MODES	Se especificó más de un modo de destinatario
DESTINATARIO_REQUIRED	No se especificó ningún modo (y sinDestinatario=false)
CONTRIBUYENTE_NOT_FOUND	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)

Errores del SII (No Reintentables)

Código	Descripción
SII_SIN_SEGUNDA_CATEGORIA	Contribuyente sin actividades de segunda categoría
SII_PERSONA_JURIDICA	Las BHE solo son para personas naturales
SII_NO_HABILITADO	Contribuyente no habilitado para emitir BHE
SII_AUTH_FAILED	Credenciales incorrectas (RUT/clave tributaria)
SII_RUT_INVALIDO	RUT del emisor o destinatario no válido
SII_DATOS_INVALIDOS	Datos de la boleta incorrectos
SII_CERTIFICADO_ERROR	Error con certificado digital

Errores de Recurso (404)

Código	Descripción
PDF_NOT_AVAILABLE	No hay PDF disponible para descargar
PDF_SII_NOT_AVAILABLE	PDF SII no disponible (revisa estadoPdfSii)

---

Estados de la Boleta

Estado	Descripción
EMITIDA	Emitida correctamente en el SII (tiene folio y código de barras)
ANULADA	Boleta anulada
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

---

RUTs de Prueba

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	Destinatario no existe en SII

Ejemplo en sandbox:

POST /{tenantSlug}/bhe
X-API-Key: sandbox-api-key

{
  "emisorTributarioId": "cmitg28qt0009serjtjcrejci",
  "sinDestinatario": false,
  "lookupRut": "78012039-8",
  "prestaciones": [
    { "descripcion": "Servicio de prueba", "valor": "100000" }
  ],
  "tipoRetencion": "RETRECEPTOR"
}

Response (sandbox):

{
  "success": true,
  "data": {
    "id": "sandbox-bhe-001",
    "folioSii": "SANDBOX-12345678",
    "codigoBarras": "SANDBOX7801203988FB4702C...",
    "estado": "EMITIDA",
    ...
  },
  "sandbox": true
}

---

API Reference

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

👉 Ver endpoints de BHE en Swagger