Ir al contenido

Emisión de documentos

Aplica a las tres emisiones tributarias: documentos tributarios electrónicos (emitirDte), boletas de honorarios (emitirBoletaHonorarios) y boletas de terceros (emitirBoletaTerceros). Sirve de base a las fichas de cada una. Para qué emisor usar, ver Emisores y tokenización; para bajar el PDF, Documentos y PDF.

Una emisión en producción vale ante el SII: llega al SII, consume un folio o genera una boleta ante el SII. Lo que cuesta depende de tu plan: redcumbre tarifas <operationId> --produccion. Con una llave de prueba la emisión es simulada: nada llega al SII (ver Modo de prueba y producción). Antes de emitir en producción, confirma con la persona.

El campo modo del pedido decide cuánto trabajo se hace antes de responder:

modoQué hace antes de responderCuándo usarlo
SINC_COMPLETOEmite y genera todos los PDF, incluido el del SIINecesitas el PDF del SII en la misma llamada
SINC_PARCIAL (por omisión)Emite y genera el PDF interno; el PDF del SII se baja después, con reintentosEl caso general
ASINCRONOSólo valida y encola; todo lo demás ocurre en segundo plano, con reintentosEmites desde una petición web y no quieres esperar al SII

Sin modo, vale el default de tu empresa (SINC_PARCIAL). En documentos tributarios el modo sólo gobierna a los emisores PORTAL_MIPYME: en FULL_DTE y SOLO_BOLETA se ignora, porque esas integraciones responden apenas tienen folio y envían al SII en segundo plano.

Ejemplo de una boleta de honorarios propia, sin destinatario, en modo asíncrono y con clave de idempotencia:

{
"emisorTributarioId": "cmikf6ei00001sek0mxzcf668",
"sinDestinatario": true,
"prestaciones": [
{ "descripcion": "Asesoría contable", "valor": "150000" }
],
"tipoRetencion": "RETCONTRIBUYENTE",
"idempotencyKey": "orden-compra-4471",
"modo": "ASINCRONO"
}

Resultado esperado (modo asíncrono): 201 con un intentoId y el estado PENDIENTE en lugar de la boleta. Con una llave de prueba, emisorTributarioId es el de un emisor de boletas de honorarios de prueba: el precargado 11111111-1 (su id sale de redcumbre escenarios --json, en emisoresTributarios) o el que deja completar la tokenización de prueba con 12345678-5 (ver Emisores y tokenización). El id del ejemplo es de relleno: reemplázalo por el tuyo.

Ventana de terminal
redcumbre api emitirBoletaHonorarios --cuerpo @boleta.json
  • BHE y BHET: si la respuesta es 2xx, la boleta se emitió. Con ASINCRONO lo que llega es el intentoId; la boleta aparece cuando el intento llega a EMITIDA. Un rechazo del SII nunca llega como 2xx a una integración con API key: llega como 422, 502 o 503.
  • Documento tributario: ramifica por la presencia de data.dte, nunca por modo. Si viene data.dte, el documento existe y tiene folio. Si no, quedó encolado y debes seguir data.intentoId. Un emisor de firma local responde modo: "ASINCRONO" pero trae el documento ya emitido; lo que queda en segundo plano es el envío al SII.
  • Borrador: saveAsDraft: true guarda el documento sin emitir ni consumir folio. Pasa por la misma validación que una emisión, así que sirve para probar un pedido sin efectos. Se emite después con emitirBorradorDte.
Ventana de terminal
redcumbre api consultarIntentoEmisionDte --param intentoId=<intentoId>
redcumbre api consultarIntentoEmisionBoletaHonorarios --param intentoId=<intentoId>
redcumbre api consultarIntentoEmisionBoletaTerceros --param intentoId=<intentoId>
CarrilEstados del intento
Documento tributarioPENDIENTE, PROCESANDO, REINTENTANDO, EMITIDO, FALLIDO
BHE y BHETPENDIENTE, PROCESANDO, REINTENTANDO, EMITIDA, FALLIDA
{
"success": true,
"data": {
"intentoId": "dtei_3f2a1b8c",
"estado": "REINTENTANDO",
"dteId": null,
"error": null,
"createdAt": "2026-11-05T14:00:00.000Z",
"updatedAt": "2026-11-05T14:35:00.000Z"
},
"sandbox": false
}

En BHE y BHET la respuesta del código es { "success": true, "data": { … } } con id, estado, intentos, ultimoIntento y, cuando está EMITIDA, la boleta en data.bhe (o data.bhet).

REINTENTANDO no es un desenlace. Un intento falló y la plataforma volverá a intentar: son 10 intentos con la espera duplicándose desde 5 minutos y un techo de 6 horas por hueco, lo que da una ventana de entre 18 y 22,6 horas. Mientras tanto no reemitas. Sólo FALLIDO o FALLIDA son definitivos, y llegan una sola vez; un error que no se arregla reintentando (RUT inválido, certificado o CAF vencido) salta directo a fallido.

Prefiere los webhooks al sondeo: bhe.emitida, bhe.emision_reintentando, bhe.emision_fallida (y los equivalentes bhet. y dte.). Cómo recibirlos y verificarlos: Webhooks.

Si tu sistema puede reintentar —por un timeout, un error de red o un doble clic—, manda siempre idempotencyKey (hasta 128 caracteres). Con la misma clave, un reintento devuelve el documento ya emitido y no emite otro ni consume folio.

La clave es del cuerpo del pedido. El mapa de la API lo declara en x-rcapi-idempotencia de cada operación:

OperaciónForma de idempotencia
emitirDte, emitirBoletaHonorarios, emitirBoletaTercerosclave: el campo idempotencyKey del cuerpo
emitirBorradorDte, reintentarEmisionDterecurso: el documento se emite una sola vez; repetir responde 400 si ya se emitió y 409 si se está emitiendo

redcumbre api describir <operación> imprime esta declaración. Reglas de la clave:

DocumentoAlcance de la clave
Documento tributarioemisor, ambiente del SII (CERTIFICACION o PRODUCCION; no es el modo de prueba), tipo de documento y la propia clave
BHE y BHETemisor y la propia clave
  • Es permanente: no expira.
  • Anular libera la clave. Un documento anulado deja de ocuparla y la misma clave vuelve a emitir uno nuevo. Si una clave a veces devuelve el original y a veces emite uno nuevo, revisa si el original fue anulado.
  • Un reintento con la clave usada devuelve el documento original (mismo folio, mismo receptor, mismos montos de la primera emisión, no los del pedido nuevo). En documentos tributarios la respuesta es 201 con "idempotent": true: ese campo, no el status, distingue «emití» de «ya estaba emitido». En BHE y BHET se vuelve a disparar el webhook bhe.emitida o bhet.emitida, porque quien repite la clave probablemente no recibió el aviso.
  • Si la emisión falló (rechazo del SII), la clave no queda reservada: corriges el dato y reenvías con la misma clave. La excepción es el resultado incierto, más abajo.
  • BHE: dos pedidos simultáneos con la misma clave se resuelven en orden: el segundo espera, encuentra el documento del primero y lo devuelve.
  • BHE en ASINCRONO: la protección cubre también la emisión en vuelo: si reintentas mientras la primera sigue en cola, recibes el intentoId original.

Elige bien la clave. Usa un identificador estable de tu sistema (el número de la orden, el id de la venta), no un UUID generado en cada intento: una clave nueva por intento no protege de nada. correlationId es sólo trazabilidad y no evita duplicados.

Con el CLI, la clave viaja en el cuerpo (idempotencyKey) o con --clave. Si no pasas ninguna, el CLI genera una y la imprime: guárdala y úsala con --clave si reintentas.

Ventana de terminal
redcumbre api emitirBoletaHonorarios --cuerpo @boleta.json --clave orden-compra-4471

Resultado esperado: la boleta (o el intentoId) y la clave usada. Repetir exactamente el comando devuelve la misma boleta.

Un resultado es incierto cuando no sabes si el documento salió: se cortó la conexión, venció tu tiempo de espera, o recibiste un error que no dice si el SII alcanzó a procesarlo. Regla de oro: consultar antes de reintentar. Reemitir a ciegas puede dejar dos documentos ante el SII y quemar un folio.

Qué dice cada respuesta:

Lo que recibesQué significaQué hacer
2xxLa boleta se emitió; en un documento tributario, mira data.dteSeguir
400El pedido no pasó validación; no se emitióCorregir el pedido
422 (BHE, BHET)El SII lo rechazó por su contenido o por el estado del contribuyenteNo reintentar sin corregir
502 (BHE, BHET)El SII respondió algo inutilizableReintentar con espera creciente y la misma clave
503Hay demasiadas emisiones en curso o no se pudo verificar tu credencial; no se rechazó ni revocó la llaveEsperar los segundos de Retry-After y reintentar; no rotes la credencial
500 con BHE_EMITIDA_NO_PERSISTIDA o BHET_EMITIDA_NO_PERSISTIDALa boleta sí se emitió ante el SII y la plataforma no pudo guardarla; el cuerpo trae folioSiiNo reintentar. Reportar el folio a soporte
500 sin ese códigoDefecto de la plataforma; la boleta queda en ERROR y el cuerpo trae boletaIdReportarlo con ese id
Sin respuesta (timeout, conexión cortada)No sabes nadaConsultar, ver abajo
  1. Con idempotencyKey en el pedido original: reintenta con la misma clave. Si el documento ya existe, te lo devuelve sin duplicar; si no existía, lo emite. Es la vía más segura, y por eso la clave se manda siempre.
  2. Sin clave, o para confirmar antes de reintentar: consulta si existe.
Ventana de terminal
redcumbre api listarBoletasHonorarios --param folioSii=<folio>
redcumbre api listarBoletasHonorarios --param fechaDesde=2026-11-05 --param estado=<estado>
redcumbre api listarDte --param emisorDteId=<emisorDteId> --param fechaDesde=2026-11-05
redcumbre api obtenerDte --param id=<dteId>

Resultado esperado: la lista de documentos que coinciden; si el tuyo no está y no hay un intento en vuelo, no se emitió. Para un documento tributario ya existente, el estado ante el SII se consulta con verificarEstadoSiiDte.

  1. Emisión asíncrona: el estado vigente está en el intento (consultarIntento…), no en el webhook. Un webhook es un aviso que puede perderse (ver Webhooks); reconcilia con la API.
  • BHE o BHET con SII_CONFIRMACION_INCIERTA: el SII no respondió al paso que emite y no se sabe si la boleta salió. La clave queda reservada: reintentar con ella devuelve esa misma boleta en ERROR, sin emitir. Verifica en el sitio del SII si la boleta existe; si no salió, reintenta con una clave nueva.
  • Documento tributario sin veredicto del SII (evento dte.emision_sin_confirmar). La plataforma dejó de procurar el resultado de un documento que ya existía; no afirma que el SII lo rechazó ni que no lo recibió.
estadoSiimotivoQué hacer
ERROR_EMISIONENVIO_INTENTOS_AGOTADOSEl envío pudo haber llegado: verifica el folio en el SII antes de reemitir
FALLIDO_RECONCILIACIONENVIO_INTENTOS_AGOTADOSUna boleta cuyo envío no se confirmó: verifica el folio en el SII
ERROR_EMISIONENVIO_PLAZO_VENCIDOEl SII no lo conoce por esta vía; puedes reemitir
TIMEOUT_SIISEGUIMIENTO_AGOTADOVerifica el folio. Si después hay veredicto, llega dte.emision_terminada, que es la última palabra

Para una boleta electrónica (tipo 39 o 41) en ERROR_EMISION que ya consumió folio, reintentarEmisionDte reutiliza ese folio en vez de consumir otro.

  • No reemitas un documento tributario con la misma idempotencyKey: te devolverá el original. Para corregir, emite con una clave distinta; eso consume un folio nuevo. El folio de un documento rechazado o en error no se anula ni se reutiliza automáticamente.
  • No reemitas mientras recibes *_emision_reintentando: es informativo.