Boletas de honorarios electrónicas (BHE)
Qué resuelve
Sección titulada «Qué resuelve»Emitir ante el SII una boleta de honorarios electrónica desde tu sistema, en vez de hacerla a mano en el sitio del SII, y guardar su folio y su PDF. La emite una persona natural por servicios que ella presta. Si quien emite es una empresa que contrata y paga a un tercero, la ficha es Boletas de honorarios de terceros.
Esta ficha te lleva desde una carpeta sin conexión hasta una boleta de prueba verificada, y deja dicho qué cambia para emitir la primera en 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. El emisor es la persona natural que presta el servicio y se inscribe con su clave tributaria del SII (no con certificado digital). En el modo de prueba tu empresa ya tiene uno, el RUT
11111111-1, que emite sin clave del SII y sin tener contratado el servicio. Cómo se inscribe un emisor, cuándo hay varios y qué hacer si el SII rechaza su clave: Emisores y tokenización. - Una llave con permiso de emisión de boletas. Las operaciones de esta ficha piden el rol
FULL-API, que es el de la llave del proyecto. - Modo de prueba. Cada llave sólo ve los emisores y las boletas de su modo: con la llave de prueba no se puede emitir con un emisor de producción. Lo que cambia entre los dos modos está en Modo de prueba y producción.
- Reglas que valen para todas las operaciones (paginación, forma de los errores, límites): Reglas comunes.
-
Obtén el identificador del emisor de prueba. Comando:
Ventana de terminal redcumbre escenarios --jsonResultado esperado: sale con código 0 y un JSON con
emisoresTributarios, una lista de{ id, servicio, rut }. Toma elidde la entrada conservicio: "BHE"yrut: "11111111-1": es tuemisorTributarioIdde prueba. El mismo JSON trae la lista de RUT de prueba y qué provoca cada uno. SiemisoresTributariosviene vacía, la llave no es de prueba:redcumbre estadodice el modo de cada llave. -
Arma el cuerpo de la boleta. Guarda este JSON como
boleta-prueba.jsony cambiatu-emisor-tributario-idpor eliddel paso 1. El destinatario22222222-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, ver más abajo).{"emisorTributarioId": "tu-emisor-tributario-id","sinDestinatario": false,"lookupRut": "22222222-2","prestaciones": [{ "descripcion": "Servicio de prueba", "valor": "100000" }],"tipoRetencion": "RETRECEPTOR","modo": "SINC_PARCIAL","idempotencyKey": "boleta-prueba-001","correlationId": "mi-referencia-001"}valorva como texto, en pesos.prestacionesadmite de 1 a 4 ítems.idempotencyKeyhace que un reintento devuelva la misma boleta en vez de emitir otra: cómo funciona y qué hacer ante un resultado incierto está en Emisión. -
Emite la boleta de prueba. Comando:
Ventana de terminal redcumbre api emitirBoletaHonorarios --cuerpo @boleta-prueba.json --jsonResultado esperado: código de salida 0 y respuesta
201. Nada llega al SII: la respuesta traecobro.modo: "prueba"ysandbox: true. La boleta está endata.bhe, no en la raíz dedata:{"success": true,"data": {"modo": "SINC_PARCIAL","bhe": {"id": "cm5abc123def456","folioSii": "SANDBOX-1790796065137","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." }}Se acorta la respuesta: trae además los enlaces de descarga y los montos (
montoBruto,montoLiquido). Guardadata.bhe.idydata.bhe.folioSii. Los modosSINC_COMPLETOyASINCRONOresponden con otra forma (enASINCRONOviene unintentoId): ver Emisión. -
Comprueba la boleta en el servidor. Comando:
Ventana de terminal redcumbre api obtenerBoletaHonorarios --param id=<data.bhe.id> --jsonResultado esperado:
200con la boleta completa endata, conestado: "EMITIDA", el mismofolioSii, el emisor11111111-1y el desglose de montos (montoBruto,ppm,montoLiquido). Si emitiste en modoASINCRONO, consulta antes el intento:redcumbre api consultarIntentoEmisionBoletaHonorarios --param intentoId=<intentoId> --jsonhasta quedata.estadoseaEMITIDA(REINTENTANDOno es un desenlace: espera, no reemitas; sóloFALLIDAlo es). -
Guarda el PDF. Comando:
Ventana de terminal redcumbre api descargarPdfInternoBoletaHonorarios --param id=<data.bhe.id> --salida boleta.pdfResultado esperado: el CLI imprime
Guardé N bytes en …/boleta.pdfy el archivo es un PDF con la marca «DOCUMENTO DE PRUEBA — SIN VALIDEZ TRIBUTARIA» en cada página. En prueba no existe el respaldo del SII: pedirdescargarPdfSiiBoletaHonorariosresponde404yestadoPdfSiiquedaNO_APLICA. En producción el respaldo llega después de emitir, avisado porbhe.emision_terminada. Dónde guardar el archivo y cuál de los dos usar: Documentos y PDF. -
Recibe los avisos de la emisión. Los eventos de la boleta salen al endpoint de webhooks de prueba que hayas configurado; si no hay uno, no llegan a ningún lado (no se desvían al de producción). Para ensayar tu receptor sin emitir otra boleta:
Ventana de terminal redcumbre webhooks escuchar --reenviar-a http://localhost:3000/webhooks --eventos bhe.emitida,bhe.anuladaredcumbre eventos disparar bhe.emitidaResultado esperado: tu servidor recibe un POST firmado con
event: "bhe.emitida"ybheId,folioSiiysandbox: true. El secreto de prueba con que tu receptor valida la firma lo imprime ese mismo comando: no hace falta el panel.bhe.emision_terminadano se dispara en prueba (en producción sale cuando el PDF del SII está listo; en prueba no hay PDF del SII): no lo esperes en este paso. Cómo validar la firma, qué eventos hay y cómo reintenta el servidor: Webhooks. Para comprobar que tu sitio valida la firma y no repite el efecto de una entrega duplicada:redcumbre prueba verificar --reenviar-a http://localhost:3000/webhooks --eventos bhe.emitida,bhe.anulada --efectos "<tu comando>". -
Anula la boleta de prueba. La anulación es asíncrona: responde
202y el desenlace llega por webhook o consultándola. Guarda el cuerpo comoanular-prueba.json:{"causaSii": "3","motivoInterno": "Prueba de anulación","correlationId": "mi-anulacion-001","enviarComprobante": false}causaSiies obligatorio:"1"no pago de honorarios,"2"prestación no realizada,"3"error de digitación.motivoInternoes sólo tuyo y nunca va al SII. Comando:Ventana de terminal redcumbre api anularBoletaHonorarios --param id=<data.bhe.id> --cuerpo @anular-prueba.json --jsonResultado esperado:
202con unanulacionIdyestado: "PENDIENTE".{"anulacionId": "cmp7x2k9a0001jw0h4nqz8bcd","estado": "PENDIENTE","folioSii": "SANDBOX-1790796065137","tipoBoleta": "BHE","mensaje": "Solicitud de anulación registrada. El resultado llegará en unos segundos.","sandbox": true,"cobro": { "modo": "prueba", "mensaje": "En modo de prueba no se cobra." }}Un
202sólo dice que la solicitud quedó encolada, no que el SII haya anulado. Consulta hasta un estado terminal:Ventana de terminal redcumbre api consultarAnulacionBoletaHonorarios --param anulacionId=<anulacionId> --jsonResultado esperado:
estado: "ANULADA"(en prueba se resuelve en segundos) y el eventobhe.anulada. Para programar contra el rechazo del SII, lleva esa anulación aNO_ANULABLE, que sólo existe en prueba:redcumbre api simularNoAnulableAnulacionBoletaHonorarios --param anulacionId=<anulacionId> --json(quedaNO_ANULABLE, la boleta vuelve aEMITIDAy salebhe.anulacion_fallida). Después se puede reintentar conreintentarAnulacionBoletaHonorarios. Una boleta emitida directamente en el sitio del SII se anula conanularBoletaHonorariosExterna, 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 tú enviaste:
obtenerBoletaHonorariosrespondeestado: "EMITIDA"con unfolioSiique empieza conSANDBOX-.- El PDF descargado abre y lleva la marca de prueba.
- Tu receptor recibió
bhe.emitidaconsandbox: truey firma válida (redcumbre prueba verificarsale con 0).
No decidas leyendo mensaje: es texto para mostrar. Ramifica con data.modo, data.bhe.estado y data.bhe.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 |
|---|---|---|
422 con errorCode SII_CREDENCIAL_INVALIDA o EMISOR_CREDENCIAL_INVALIDA | La clave tributaria del emisor fue rechazada o ya estaba marcada como inválida; la emisión está detenida | No reintentes. La persona actualiza su clave: Emisores y tokenización. Llega bhe.credencial_rechazada, y bhe.credencial_restablecida cuando vuelve a funcionar |
422 con SII_RUT_INVALIDO | El SII rechazó el RUT del emisor o del destinatario. En prueba lo provoca el destinatario 44444444-4 | Corrige el RUT. La boleta queda en ERROR y se consulta con el boletaId del error |
422 con SII_PERSONA_JURIDICA, SII_SIN_INICIO_ACTIVIDADES, SII_SIN_SEGUNDA_CATEGORIA o SII_NO_HABILITADO | El emisor no puede emitir honorarios ante el SII (una BHE sólo la emite una persona natural con actividades de segunda categoría) | No reintentes. La persona lo resuelve en el SII, o usa boletas de terceros si es una empresa quien emite |
422 con SII_DATOS_INVALIDOS o SII_FORM_ERROR | El SII no aceptó los datos de la boleta | Corrige el cuerpo y reintenta con la misma idempotencyKey (una emisión fallida no reserva la clave) |
400 con MULTIPLE_DESTINATARIO_MODES o DESTINATARIO_REQUIRED | Mandaste más de un modo de destinatario, o ninguno | Envía exactamente uno de destinatarioId, destinatario, siiLookup o lookupRut, o sinDestinatario: true |
400 con RETENCION_INVALIDA_SIN_DESTINATARIO | tipoRetencion: "RETRECEPTOR" junto con sinDestinatario: true | Sin destinatario, usa RETCONTRIBUYENTE |
400 con SII_LOOKUP_FAILED o CONTRIBUYENTE_NOT_FOUND | La consulta del destinatario falló o el RUT no está guardado. En prueba, 99999999-9 responde «no encontrado» | Usa otro modo de destinatario o corrige el RUT |
400 con MODO_PRUEBA_TOPE_DIARIO | Superaste las 200 boletas de prueba del día (contadas aparte de las de terceros) | Espera hasta las 00:00 de Chile. redcumbre estado dice cuánto queda |
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 si existe. La clave de idempotencia queda reservada; si no salió, usa una clave nueva. Ver Emisión |
503 con SII_EMISOR_BUSY | El emisor tiene demasiadas emisiones en curso | Espera los segundos de la cabecera 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 BHE_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 a soporte |
404 al pedir el PDF del SII | Aún no existe (PENDIENTE), falló (FALLIDO, avisado por bhe.pdf_sii_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, o el emisor está inactivo o sin credenciales | Corrige el estado y repite. Un folio de prueba con llave de producción responde FOLIO_SANDBOX_EN_PRODUCCION |
409 al anular | Ya hay una anulación en curso o terminada para esa boleta | Consulta la anulación que ya existe; no se crea otra |
Anulación en NO_ANULABLE | El SII no deja anular (plazo vencido, folio inexistente, receptor extranjero) | La anulación electrónica ya no es posible; el trámite es presencial en el SII. Se puede reintentar con reintentarAnulacionBoletaHonorarios. El SII no publica el plazo de una BHE: asume que cualquier anulación puede terminar así |
Anulación en FALLIDA_DEFINITIVA | Se agotaron los reintentos por una caída (el SII no rechazó nada) | Reintenta con reintentarAnulacionBoletaHonorarios |
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 emitirBoletaHonorarios --produccion. No existe una «boleta de prueba» en producción: la primera emisión ya es una boleta de producción.
-
Emisor de producción. La persona que emite inscribe su clave tributaria del SII por tokenización: es ella quien autoriza en el SII, tú no ves su clave ni la pides. Su
emisorTributarioIdde producción es distinto al de prueba; léelo conredcumbre emisores tributarios listar --produccion --jsony guárdalo, porque va en el cuerpo de cada emisión. Los comandos de la tokenización, el caso de varios profesionales y el de una clave que el SII deja de aceptar están en Emisores y tokenización. -
Servicio contratado. El servicio de boletas de honorarios (
SII_BHE) tiene que estar activo en la empresa.redcumbre pasar-a-produccion --servicios bherevisa que todo esté en orden, dice qué falta y dónde configurarlo, y recién entonces crea la llave de producción (la 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. Configura el endpoint de producción y su secreto de firma, que son otros que los de prueba. Tu receptor tiene que deduplicar: una repetición de la misma
idempotencyKeyvuelve a dispararbhe.emitida. Ver Webhooks. -
Precio. Lo que cuesta emitir y anular depende de tu plan:
redcumbre tarifas emitirBoletaHonorarios --produccionyredcumbre tarifas anularBoletaHonorarios --produccion.lookupRutagrega la consulta al SII del destinatario: si ya tienes sus datos, usadestinatariocompleto,destinatarioIdosiiLookupy 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 emitirBoletaHonorarios --produccion --confirmar <identificador-de-la-empresa> --cuerpo @boleta.json --jsonResultado esperado:
201concobro.modo: "produccion", un folio de producción del SII (sin el prefijoSANDBOX-) ysandbox: false. El PDF del SII llega después y se avisa conbhe.emision_terminada. Más sobre qué cambia entre modos: Modo de prueba y producción.