Boletas de Terceros

Boletas de Honorarios de Terceros (BHET)

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 variable (13.75%)	Fija 14.5%
Sin receptor	`sinDestinatario` soportado	Siempre requiere tercero
Campo monto	`montoLiquido`	`montoNeto`
Campo impuesto	`ppm`	`impuesto`

Requisitos Previos

Antes de emitir una BHET necesitas:

Un Emisor Tributario activo con clave tributaria delegada y servicio BOLETAS_TERCEROS habilitado
Una API Key con uno de estos roles: ADMIN, SUPER-ADMIN, SII-EMISOR-BHET, o FULL-API
Los datos del tercero (siempre requerido, no existe opción sin tercero)

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 por hasta 7 horas si el SII falla
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í

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": "cmitg28qt0009serjtjcrejci",
  "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": "cmitg28qt0009serjtjcrejci",
  "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": "cmitg28qt0009serjtjcrejci",
  "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" }
  ]
}

Modo 4: `lookupRut` (Ejecutar Lookup)

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

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

Emitir Boleta

Request Completo

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

{
  "emisorTributarioId": "cmitg28qt0009serjtjcrejci",
  "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
`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",
  "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`

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

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

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": "76123456-7",
      "razonSocial": "EMPRESA CONTRATANTE SPA"
    },
    "tercero": {
      "rut": "78012039-8",
      "nombre": "FIRERAISE SPA",
      "domicilio": "AV PROVIDENCIA 1234 OF 501",
      "codigoRegion": "13",
      "codigoComuna": "13101",
      "descComuna": "SANTIAGO"
    },
    "prestaciones": [
      {
        "descripcion": "Servicio de consultoría en sistemas",
        "cantidad": 1,
        "unidadMedida": "servicio",
        "precioUnitario": 150000,
        "valor": "150000"
      }
    ],
    "montoBruto": 225000,
    "tasaImpuesto": 14.5,
    "impuesto": 32625,
    "montoNeto": 192375,
    "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,
  "data": {
    "modo": "ASINCRONO",
    "intentoId": "cm5xyz789abc123",
    "estado": "PENDIENTE",
    "correlationId": "mi-referencia-123"
  }
}

Consultar Estado Asíncrono

Para el modo ASINCRONO, consulta el estado del intento:

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

Response

{
  "id": "cm5xyz789abc123",
  "estado": "EMITIDA",
  "bhet": {
    "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 BHET 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}/bhet
└── 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}/bhet/borradores`	Crear borrador
`GET`	`/{tenantSlug}/bhet/borradores`	Listar borradores
`GET`	`/{tenantSlug}/bhet/borradores/{id}`	Detalle de borrador
`PATCH`	`/{tenantSlug}/bhet/borradores/{id}`	Actualizar borrador
`DELETE`	`/{tenantSlug}/bhet/borradores/{id}`	Eliminar borrador
`POST`	`/{tenantSlug}/bhet/borradores/{id}/solicitar-autorizacion`	Solicitar autorización
`POST`	`/{tenantSlug}/bhet/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 BHET	Solo lectura

Clonar Boleta

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

Clonar desde BHET Emitida

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

Response:

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

Clonar desde Borrador

POST /{tenantSlug}/bhet/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 o sandbox
`PENDIENTE`	En cola para descarga
`DISPONIBLE`	Descargado exitosamente
`FALLIDO`	Agotó reintentos después de 7 días

Listar Archivos PDF

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

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

Enviar por Email

Enviar Archivo Específico

POST /{tenantSlug}/bhet/{id}/archivos/{archivoId}/enviar-email
Content-Type: application/json
Authorization: Bearer tu-api-key

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

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_fallida`	Emisión asíncrona falló	Después de ~7 horas de reintentos (modo ASINCRONO)

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": 225000,
    "impuesto": 32625,
    "neto": 192375
  },
  "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 × 14.5%
Monto Neto = Monto Bruto - Impuesto

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 (No Reintentables)

Código	Descripción
`SII_AUTH_FAILED`	Credenciales incorrectas (RUT/clave tributaria)
`SII_RUT_INVALIDO`	RUT del emisor o tercero no válido
`SII_DATOS_INVALIDOS`	Datos de la boleta incorrectos

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

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": "cmitg28qt0009serjtjcrejci",
  "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

Boletas de Terceros

Boletas de Honorarios de Terceros (BHET)

Diferencias con BHE

Requisitos Previos

Modos de Emisión

Flujo SINC_PARCIAL (Default)

Flujo ASINCRONO

Modos de Tercero

Diagrama de Decisión

Modo 1: terceroId (Contribuyente Guardado)

Modo 2: tercero (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

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

Clonar Boleta

Clonar desde BHET Emitida

Clonar desde Borrador

Gestión de PDFs

Estados del PDF SII

Listar Archivos PDF

Listar y Consultar

Listar Boletas

Obtener Detalle

Enviar por Email

Enviar Archivo Específico

Webhooks

Payload: bhet.emitida

Cálculo de Montos

Códigos de Error

Errores de Validación (400)

Errores del SII (No Reintentables)

Estados de la Boleta

Testing (Sandbox)

RUTs de Prueba (Tercero)

API Reference

Modo 1: `terceroId` (Contribuyente Guardado)

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

Modo 3: `siiLookup` (Objeto Lookup Completo)

Modo 4: `lookupRut` (Ejecutar Lookup)

Payload: `bhet.emitida`