Ir al contenido

Boletas de honorarios de terceros (BHET)

Emitir ante el SII una boleta de honorarios de terceros: el documento que emite una empresa cuando contrata y paga un servicio a un tercero (persona natural o jurídica) que no le entrega boleta propia. Se hace desde tu sistema, y guardas el folio y el PDF.

Es el espejo de las boletas de honorarios, con tres diferencias que importan:

  • Quien emite es la empresa que paga, no quien presta el servicio. El receptor del documento es el tercero, y siempre hay uno: no existe sinDestinatario.
  • La retención es una sola: la tasa la fija la plataforma. No hay tipoRetencion; la tasa vigente se consulta con consultarTasaRetencionBoletaTerceros.
  • Los montos se llaman distinto: impuesto y montoNeto, en vez de ppm y montoLiquido.

Esta ficha te lleva hasta una boleta de prueba verificada y deja dicho qué cambia para la primera de producción.

  • Una llave de prueba conectada al proyecto. Si keys/redcumbre-prueba.json no existe, parte por el arranque o corre redcumbre init.
  • Un emisor tributario de la empresa que paga. Lo habitual es un solo RUT, el de la empresa; algunas emiten desde más de uno, y cada uno se inscribe aparte con su clave tributaria del SII (no certificado digital). En el modo de prueba tu empresa ya tiene el emisor 88888888-8 (persona jurídica), que emite sin clave del SII y sin tener contratado el servicio. Cómo se inscribe un emisor y qué hacer si el SII rechaza su clave: Emisores y tokenización.
  • Rol FULL-API, que es el de la llave del proyecto.
  • Cada llave sólo ve los emisores y boletas de su modo. Diferencias entre modos: Modo de prueba y producción. Paginación, forma de los errores y límites: Reglas comunes.
  1. Obtén el identificador del emisor de prueba. Comando:

    Ventana de terminal
    redcumbre escenarios --json

    Resultado esperado: código de salida 0 y un JSON con emisoresTributarios, una lista de { id, servicio, rut }. Toma el id de la entrada con servicio: "BHET" y rut: "88888888-8": es tu emisorTributarioId de prueba. No uses la entrada BHE: es el emisor de las boletas de honorarios propias.

  2. Arma el cuerpo. Guárdalo como bhet-prueba.json y cambia tu-emisor-tributario-id por el id del paso 1. El tercero 22222222-2 es un RUT de prueba que siempre se emite bien; lookupRut hace que la plataforma consulte sus datos (en producción esa consulta va al SII).

    {
    "emisorTributarioId": "tu-emisor-tributario-id",
    "lookupRut": "22222222-2",
    "prestaciones": [
    { "descripcion": "Servicio de prueba", "valor": "100000" }
    ],
    "modo": "SINC_PARCIAL",
    "idempotencyKey": "bhet-prueba-001",
    "correlationId": "mi-referencia-001"
    }

    El tercero se indica con uno solo de estos campos: terceroId (uno ya guardado), tercero (datos completos: rut, nombres, domicilio, y el código de comuna), siiLookup (el resultado de una consulta de RUT que ya hiciste) o lookupRut (sólo el RUT). valor va como texto, en pesos; prestaciones admite de 1 a 4 ítems. La idempotencyKey evita emitir dos veces en un reintento: ver Emisión.

  3. Emite la boleta de prueba. Comando:

    Ventana de terminal
    redcumbre api emitirBoletaTerceros --cuerpo @bhet-prueba.json --json

    Resultado esperado: código de salida 0 y respuesta 201. No llega nada al SII: la respuesta trae cobro.modo: "prueba" y sandbox: true. La boleta está en data.bhet, no en la raíz de data:

    {
    "success": true,
    "data": {
    "modo": "SINC_PARCIAL",
    "bhet": {
    "id": "cm5abc123def456",
    "folioSii": "SBX1790790355066-vpc6vlsv",
    "estado": "EMITIDA",
    "estadoPdfSii": "NO_APLICA",
    "modoEmision": "SINC_PARCIAL"
    },
    "correlationId": "mi-referencia-001"
    },
    "sandbox": true,
    "cobro": { "modo": "prueba", "mensaje": "En modo de prueba no se cobra." }
    }

    La respuesta real es más larga (enlaces de descarga, montoBruto, tasaImpuesto, impuesto, montoNeto). Guarda data.bhet.id y data.bhet.folioSii. Los modos SINC_COMPLETO y ASINCRONO responden con otra forma (en ASINCRONO, un intentoId): ver Emisión.

  4. Comprueba la boleta en el servidor. Comando:

    Ventana de terminal
    redcumbre api obtenerBoletaTerceros --param id=<data.bhet.id> --json

    Resultado esperado: 200 con la boleta completa en data: estado: "EMITIDA", el mismo folioSii, el emisor 88888888-8 y el tercero. En modo ASINCRONO, consulta antes redcumbre api consultarIntentoEmisionBoletaTerceros --param intentoId=<intentoId> --json hasta EMITIDA (REINTENTANDO no es un desenlace: espera, no reemitas; sólo FALLIDA lo es).

  5. Guarda el PDF. Comando:

    Ventana de terminal
    redcumbre api descargarPdfInternoBoletaTerceros --param id=<data.bhet.id> --salida bhet.pdf

    Resultado esperado: el CLI imprime Guardé N bytes en …/bhet.pdf y el archivo es un PDF con la marca «DOCUMENTO DE PRUEBA — SIN VALIDEZ TRIBUTARIA». En prueba no hay respaldo del SII: descargarPdfSiiBoletaTerceros responde 404 y estadoPdfSii queda NO_APLICA. En producción el respaldo llega después y se avisa con bhet.emision_terminada. Cuál usar y dónde guardarlo: Documentos y PDF.

  6. Recibe los avisos. Los eventos de la boleta salen al endpoint de webhooks de prueba de tu empresa; si no hay uno, no llegan (no se desvían al de producción). Para ensayar tu receptor:

    Ventana de terminal
    redcumbre webhooks escuchar --reenviar-a http://localhost:3000/webhooks --eventos bhet.emitida,bhet.anulada
    redcumbre eventos disparar bhet.emitida

    Resultado esperado: tu servidor recibe un POST firmado con event: "bhet.emitida", bhetId, folioSii y sandbox: true. El secreto de prueba con que tu receptor valida la firma lo imprime ese mismo comando: no hace falta el panel. bhet.emision_terminada no se dispara en prueba (en producción sale cuando el PDF está listo; en prueba no hay PDF del SII): no lo esperes en este paso. Firma, lista de eventos y reintentos: Webhooks. Para comprobar que tu sitio valida la firma y no repite el efecto ante una entrega duplicada: redcumbre prueba verificar --reenviar-a http://localhost:3000/webhooks --eventos bhet.emitida,bhet.anulada --efectos "<tu comando>".

  7. Anula la boleta de prueba. La anulación es asíncrona (202, y el desenlace llega por webhook o consultándola). Guarda el cuerpo como anular-bhet.json:

    {
    "causaSii": "3",
    "motivoInterno": "Prueba de anulación",
    "correlationId": "mi-anulacion-001",
    "enviarComprobante": false
    }

    causaSii es obligatorio: "1" no pago, "2" prestación de servicios no realizada, "3" error de digitación. Comandos:

    Ventana de terminal
    redcumbre api anularBoletaTerceros --param id=<data.bhet.id> --cuerpo @anular-bhet.json --json
    redcumbre api consultarAnulacionBoletaTerceros --param anulacionId=<anulacionId> --json

    Resultado esperado: el primero responde 202 con anulacionId y estado: "PENDIENTE"; el segundo, en segundos, estado: "ANULADA", y llega bhet.anulada. Un 202 sólo dice que la solicitud quedó encolada. Para programar contra el rechazo del SII, redcumbre api simularNoAnulableAnulacionBoletaTerceros --param anulacionId=<anulacionId> --json lleva esa anulación a NO_ANULABLE (sólo existe en prueba; sale bhet.anulacion_fallida), y desde ahí se puede reintentar con reintentarAnulacionBoletaTerceros. Una boleta emitida directamente en el sitio del SII se anula con anularBoletaTercerosExterna, que recibe folioSii y emisorTributarioId en vez del id.

Una boleta de prueba está verificada cuando se cumplen las tres cosas, leídas del servidor y no de lo que enviaste:

  1. obtenerBoletaTerceros responde estado: "EMITIDA" con un folioSii de prueba (empieza con SBX).
  2. El PDF descargado abre y lleva la marca de prueba.
  3. Tu receptor recibió bhet.emitida con sandbox: true y firma válida (redcumbre prueba verificar sale con 0).

No decidas leyendo mensaje: es texto para mostrar. Ramifica con data.modo, data.bhet.estado y data.bhet.estadoPdfSii. En producción, una respuesta 2xx significa que la boleta se emitió: un rechazo del SII llega siempre como error HTTP.

Si vesSignificaQué haces
400 con EMISOR_NO_HABILITADOEl emisor no tiene el servicio de boletas de terceros habilitadoEn producción, contratar el servicio; en prueba no debería ocurrir: revisa que usas el emisor 88888888-8 y no otro
400 con MULTIPLE_TERCERO_MODES o TERCERO_REQUIREDMandaste más de un modo de tercero, o ningunoEnvía exactamente uno de terceroId, tercero, siiLookup o lookupRut
400 con SII_LOOKUP_FAILED o CONTRIBUYENTE_NOT_FOUNDLa consulta del tercero falló o el RUT no está guardado. En prueba, 99999999-9 responde «no encontrado»Usa otro modo de tercero o corrige el RUT
400 con MODO_PRUEBA_TOPE_DIARIOSuperaste las 200 boletas de prueba del día (contadas aparte de las de honorarios propios)Espera hasta las 00:00 de Chile. redcumbre estado dice cuánto queda
422 con SII_TERCERO_INVALIDOEl tercero no es válido para recibir una boleta de terceros. En prueba lo provoca 44444444-4Corrige el tercero. La boleta queda en ERROR y se consulta con el boletaId del error
422 con SII_RUT_INVALIDO, SII_DATOS_INVALIDOS, SII_FORM_ERROR o SII_NO_HABILITADOEl SII rechazó el RUT, los datos o la habilitación del emisorNo reintentes sin corregir; luego reenvía con la misma idempotencyKey (una emisión fallida no la reserva)
422 con SII_CREDENCIAL_INVALIDA o EMISOR_CREDENCIAL_INVALIDALa clave tributaria del emisor fue rechazada; la emisión está detenidaNo reintentes. Actualiza la credencial: Emisores y tokenización. Llegan bhet.credencial_rechazada y, al corregirse, bhet.credencial_restablecida
502El SII respondió algo inutilizable (SII_AUTH_FAILED, SII_SERVICIO_NO_DISPONIBLE, …)Reintenta con espera creciente y la misma idempotencyKey
502 con SII_CONFIRMACION_INCIERTAEl SII no respondió al paso que emite: no se sabe si la boleta salióNo reintentes sin verificar en el SII. La clave queda reservada; si no salió, usa una nueva. Ver Emisión
503 con SII_EMISOR_BUSYEl emisor tiene demasiadas emisiones en cursoEspera los segundos de Retry-After y reintenta
503 con API_KEY_VERIFICATION_UNAVAILABLENo se pudo verificar la llave, que no fue rechazadaReintenta tras Retry-After. No la rotes
500 con BHET_EMITIDA_NO_PERSISTIDALa boleta sí se emitió ante el SII y la plataforma no pudo guardarlaNo reintentes: emitirías una segunda boleta. Informa el folioSii (viene en la respuesta, junto al codigoBarras) a soporte
404 al pedir el PDF del SIIAún no existe (PENDIENTE), falló (FALLIDO) o no aplica (NO_APLICA, siempre en prueba)Mira error.estadoPdfSii; mientras tanto usa el PDF interno
400 al anularLa boleta no tiene folio, no está EMITIDA, el emisor no tiene credenciales, o está fuera de los límites de anulaciónUna BHET sólo se anula electrónicamente dentro de 10 días corridos desde la emisión y hasta $1.000.000 de monto neto; fuera de eso la responde 400 sin consultar al SII y el trámite es presencial (Formulario 2117 en una oficina del SII)
409 al anularYa hay una anulación en curso o terminada para esa boletaConsulta la que ya existe; no se crea otra
Anulación en NO_ANULABLEEl SII no deja anularEl trámite es presencial. Se puede reintentar con reintentarAnulacionBoletaTerceros
Anulación en FALLIDA_DEFINITIVASe agotaron los reintentos por una caída (el SII no rechazó nada)Reintenta con reintentarAnulacionBoletaTerceros

Lo emitido en producción vale ante el SII, consume un folio; una boleta no se puede deshacer, sólo anular. Lo que cuesta depende de tu plan: redcumbre tarifas emitirBoletaTerceros --produccion. En producción no existe una «boleta de prueba»: la primera emisión ya es una boleta de producción.

  1. Emisor de producción. La empresa que paga inscribe su clave tributaria del SII por tokenización; la autoriza quien tiene esa clave, tú no la ves ni la pides. Su emisorTributarioId de producción es distinto al de prueba: léelo con redcumbre emisores tributarios listar --produccion --json. Los comandos de la tokenización y el caso de una empresa que emite desde más de un RUT: Emisores y tokenización.

  2. Servicio contratado. El servicio de boletas de terceros (SII_BHET) tiene que estar activo en la empresa. redcumbre pasar-a-produccion --servicios bhet revisa que todo esté en orden, dice qué falta y dónde configurarlo, y recién entonces crea la llave de producción, que confirma una persona escribiendo el identificador de la empresa. Esa llave nunca se muestra ni se pega en el chat o el repositorio: queda en keys/redcumbre-produccion.json.

  3. Webhooks de producción. Endpoint y secreto de firma de producción, distintos de los de prueba. Tu receptor tiene que deduplicar: repetir la misma idempotencyKey vuelve a disparar bhet.emitida. Ver Webhooks.

  4. Precio. Lo que cuesta emitir y anular depende de tu plan: redcumbre tarifas emitirBoletaTerceros --produccion y redcumbre tarifas anularBoletaTerceros --produccion. lookupRut suma la consulta al SII del tercero: si ya tienes sus datos usa tercero, terceroId o siiLookup y te ahorras esa consulta. redcumbre consumo --produccion muestra lo consumido y los topes.

  5. La primera emisión. Comando, con la confirmación explícita de producción:

    Ventana de terminal
    redcumbre api emitirBoletaTerceros --produccion --confirmar <identificador-de-la-empresa> --cuerpo @bhet.json --json

    Resultado esperado: 201 con cobro.modo: "produccion", un folio de producción del SII y sandbox: false. El respaldo del SII llega después y se avisa con bhet.emision_terminada. Más sobre qué cambia entre modos: Modo de prueba y producción.