Boletas de Honorarios

Boletas de Honorarios Electrónicas (BHE)

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:

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

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í

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"
}

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"
}

Emitir Boleta

Request Completo

POST /{tenantSlug}/bhe
Content-Type: application/json
Authorization: Bearer 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)
`tipoRetencion`	enum	Sí	`RETRECEPTOR` o `RETCONTRIBUYENTE`
`validarCatalogo`	boolean	No	Forzar validación contra catálogo de productos
`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
`fechaEmision`	string	No	Fecha de emisión personalizada (ver sección siguiente)

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.

Formato

El campo acepta formato ISO YYYY-MM-DD:

{
  "emisorTributarioId": "cmitg28qt0009serjtjcrejci",
  "sinDestinatario": false,
  "destinatarioId": "12345678-9",
  "prestaciones": [
    { "descripcion": "Servicio de consultoría", "valor": "150000" }
  ],
  "tipoRetencion": "RETRECEPTOR",
  "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`

Con productoId:

Solo enviar: productoId (requerido), cantidad (default: 1), descuentoPorcentaje (opcional, 0-100%)
El sistema calcula automáticamente: precio, descripción, unidad de medida, valor total
Si envías campos prohibidos, recibirás error 400

Sin productoId (item libre):

Enviar: descripcion (requerido, máx 80 chars), valor (requerido, string numérico en CLP)
No hay validación de catálogo

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 sistema soporta dos modos de especificar prestaciones:

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
    }
  ]
}

Puedes combinar ambos modos en una misma emisión:

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

Validaciones del Catálogo

Cuando usas productoId, el sistema valida automáticamente:

Validación	Descripción
Existencia	El producto debe existir y pertenecer al tenant
Estado	El producto debe estar en estado `ACTIVO`
Tipo	El producto debe ser tipo `SERVICIO` (no PRODUCTO)
ILA	El producto NO debe tener impuesto adicional (ILA)
Visibilidad	El producto debe tener `visibleEnBhe: true`
Descuento	El `descuentoPorcentaje` no puede exceder el máximo configurado en el producto

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": [
      {
        "productoId": "clxyz123abc",
        "codigoSku": "SRV-00001",
        "descripcion": "Consultoría especializada",
        "cantidad": 3,
        "unidadMedida": "hora",
        "precioUnitario": 50000,
        "descuentoPorcentaje": 10,
        "descuentoMonto": 15000,
        "valor": "135000"
      },
      {
        "descripcion": "Desarrollo de software",
        "cantidad": 1,
        "unidadMedida": "unidad",
        "precioUnitario": 75000,
        "descuentoPorcentaje": 0,
        "descuentoMonto": 0,
        "valor": "75000"
      }
    ],
    "tipoRetencion": "RETRECEPTOR",
    "montoBruto": 210000,
    "ppm": 28875,
    "montoLiquido": 181125,
    "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}
Authorization: Bearer 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)

Borradores y Autorizaciones

Cuando un producto tiene un descuento máximo configurado y necesitas aplicar un descuento mayor, debes usar el flujo de borradores con autorización.

Diagrama de Decisión

¿Descuento excede el máximo del producto?
├── NO → Emitir directamente con POST /{tenantSlug}/bhe
└── SÍ → Flujo de autorización:
         1. Crear borrador
         2. Solicitar autorización
         3. (Esperar aprobación por supervisor)
         4. Emitir desde borrador autorizado

Endpoints de Borradores

Método	Endpoint	Descripción
`POST`	`/{tenantSlug}/bhe/borradores`	Crear borrador
`GET`	`/{tenantSlug}/bhe/borradores`	Listar borradores
`GET`	`/{tenantSlug}/bhe/borradores/{id}`	Detalle de borrador
`PATCH`	`/{tenantSlug}/bhe/borradores/{id}`	Actualizar borrador
`DELETE`	`/{tenantSlug}/bhe/borradores/{id}`	Eliminar borrador
`POST`	`/{tenantSlug}/bhe/borradores/{id}/solicitar-autorizacion`	Solicitar autorización
`POST`	`/{tenantSlug}/bhe/borradores/{id}/emitir`	Emitir desde borrador

Estados del Borrador

Estado	Descripción	Acciones Permitidas
`BORRADOR`	Editable, puede emitirse si no requiere autorización	Editar, eliminar, solicitar autorización, emitir
`EN_AUTORIZACION`	Esperando aprobación de supervisor	Solo lectura
`AUTORIZADO`	Aprobado, listo para emitir	Emitir
`RECHAZADO`	Rechazado por supervisor	Editar, eliminar
`EMITIDO`	Ya se emitió la BHE	Solo lectura

Crear Borrador con Autorización

Cuando una línea requiere autorización, incluye motivoAutorizacion:

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

{
  "emisorTributarioId": "cmitg28qt0009serjtjcrejci",
  "sinDestinatario": false,
  "destinatarioId": "12345678-9",
  "prestaciones": [
    {
      "productoId": "clxyz123abc",
      "cantidad": 2,
      "descuentoPorcentaje": 25,
      "motivoAutorizacion": "Cliente VIP con contrato anual"
    }
  ],
  "tipoRetencion": "RETRECEPTOR"
}

Response:

{
  "success": true,
  "data": {
    "id": "cm5borrador123",
    "estado": "BORRADOR",
    "requiereAutorizacion": true,
    "lineasConAutorizacion": [
      {
        "lineaIndex": 0,
        "productoId": "clxyz123abc",
        "descuentoSolicitado": 25,
        "descuentoMaximo": 15,
        "motivoAutorizacion": "Cliente VIP con contrato anual"
      }
    ],
    "montoBruto": 75000,
    "ppm": 10313,
    "montoLiquido": 64687,
    "createdAt": "2025-12-08T10:00:00Z"
  }
}

Solicitar Autorización

POST /{tenantSlug}/bhe/borradores/{id}/solicitar-autorizacion
Authorization: Bearer tu-api-key

Response:

{
  "success": true,
  "data": {
    "id": "cm5borrador123",
    "estado": "EN_AUTORIZACION",
    "solicitudAutorizacionId": "cm5auth456"
  },
  "message": "Solicitud de autorización enviada. Recibirás una notificación cuando sea procesada."
}

Emitir desde Borrador

Una vez autorizado:

POST /{tenantSlug}/bhe/borradores/{id}/emitir
Authorization: Bearer tu-api-key

Response:

{
  "success": true,
  "data": {
    "bheId": "cm5bhe789",
    "folioSii": "12345678",
    "estado": "EMITIDA",
    "mensaje": "BHE emitida exitosamente desde borrador"
  }
}

Clonar Boleta

Crea un nuevo borrador a partir de una BHE emitida o un borrador existente. Útil para emisiones recurrentes al mismo destinatario.

Clonar desde BHE Emitida

POST /{tenantSlug}/bhe/{id}/clonar
Authorization: Bearer tu-api-key

Response:

{
  "success": true,
  "data": {
    "borradorId": "cm5newborrador123",
    "mensaje": "Borrador creado desde BHE"
  }
}

Clonar desde Borrador

POST /{tenantSlug}/bhe/borradores/{id}/clonar
Authorization: Bearer tu-api-key

Response:

{
  "success": true,
  "data": {
    "borradorId": "cm5newborrador456",
    "mensaje": "Borrador clonado exitosamente"
  }
}

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
Authorization: Bearer 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
Authorization: Bearer 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
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
`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}
Authorization: Bearer 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
Authorization: Bearer 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
Authorization: Bearer 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
Authorization: Bearer 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

Boletas de Honorarios

Boletas de Honorarios Electrónicas (BHE)

Requisitos Previos

Modos de Emisión

Flujo SINC_PARCIAL (Default)

Flujo ASINCRONO

Modos de Destinatario

Diagrama de Decisión

Modo 1: destinatarioId (Contribuyente Guardado)

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

Modo 3: siiLookup (Objeto Lookup Completo)

Modo 4: lookupRut (Ejecutar Lookup)

Emitir Boleta

Request Completo

Fecha de Emisión Personalizada

Formato

Restricciones

Comportamiento en PDFs

Emisión con Productos del Catálogo

Modo 1: Items Libres (Sin Catálogo)

Modo 2: Productos del Catálogo

Validaciones del Catálogo

Response: Modo Síncrono (SINC_COMPLETO / SINC_PARCIAL)

Response: Modo ASINCRONO

Consultar Estado Asíncrono

Response

Borradores y Autorizaciones

Diagrama de Decisión

Endpoints de Borradores

Estados del Borrador

Crear Borrador con Autorización

Solicitar Autorización

Emitir desde Borrador

Clonar Boleta

Clonar desde BHE Emitida

Clonar desde Borrador

Gestión de PDFs

Estados del PDF SII

Descargar PDF

Generar PDF con Template Específico

Reintentar Descarga PDF SII

Listar Archivos PDF

Listar y Consultar

Listar Boletas

Obtener Detalle

Enviar por Email

Enviar Boleta al Destinatario

Enviar Archivo Específico a Email Arbitrario

Webhooks

Payload: bhe.emitida

Payload: bhe.emision_terminada

Payload: bhe.pdf_sii_fallido

Payload: bhe.emision_fallida

Cálculo de Montos

Códigos de Error

Errores de Validación (400)

Errores del SII (No Reintentables)

Errores de Recurso (404)

Estados de la Boleta

Testing (Sandbox)

RUTs de Prueba

API Reference

Modo 1: `destinatarioId` (Contribuyente Guardado)

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

Modo 3: `siiLookup` (Objeto Lookup Completo)

Modo 4: `lookupRut` (Ejecutar Lookup)

Payload: `bhe.emitida`

Payload: `bhe.emision_terminada`

Payload: `bhe.pdf_sii_fallido`

Payload: `bhe.emision_fallida`