Ir al contenido

Boletas de honorarios electrónicas (BHE)

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.

  • 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. 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.
  1. Obtén el identificador del emisor de prueba. Comando:

    Ventana de terminal
    redcumbre escenarios --json

    Resultado esperado: sale con código 0 y un JSON con emisoresTributarios, una lista de { id, servicio, rut }. Toma el id de la entrada con servicio: "BHE" y rut: "11111111-1": es tu emisorTributarioId de prueba. El mismo JSON trae la lista de RUT de prueba y qué provoca cada uno. Si emisoresTributarios viene vacía, la llave no es de prueba: redcumbre estado dice el modo de cada llave.

  2. Arma el cuerpo de la boleta. Guarda este JSON como boleta-prueba.json y cambia tu-emisor-tributario-id por el id del paso 1. El destinatario 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, 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"
    }

    valor va como texto, en pesos. prestaciones admite de 1 a 4 ítems. idempotencyKey hace 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.

  3. Emite la boleta de prueba. Comando:

    Ventana de terminal
    redcumbre api emitirBoletaHonorarios --cuerpo @boleta-prueba.json --json

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

    {
    "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). Guarda data.bhe.id y data.bhe.folioSii. Los modos SINC_COMPLETO y ASINCRONO responden con otra forma (en ASINCRONO viene un intentoId): ver Emisión.

  4. Comprueba la boleta en el servidor. Comando:

    Ventana de terminal
    redcumbre api obtenerBoletaHonorarios --param id=<data.bhe.id> --json

    Resultado esperado: 200 con la boleta completa en data, con estado: "EMITIDA", el mismo folioSii, el emisor 11111111-1 y el desglose de montos (montoBruto, ppm, montoLiquido). Si emitiste en modo ASINCRONO, consulta antes el intento: redcumbre api consultarIntentoEmisionBoletaHonorarios --param intentoId=<intentoId> --json hasta que data.estado sea EMITIDA (REINTENTANDO no es un desenlace: espera, no reemitas; sólo FALLIDA lo es).

  5. Guarda el PDF. Comando:

    Ventana de terminal
    redcumbre api descargarPdfInternoBoletaHonorarios --param id=<data.bhe.id> --salida boleta.pdf

    Resultado esperado: el CLI imprime Guardé N bytes en …/boleta.pdf y 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: pedir descargarPdfSiiBoletaHonorarios responde 404 y estadoPdfSii queda NO_APLICA. En producción el respaldo llega después de emitir, avisado por bhe.emision_terminada. Dónde guardar el archivo y cuál de los dos usar: Documentos y PDF.

  6. 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.anulada
    redcumbre eventos disparar bhe.emitida

    Resultado esperado: tu servidor recibe un POST firmado con event: "bhe.emitida" y bheId, 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. bhe.emision_terminada no 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>".

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

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

    causaSii es obligatorio: "1" no pago de honorarios, "2" prestación no realizada, "3" error de digitación. motivoInterno es sólo tuyo y nunca va al SII. Comando:

    Ventana de terminal
    redcumbre api anularBoletaHonorarios --param id=<data.bhe.id> --cuerpo @anular-prueba.json --json

    Resultado esperado: 202 con un anulacionId y estado: "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 202 só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> --json

    Resultado esperado: estado: "ANULADA" (en prueba se resuelve en segundos) y el evento bhe.anulada. Para programar contra el rechazo del SII, lleva esa anulación a NO_ANULABLE, que sólo existe en prueba: redcumbre api simularNoAnulableAnulacionBoletaHonorarios --param anulacionId=<anulacionId> --json (queda NO_ANULABLE, la boleta vuelve a EMITIDA y sale bhe.anulacion_fallida). Después se puede reintentar con reintentarAnulacionBoletaHonorarios. Una boleta emitida directamente en el sitio del SII se anula con anularBoletaHonorariosExterna, 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 tú enviaste:

  1. obtenerBoletaHonorarios responde estado: "EMITIDA" con un folioSii que empieza con SANDBOX-.
  2. El PDF descargado abre y lleva la marca de prueba.
  3. Tu receptor recibió bhe.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.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.

Si vesSignificaQué haces
422 con errorCode SII_CREDENCIAL_INVALIDA o EMISOR_CREDENCIAL_INVALIDALa clave tributaria del emisor fue rechazada o ya estaba marcada como inválida; la emisión está detenidaNo 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_INVALIDOEl SII rechazó el RUT del emisor o del destinatario. En prueba lo provoca el destinatario 44444444-4Corrige 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_HABILITADOEl 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_ERROREl SII no aceptó los datos de la boletaCorrige el cuerpo y reintenta con la misma idempotencyKey (una emisión fallida no reserva la clave)
400 con MULTIPLE_DESTINATARIO_MODES o DESTINATARIO_REQUIREDMandaste más de un modo de destinatario, o ningunoEnvía exactamente uno de destinatarioId, destinatario, siiLookup o lookupRut, o sinDestinatario: true
400 con RETENCION_INVALIDA_SIN_DESTINATARIOtipoRetencion: "RETRECEPTOR" junto con sinDestinatario: trueSin destinatario, usa RETCONTRIBUYENTE
400 con SII_LOOKUP_FAILED o CONTRIBUYENTE_NOT_FOUNDLa 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_DIARIOSuperaste 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
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 si existe. La clave de idempotencia queda reservada; si no salió, usa una clave nueva. Ver Emisión
503 con SII_EMISOR_BUSYEl emisor tiene demasiadas emisiones en cursoEspera los segundos de la cabecera 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 BHE_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 a soporte
404 al pedir el PDF del SIIAú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 anularLa boleta no tiene folio, no está EMITIDA, o el emisor está inactivo o sin credencialesCorrige el estado y repite. Un folio de prueba con llave de producción responde FOLIO_SANDBOX_EN_PRODUCCION
409 al anularYa hay una anulación en curso o terminada para esa boletaConsulta la anulación que ya existe; no se crea otra
Anulación en NO_ANULABLEEl 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_DEFINITIVASe agotaron los reintentos por una caída (el SII no rechazó nada)Reintenta con reintentarAnulacionBoletaHonorarios

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.

  1. 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 emisorTributarioId de producción es distinto al de prueba; léelo con redcumbre emisores tributarios listar --produccion --json y 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.

  2. Servicio contratado. El servicio de boletas de honorarios (SII_BHE) tiene que estar activo en la empresa. redcumbre pasar-a-produccion --servicios bhe revisa 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 en keys/redcumbre-produccion.json.

  3. 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 idempotencyKey vuelve a disparar bhe.emitida. Ver Webhooks.

  4. Precio. Lo que cuesta emitir y anular depende de tu plan: redcumbre tarifas emitirBoletaHonorarios --produccion y redcumbre tarifas anularBoletaHonorarios --produccion. lookupRut agrega la consulta al SII del destinatario: si ya tienes sus datos, usa destinatario completo, destinatarioId 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 emitirBoletaHonorarios --produccion --confirmar <identificador-de-la-empresa> --cuerpo @boleta.json --json

    Resultado esperado: 201 con cobro.modo: "produccion", un folio de producción del SII (sin el prefijo SANDBOX-) y sandbox: false. El PDF del SII llega después y se avisa con bhe.emision_terminada. Más sobre qué cambia entre modos: Modo de prueba y producción.