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:
modo | Qué hace antes de responder | Cuándo usarlo |
|---|---|---|
SINC_COMPLETO | Emite y genera todos los PDF, incluido el del SII | Necesitas 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 reintentos | El caso general |
ASINCRONO | Sólo valida y encola; todo lo demás ocurre en segundo plano, con reintentos | Emites 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.
redcumbre api emitirBoletaHonorarios --cuerpo @boleta.jsonCómo leer la respuesta
Sección titulada «Cómo leer la respuesta»- BHE y BHET: si la respuesta es
2xx, la boleta se emitió. ConASINCRONOlo que llega es elintentoId; la boleta aparece cuando el intento llega aEMITIDA. Un rechazo del SII nunca llega como2xxa una integración con API key: llega como422,502o503. - Documento tributario: ramifica por la presencia de
data.dte, nunca pormodo. Si vienedata.dte, el documento existe y tiene folio. Si no, quedó encolado y debes seguirdata.intentoId. Un emisor de firma local respondemodo: "ASINCRONO"pero trae el documento ya emitido; lo que queda en segundo plano es el envío al SII. - Borrador:
saveAsDraft: trueguarda 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 conemitirBorradorDte.
Seguir un intento asíncrono
Sección titulada «Seguir un intento asíncrono»redcumbre api consultarIntentoEmisionDte --param intentoId=<intentoId>redcumbre api consultarIntentoEmisionBoletaHonorarios --param intentoId=<intentoId>redcumbre api consultarIntentoEmisionBoletaTerceros --param intentoId=<intentoId>| Carril | Estados del intento |
|---|---|
| Documento tributario | PENDIENTE, PROCESANDO, REINTENTANDO, EMITIDO, FALLIDO |
| BHE y BHET | PENDIENTE, 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.
Idempotencia
Sección titulada «Idempotencia»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ón | Forma de idempotencia |
|---|---|
emitirDte, emitirBoletaHonorarios, emitirBoletaTerceros | clave: el campo idempotencyKey del cuerpo |
emitirBorradorDte, reintentarEmisionDte | recurso: 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:
| Documento | Alcance de la clave |
|---|---|
| Documento tributario | emisor, ambiente del SII (CERTIFICACION o PRODUCCION; no es el modo de prueba), tipo de documento y la propia clave |
| BHE y BHET | emisor 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
201con"idempotent": true: ese campo, no el status, distingue «emití» de «ya estaba emitido». En BHE y BHET se vuelve a disparar el webhookbhe.emitidaobhet.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 elintentoIdoriginal.
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.
redcumbre api emitirBoletaHonorarios --cuerpo @boleta.json --clave orden-compra-4471Resultado esperado: la boleta (o el intentoId) y la clave usada. Repetir exactamente el comando devuelve la misma boleta.
Resultado incierto
Sección titulada «Resultado incierto»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 recibes | Qué significa | Qué hacer |
|---|---|---|
2xx | La boleta se emitió; en un documento tributario, mira data.dte | Seguir |
400 | El 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 contribuyente | No reintentar sin corregir |
502 (BHE, BHET) | El SII respondió algo inutilizable | Reintentar con espera creciente y la misma clave |
503 | Hay demasiadas emisiones en curso o no se pudo verificar tu credencial; no se rechazó ni revocó la llave | Esperar los segundos de Retry-After y reintentar; no rotes la credencial |
500 con BHE_EMITIDA_NO_PERSISTIDA o BHET_EMITIDA_NO_PERSISTIDA | La boleta sí se emitió ante el SII y la plataforma no pudo guardarla; el cuerpo trae folioSii | No reintentar. Reportar el folio a soporte |
500 sin ese código | Defecto de la plataforma; la boleta queda en ERROR y el cuerpo trae boletaId | Reportarlo con ese id |
| Sin respuesta (timeout, conexión cortada) | No sabes nada | Consultar, ver abajo |
Procedimiento
Sección titulada «Procedimiento»- Con
idempotencyKeyen 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. - Sin clave, o para confirmar antes de reintentar: consulta si existe.
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-05redcumbre 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.
- 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.
Casos que no se arreglan reintentando igual
Sección titulada «Casos que no se arreglan reintentando igual»- 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 enERROR, 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ó.
estadoSii | motivo | Qué hacer |
|---|---|---|
ERROR_EMISION | ENVIO_INTENTOS_AGOTADOS | El envío pudo haber llegado: verifica el folio en el SII antes de reemitir |
FALLIDO_RECONCILIACION | ENVIO_INTENTOS_AGOTADOS | Una boleta cuyo envío no se confirmó: verifica el folio en el SII |
ERROR_EMISION | ENVIO_PLAZO_VENCIDO | El SII no lo conoce por esta vía; puedes reemitir |
TIMEOUT_SII | SEGUIMIENTO_AGOTADO | Verifica 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.