Carga masiva de boletas desde un archivo
Esta ficha sirve para emitir muchas boletas de una vez desde un archivo, en lugar de llamar emitirBoletaHonorarios o emitirBoletaTerceros una por una. Subes un archivo con una fila por boleta; la plataforma valida cada fila, emite en segundo plano, reintenta lo que falle por causas temporales y deja un archivo de resultados.
Por API la carga masiva cubre boletas de honorarios (BHE) y boletas de terceros (BHET). Las facturas, guías y demás documentos tributarios se emiten uno a uno con emitirDte (Documentos tributarios electrónicos).
Qué resuelve
Sección titulada «Qué resuelve»- Emitir de una vez entre 1 y 5.000 boletas desde un
.xlsx,.xlso.csv. - Validar el archivo completo antes de emitir y corregir las filas con error sin haber emitido nada.
- Seguir el avance, bajar el detalle fila por fila y el archivo de resultados con folios y errores.
- Emitir desde varios emisores en un solo archivo: el emisor va en cada fila (
rut_emisor).
Qué necesitas antes
Sección titulada «Qué necesitas antes»| Qué | Detalle |
|---|---|
| Llave de la empresa | Rol FULL-API. En el modo de prueba, la de keys/redcumbre-prueba.json. |
| Emisor tributario | Un emisor inscrito por tokenización para cada rut_emisor del archivo: Emisores y tokenización. En el modo de prueba están precargados 11111111-1 (honorarios) y 88888888-8 (terceros). |
| Servicio contratado | En producción, SII_BHE o SII_BHET habilitado en la empresa. El modo de prueba no lo exige. |
| El archivo | Una fila por boleta, con las columnas de abajo. |
| Cómo subirlo | ejecutarProcesoBatch recibe el archivo como formulario (multipart/form-data). redcumbre api envía el cuerpo como JSON y no adjunta archivos: con esta operación sube el archivo desde un programa de tu integración con el cliente HTTP de tu lenguaje (fetch y FormData en Node), como en el paso 2; ese programa lee la llave de la ruta de REDCUMBRE_LLAVE_PRUEBA, nunca la pasas por la línea de comandos. El resto de las operaciones sí se pueden correr con redcumbre api. |
Las plantillas oficiales de Excel y CSV se descargan con la sesión de una persona en la aplicación web, no con una llave de API. Para un agente basta con armar el archivo con las columnas de abajo.
Columnas del archivo
Sección titulada «Columnas del archivo»La primera fila trae los nombres de las columnas (en minúsculas, tal como se escriben acá). La segunda fila no es un dato: en la plantilla indica cuáles columnas son obligatorias y la plataforma siempre la salta, también en CSV. Tus boletas empiezan en la fila 3. En CSV el separador es punto y coma (;) o coma, y la codificación UTF-8, con BOM.
BHE (tipo=BHE):
| Columna | Obligatoria | Qué es |
|---|---|---|
rut_emisor | Sí | RUT del emisor tributario, con guion y dígito verificador (11111111-1) |
tipo_retencion | Sí | RETRECEPTOR o RETCONTRIBUYENTE |
dest_rut | No | RUT del destinatario. Si va vacío, la boleta se emite sin destinatario |
dest_nombre, dest_direccion, dest_codigo_comuna | Sí, si hay dest_rut | Nombre, dirección y código SII de la comuna (la región se deriva de la comuna) |
dest_email | No | Si lo traes, la boleta se envía por correo |
prestacion_1_descripcion, prestacion_1_valor | Sí | Primera prestación (monto en pesos) |
prestacion_2_… a prestacion_4_… | No | Hasta cuatro prestaciones por boleta |
fecha_emision | No | AAAA-MM-DD; sin ella usa la fecha de hoy |
correlation_id | No | Tu identificador, para cruzar el resultado con tu sistema |
BHET (tipo=BHET): igual que BHE, pero sin tipo_retencion ni dest_*, y con el tercero siempre obligatorio:
| Columna | Obligatoria | Qué es |
|---|---|---|
rut_emisor | Sí | RUT del emisor tributario |
tercero_rut, tercero_nombre, tercero_domicilio, tercero_codigo_comuna | Sí | La persona que prestó el servicio y el código SII de su comuna |
tercero_email | No | Si lo traes, la boleta se envía por correo |
prestacion_1_descripcion, prestacion_1_valor | Sí | Primera prestación; hasta cuatro |
fecha_emision, correlation_id | No | Igual que en BHE |
Los códigos SII de comuna salen de listarComunas (redcumbre api listarComunas). Máximo 5.000 filas por archivo; con más, la carga se rechaza.
Los ejemplos usan el modo de prueba: el lote corre de verdad con el motor de simulación, boleta por boleta, con las mismas validaciones por fila que en producción y sin llamar al SII.
-
Arma el archivo. Un CSV de honorarios de prueba, con una boleta sin destinatario y otra con destinatario (reemplaza
<comuna>por un código delistarComunas):rut_emisor;tipo_retencion;dest_rut;dest_nombre;dest_direccion;dest_codigo_comuna;dest_email;prestacion_1_descripcion;prestacion_1_valor;correlation_idREQUERIDO;REQUERIDO;Opcional;Opcional;Opcional;Opcional;Opcional;REQUERIDO;REQUERIDO;Opcional11111111-1;RETRECEPTOR;;;;;;Asesoría tributaria;100000;lote-1-fila-111111111-1;RETRECEPTOR;22222222-2;CONTRIBUYENTE DE PRUEBA DOS;CALLE UNO 123;<comuna>;;Informe mensual;50000;lote-1-fila-2La segunda línea nunca se lee como dato: la plataforma siempre salta la fila 2 (en la plantilla es la fila que marca cada columna como requerida u opcional). Si la omites, tu primera boleta se pierde en silencio. Guárdalo como
lote.csven UTF-8 con BOM; si lo generas desde un script, escribe antes los bytesEF BB BF. En Excel, los datos van en la hojaDatos(o en la primera hoja). -
Súbelo sin iniciarlo. Con
iniciarInmediatamente=falseel lote quedaPREPARADOy puedes revisar la validación antes de emitir nada. Manda siempre unaidempotencyKey(hasta 128 caracteres): si repites la llamada con la misma clave, en la misma empresa y el mismo modo, recibes el mismo lote y no se crea otro.redcumbre apienvía JSON y esta operación es un formulario con archivo, así que la subida es un programa pequeño de tu integración, no un comando con la llave en la línea. Escríbelo en tu proyecto (por ejemploscripts/subir-lote.mjs; Node 20.6 o superior). Lee la llave desde la ruta que apuntaREDCUMBRE_LLAVE_PRUEBA, tal como lo hará tu sistema en ejecución, y nunca la imprime:// scripts/subir-lote.mjs — uso: node --env-file=.env scripts/subir-lote.mjs lote.csvimport { readFile } from 'node:fs/promises';import path from 'node:path';const variable = process.argv.includes('--produccion') ? 'REDCUMBRE_LLAVE_PRODUCCION' : 'REDCUMBRE_LLAVE_PRUEBA';const rutaLlave = process.env[variable];if (!rutaLlave) throw new Error(`Falta la variable ${variable} (la ruta del archivo de la llave).`);const { tenantSlug, token } = JSON.parse(await readFile(rutaLlave, 'utf8'));const archivo = process.argv[2];if (!archivo) throw new Error('Indica el archivo: node scripts/subir-lote.mjs lote.csv');const formulario = new FormData();formulario.set('tipo', 'BHE');formulario.set('archivo', new Blob([await readFile(archivo)]), path.basename(archivo));formulario.set('nombre', 'Honorarios noviembre');formulario.set('iniciarInmediatamente', 'false');formulario.set('idempotencyKey', 'lote-honorarios-2026-11');// Opcional: formulario.set('emailsAdicionales', JSON.stringify(['supervisor@tuempresa.cl']));const respuesta = await fetch(`https://api.redcumbre.cl/${encodeURIComponent(tenantSlug)}/procesos-batch/api/ejecutar`, {method: 'POST',headers: { Authorization: `Bearer ${token}` },body: formulario,});console.log(respuesta.status, await respuesta.text());if (!respuesta.ok) process.exitCode = 1;Quien escribe y corre este programa no abre ni imprime el archivo de la llave (ni con
cat, ni connode -p, ni pasándola acurl): el programa la lee solo y lo único que sale por pantalla es la respuesta del API.--env-file=.envcarga la variable, que sólo apunta al archivo. Correnode --env-file=.env scripts/subir-lote.mjs lote.csv.Resultado esperado:
201seguido de la respuesta, condata.proceso.estadoPREPARADO,data.iniciado: falseydata.validacionconpuedeIniciar: true,filasValidasigual atotalFilasyerroresvacío, ysandboxentrue. ConiniciarInmediatamenteentrue(el valor por defecto de la operación) el lote empieza a procesarse en el acto y la respuesta es:{"success": true,"data": {"proceso": {"id": "clxyz123abc","tipo": "BHE","estado": "EN_COLA","nombre": "Honorarios noviembre","totalItems": 2,"itemsProcesados": 0,"itemsExitosos": 0,"itemsFallidos": 0,"estadoValidacion": "VALIDO","creadoEn": "2026-11-05T12:00:00.000Z"},"validacion": { "puedeIniciar": true, "totalFilas": 2, "filasValidas": 2, "filasConErrores": 0, "errores": [] },"iniciado": true},"sandbox": true,"cobro": { "modo": "prueba", "mensaje": "En modo de prueba no se cobra." }}Guarda el
data.proceso.id. -
Si la validación falla, la respuesta es
400y el lote queda creado enPREPARADO, sin iniciar. Cada error nombra la fila, la columna, el motivo y el valor recibido. Corrige el archivo y súbelo de nuevo (con otraidempotencyKey: la anterior ya devolvería el lote con errores):{"success": false,"error": {"code": "VALIDATION_ERROR","message": "El archivo contiene errores de validación","totalFilas": 2,"filasConErrores": 1,"errores": [{ "fila": 4, "columna": "dest_rut", "mensaje": "RUT inválido", "valor": "123456789" }]},"data": { "proceso": {}, "validacion": {}, "iniciado": false }} -
Inicia el lote. Sólo si quedó
PREPARADOy sin errores. Esto es lo que emite (en el modo de prueba, simulado):Ventana de terminal redcumbre api iniciarProcesoBatch --param id=<id>Resultado esperado:
201conmessage: "Proceso iniciado"yproceso.estado: "EN_COLA". No se puede cancelar desde la API. Repetirlo sobre un lote que ya no estáPREPARADOresponde400con su estado y no vuelve a emitir ninguna boleta. -
Sigue el avance. El lote recorre
EN_COLA,EN_EJECUCIONy termina enCOMPLETADO,COMPLETADO_CON_ERRORESoFALLIDO:Ventana de terminal redcumbre api obtenerProcesoBatch --param id=<id>Resultado esperado: el detalle del lote. Cuando terminó,
itemsProcesadoses igual atotalItemsyporcentajees100:{"id": "clxyz123abc","tipo": "BHE","estado": "COMPLETADO","nombre": "Honorarios noviembre","totalItems": 2,"itemsProcesados": 2,"itemsExitosos": 2,"itemsFallidos": 0,"porcentaje": 100,"estadoValidacion": "VALIDO","emisor": { "id": "clemisor123", "rut": "11111111-1", "razonSocial": "PROFESIONAL DE PRUEBA RCAPI" },"creadoEn": "2026-11-05T12:00:00.000Z","iniciadoEn": "2026-11-05T12:00:05.000Z","finalizadoEn": "2026-11-05T12:00:20.000Z","sandbox": true}Para no consultar en un ciclo, suscríbete a
batch.completado(Webhooks). Es un evento de adhesión explícita: tienes que listarlo en los eventos habilitados, porque dejar la lista vacía no lo activa. Lleva el resumen (total,exitosos,fallidos,porcentaje) y la ruta de resultados. En el modo de prueba lo dispara el propio lote. -
Lee el resultado de cada fila. Pagina con
limityoffset, y filtra conestado(PENDIENTE,EN_COLA,PROCESANDO,EXITOSO,FALLIDO,CANCELADO):Ventana de terminal redcumbre api listarFilasProcesoBatch --param id=<id> --param estado=FALLIDO --todasResultado esperado: las filas fallidas, cada una con su número de
fila,errorCodigoyerrorMensaje; las exitosas traenfolio, los montos yurlPdf:{"data": [{"id": "clitem001","fila": 3,"estado": "EXITOSO","folio": 12345678,"montoBruto": 100000,"montoRetencion": 15250,"montoLiquido": 84750,"urlPdf": "https://app.redcumbre.cl/d/DHp51REmpiqt/pdf","procesadoEn": "2026-11-05T12:00:10.000Z"}],"total": 1,"limit": 50,"offset": 0,"sandbox": true}Para decidir si el lote salió completo, mira
itemsFallidos(oresumen.fallidosdel evento), no sólo elestado: un lote con filas fallidas puede terminar comoCOMPLETADO. -
Baja el archivo de resultados. Es tu archivo con columnas agregadas (
_resultado,_folio,_monto_bruto,_monto_retencion,_monto_liquido,_url_pdf,_error_codigo,_error_mensaje, entre otras). Sólo está disponible cuando el lote terminó:Ventana de terminal redcumbre api descargarResultadosProcesoBatch --param id=<id> --salida resultados.xlsxResultado esperado:
✓ Guardé N bytes en …/resultados.xlsx. El CLI no imprime el contenido. Si el lote aún no terminó, responde400. -
Reintenta sólo lo que falló. Corrige la causa (por ejemplo, la credencial del emisor), arma un archivo nuevo sólo con las filas fallidas —sus datos están en el archivo de resultados— y súbelo como un lote nuevo con otra
idempotencyKey. El lote original no cambia. No reenvíes las filas que ya salieron: en producción, cada boleta emitida ya vale ante el SII.
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»- Se subió bien:
201,data.validacion.puedeIniciar: trueyerroresvacío. - Terminó:
obtenerProcesoBatchmuestraitemsProcesadosigual atotalItems, o llegóbatch.completado. - Salió entero:
itemsFallidoses0, ylistarFilasProcesoBatchconestado=EXITOSOtrae unfoliopor fila. - Eres el modo correcto:
sandbox: trueen toda respuesta del modo de prueba; los folios son simulados.
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
400 con VALIDATION_ERROR | El archivo tiene filas con errores (RUT inválido, comuna desconocida, columna que falta) | Lee error.errores (fila, columna, motivo, valor), corrige y vuelve a subir |
400 por exceso de filas | Más de 5.000 filas | Parte el archivo en lotes de hasta 5.000 |
400 con MODO_PRUEBA_TOPE_DIARIO | Las filas del lote no caben en lo que queda del tope diario de prueba; el lote queda PREPARADO | Espera a las 00:00 de Chile, o sube un lote más chico. redcumbre estado muestra lo que queda |
400 al iniciar | El lote no está PREPARADO o tiene errores de validación | Consulta su estado; un lote ya iniciado no se vuelve a emitir |
400 al descargar resultados | El lote no terminó o el archivo no está disponible | Espera a que termine |
403 | La llave no tiene rol FULL-API, o la empresa no tiene el servicio SII_BHE o SII_BHET (producción) | Usa una llave FULL-API; revisa los servicios contratados |
Filas FALLIDO en el lote | Una fila falló aunque las demás salieron (credencial del emisor rechazada, SII sin respuesta tras los reintentos, datos que el SII rechaza) | Lee errorCodigo y errorMensaje de la fila; corrige y reenvía sólo esas filas (paso 8) |
503 con Retry-After | No se pudo verificar la llave en ese momento; la llave no fue rechazada | Reintenta respetando la espera; no rotes la llave |
Un fallo temporal del SII se reintenta solo, con pausas crecientes, antes de marcar la fila como fallida: no reenvíes una fila mientras su lote siga en ejecución.
Antes de pasar a producción
Sección titulada «Antes de pasar a producción»- Cada fila que sale bien es una boleta de producción ante el SII. Lo que cuesta depende de tu plan:
redcumbre tarifas --produccion. El lote no se puede cancelar desde la API: revisa el archivo coniniciarInmediatamente=falsey confirma con la persona antes de iniciar. - Cambia la llave y el emisor. La llave de producción se agrega con
redcumbre pasar-a-produccion(queda enkeys/redcumbre-produccion.json, no se muestra). Cada comando deredcumbre apique escribe en producción lleva--produccion --confirmar <slug>; el programa del paso 2 usa la llave de producción cuando lo corres con--produccion(lee la ruta deREDCUMBRE_LLAVE_PRODUCCION), y lo corre la persona tras confirmar el archivo: un agente no lanza una subida a producción ni abre el archivo de la llave. Ver Modo de prueba y producción. - Los
rut_emisordel archivo tienen que ser emisores de producción de la empresa, inscritos por tokenización y con la credencial del SII vigente. Los de prueba (11111111-1,88888888-8) no existen en producción. - Se exige el servicio contratado (
SII_BHEoSII_BHET). - El tope diario deja de aplicar; en cambio, cada boleta cuenta para el consumo de tu plan (
redcumbre consumo --produccion). - Una
idempotencyKeygastada probando no devuelve el lote de prueba en producción: el modo es parte de su alcance.