Boletas de honorarios de terceros (BHET)
Qué resuelve
Sección titulada «Qué resuelve»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 conconsultarTasaRetencionBoletaTerceros. - Los montos se llaman distinto:
impuestoymontoNeto, en vez deppmymontoLiquido.
Esta ficha te lleva hasta una boleta de prueba verificada y deja dicho qué cambia para la primera de producción.
Qué necesitas antes
Sección titulada «Qué necesitas antes»- Una llave de prueba conectada al proyecto. Si
keys/redcumbre-prueba.jsonno existe, parte por el arranque o correredcumbre 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.
-
Obtén el identificador del emisor de prueba. Comando:
Ventana de terminal redcumbre escenarios --jsonResultado esperado: código de salida 0 y un JSON con
emisoresTributarios, una lista de{ id, servicio, rut }. Toma elidde la entrada conservicio: "BHET"yrut: "88888888-8": es tuemisorTributarioIdde prueba. No uses la entradaBHE: es el emisor de las boletas de honorarios propias. -
Arma el cuerpo. Guárdalo como
bhet-prueba.jsony cambiatu-emisor-tributario-idpor eliddel paso 1. El tercero22222222-2es un RUT de prueba que siempre se emite bien;lookupRuthace 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) olookupRut(sólo el RUT).valorva como texto, en pesos;prestacionesadmite de 1 a 4 ítems. LaidempotencyKeyevita emitir dos veces en un reintento: ver Emisión. -
Emite la boleta de prueba. Comando:
Ventana de terminal redcumbre api emitirBoletaTerceros --cuerpo @bhet-prueba.json --jsonResultado esperado: código de salida 0 y respuesta
201. No llega nada al SII: la respuesta traecobro.modo: "prueba"ysandbox: true. La boleta está endata.bhet, no en la raíz dedata:{"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). Guardadata.bhet.idydata.bhet.folioSii. Los modosSINC_COMPLETOyASINCRONOresponden con otra forma (enASINCRONO, unintentoId): ver Emisión. -
Comprueba la boleta en el servidor. Comando:
Ventana de terminal redcumbre api obtenerBoletaTerceros --param id=<data.bhet.id> --jsonResultado esperado:
200con la boleta completa endata:estado: "EMITIDA", el mismofolioSii, el emisor88888888-8y el tercero. En modoASINCRONO, consulta antesredcumbre api consultarIntentoEmisionBoletaTerceros --param intentoId=<intentoId> --jsonhastaEMITIDA(REINTENTANDOno es un desenlace: espera, no reemitas; sóloFALLIDAlo es). -
Guarda el PDF. Comando:
Ventana de terminal redcumbre api descargarPdfInternoBoletaTerceros --param id=<data.bhet.id> --salida bhet.pdfResultado esperado: el CLI imprime
Guardé N bytes en …/bhet.pdfy el archivo es un PDF con la marca «DOCUMENTO DE PRUEBA — SIN VALIDEZ TRIBUTARIA». En prueba no hay respaldo del SII:descargarPdfSiiBoletaTercerosresponde404yestadoPdfSiiquedaNO_APLICA. En producción el respaldo llega después y se avisa conbhet.emision_terminada. Cuál usar y dónde guardarlo: Documentos y PDF. -
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.anuladaredcumbre eventos disparar bhet.emitidaResultado esperado: tu servidor recibe un POST firmado con
event: "bhet.emitida",bhetId,folioSiiysandbox: true. El secreto de prueba con que tu receptor valida la firma lo imprime ese mismo comando: no hace falta el panel.bhet.emision_terminadano 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>". -
Anula la boleta de prueba. La anulación es asíncrona (
202, y el desenlace llega por webhook o consultándola). Guarda el cuerpo comoanular-bhet.json:{"causaSii": "3","motivoInterno": "Prueba de anulación","correlationId": "mi-anulacion-001","enviarComprobante": false}causaSiies 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 --jsonredcumbre api consultarAnulacionBoletaTerceros --param anulacionId=<anulacionId> --jsonResultado esperado: el primero responde
202conanulacionIdyestado: "PENDIENTE"; el segundo, en segundos,estado: "ANULADA", y llegabhet.anulada. Un202sólo dice que la solicitud quedó encolada. Para programar contra el rechazo del SII,redcumbre api simularNoAnulableAnulacionBoletaTerceros --param anulacionId=<anulacionId> --jsonlleva esa anulación aNO_ANULABLE(sólo existe en prueba; salebhet.anulacion_fallida), y desde ahí se puede reintentar conreintentarAnulacionBoletaTerceros. Una boleta emitida directamente en el sitio del SII se anula conanularBoletaTercerosExterna, que recibefolioSiiyemisorTributarioIden vez delid.
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»Una boleta de prueba está verificada cuando se cumplen las tres cosas, leídas del servidor y no de lo que enviaste:
obtenerBoletaTercerosrespondeestado: "EMITIDA"con unfolioSiide prueba (empieza conSBX).- El PDF descargado abre y lleva la marca de prueba.
- Tu receptor recibió
bhet.emitidaconsandbox: truey firma válida (redcumbre prueba verificarsale 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.
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
400 con EMISOR_NO_HABILITADO | El emisor no tiene el servicio de boletas de terceros habilitado | En 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_REQUIRED | Mandaste más de un modo de tercero, o ninguno | Envía exactamente uno de terceroId, tercero, siiLookup o lookupRut |
400 con SII_LOOKUP_FAILED o CONTRIBUYENTE_NOT_FOUND | La 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_DIARIO | Superaste 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_INVALIDO | El tercero no es válido para recibir una boleta de terceros. En prueba lo provoca 44444444-4 | Corrige 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_HABILITADO | El SII rechazó el RUT, los datos o la habilitación del emisor | No 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_INVALIDA | La clave tributaria del emisor fue rechazada; la emisión está detenida | No reintentes. Actualiza la credencial: Emisores y tokenización. Llegan bhet.credencial_rechazada y, al corregirse, bhet.credencial_restablecida |
502 | El SII respondió algo inutilizable (SII_AUTH_FAILED, SII_SERVICIO_NO_DISPONIBLE, …) | Reintenta con espera creciente y la misma idempotencyKey |
502 con SII_CONFIRMACION_INCIERTA | El 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_BUSY | El emisor tiene demasiadas emisiones en curso | Espera los segundos de Retry-After y reintenta |
503 con API_KEY_VERIFICATION_UNAVAILABLE | No se pudo verificar la llave, que no fue rechazada | Reintenta tras Retry-After. No la rotes |
500 con BHET_EMITIDA_NO_PERSISTIDA | La boleta sí se emitió ante el SII y la plataforma no pudo guardarla | No reintentes: emitirías una segunda boleta. Informa el folioSii (viene en la respuesta, junto al codigoBarras) a soporte |
404 al pedir el PDF del SII | Aú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 anular | La boleta no tiene folio, no está EMITIDA, el emisor no tiene credenciales, o está fuera de los límites de anulación | Una 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 anular | Ya hay una anulación en curso o terminada para esa boleta | Consulta la que ya existe; no se crea otra |
Anulación en NO_ANULABLE | El SII no deja anular | El trámite es presencial. Se puede reintentar con reintentarAnulacionBoletaTerceros |
Anulación en FALLIDA_DEFINITIVA | Se agotaron los reintentos por una caída (el SII no rechazó nada) | Reintenta con reintentarAnulacionBoletaTerceros |
Antes de pasar a producción
Sección titulada «Antes de pasar a producción»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.
-
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
emisorTributarioIdde producción es distinto al de prueba: léelo conredcumbre 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. -
Servicio contratado. El servicio de boletas de terceros (
SII_BHET) tiene que estar activo en la empresa.redcumbre pasar-a-produccion --servicios bhetrevisa 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 enkeys/redcumbre-produccion.json. -
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
idempotencyKeyvuelve a dispararbhet.emitida. Ver Webhooks. -
Precio. Lo que cuesta emitir y anular depende de tu plan:
redcumbre tarifas emitirBoletaTerceros --produccionyredcumbre tarifas anularBoletaTerceros --produccion.lookupRutsuma la consulta al SII del tercero: si ya tienes sus datos usatercero,terceroIdosiiLookupy te ahorras esa consulta.redcumbre consumo --produccionmuestra lo consumido y los topes. -
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 --jsonResultado esperado:
201concobro.modo: "produccion", un folio de producción del SII ysandbox: false. El respaldo del SII llega después y se avisa conbhet.emision_terminada. Más sobre qué cambia entre modos: Modo de prueba y producción.