Ir al contenido

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).

  • Emitir de una vez entre 1 y 5.000 boletas desde un .xlsx, .xls o .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éDetalle
Llave de la empresaRol FULL-API. En el modo de prueba, la de keys/redcumbre-prueba.json.
Emisor tributarioUn 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 contratadoEn producción, SII_BHE o SII_BHET habilitado en la empresa. El modo de prueba no lo exige.
El archivoUna fila por boleta, con las columnas de abajo.
Cómo subirloejecutarProcesoBatch 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.

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):

ColumnaObligatoriaQué es
rut_emisorSíRUT del emisor tributario, con guion y dígito verificador (11111111-1)
tipo_retencionSíRETRECEPTOR o RETCONTRIBUYENTE
dest_rutNoRUT del destinatario. Si va vacío, la boleta se emite sin destinatario
dest_nombre, dest_direccion, dest_codigo_comunaSí, si hay dest_rutNombre, dirección y código SII de la comuna (la región se deriva de la comuna)
dest_emailNoSi lo traes, la boleta se envía por correo
prestacion_1_descripcion, prestacion_1_valorSíPrimera prestación (monto en pesos)
prestacion_2_… a prestacion_4_…NoHasta cuatro prestaciones por boleta
fecha_emisionNoAAAA-MM-DD; sin ella usa la fecha de hoy
correlation_idNoTu 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:

ColumnaObligatoriaQué es
rut_emisorSíRUT del emisor tributario
tercero_rut, tercero_nombre, tercero_domicilio, tercero_codigo_comunaSíLa persona que prestó el servicio y el código SII de su comuna
tercero_emailNoSi lo traes, la boleta se envía por correo
prestacion_1_descripcion, prestacion_1_valorSíPrimera prestación; hasta cuatro
fecha_emision, correlation_idNoIgual 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.

  1. Arma el archivo. Un CSV de honorarios de prueba, con una boleta sin destinatario y otra con destinatario (reemplaza <comuna> por un código de listarComunas):

    rut_emisor;tipo_retencion;dest_rut;dest_nombre;dest_direccion;dest_codigo_comuna;dest_email;prestacion_1_descripcion;prestacion_1_valor;correlation_id
    REQUERIDO;REQUERIDO;Opcional;Opcional;Opcional;Opcional;Opcional;REQUERIDO;REQUERIDO;Opcional
    11111111-1;RETRECEPTOR;;;;;;Asesoría tributaria;100000;lote-1-fila-1
    11111111-1;RETRECEPTOR;22222222-2;CONTRIBUYENTE DE PRUEBA DOS;CALLE UNO 123;<comuna>;;Informe mensual;50000;lote-1-fila-2

    La 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.csv en UTF-8 con BOM; si lo generas desde un script, escribe antes los bytes EF BB BF. En Excel, los datos van en la hoja Datos (o en la primera hoja).

  2. Súbelo sin iniciarlo. Con iniciarInmediatamente=false el lote queda PREPARADO y puedes revisar la validación antes de emitir nada. Manda siempre una idempotencyKey (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 api enví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 ejemplo scripts/subir-lote.mjs; Node 20.6 o superior). Lee la llave desde la ruta que apunta REDCUMBRE_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.csv
    import { 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 con node -p, ni pasándola a curl): el programa la lee solo y lo único que sale por pantalla es la respuesta del API. --env-file=.env carga la variable, que sólo apunta al archivo. Corre node --env-file=.env scripts/subir-lote.mjs lote.csv.

    Resultado esperado: 201 seguido de la respuesta, con data.proceso.estado PREPARADO, data.iniciado: false y data.validacion con puedeIniciar: true, filasValidas igual a totalFilas y errores vacío, y sandbox en true. Con iniciarInmediatamente en true (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.

  3. Si la validación falla, la respuesta es 400 y el lote queda creado en PREPARADO, sin iniciar. Cada error nombra la fila, la columna, el motivo y el valor recibido. Corrige el archivo y súbelo de nuevo (con otra idempotencyKey: 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 }
    }
  4. Inicia el lote. Sólo si quedó PREPARADO y sin errores. Esto es lo que emite (en el modo de prueba, simulado):

    Ventana de terminal
    redcumbre api iniciarProcesoBatch --param id=<id>

    Resultado esperado: 201 con message: "Proceso iniciado" y proceso.estado: "EN_COLA". No se puede cancelar desde la API. Repetirlo sobre un lote que ya no está PREPARADO responde 400 con su estado y no vuelve a emitir ninguna boleta.

  5. Sigue el avance. El lote recorre EN_COLA, EN_EJECUCION y termina en COMPLETADO, COMPLETADO_CON_ERRORES o FALLIDO:

    Ventana de terminal
    redcumbre api obtenerProcesoBatch --param id=<id>

    Resultado esperado: el detalle del lote. Cuando terminó, itemsProcesados es igual a totalItems y porcentaje es 100:

    {
    "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.

  6. Lee el resultado de cada fila. Pagina con limit y offset, y filtra con estado (PENDIENTE, EN_COLA, PROCESANDO, EXITOSO, FALLIDO, CANCELADO):

    Ventana de terminal
    redcumbre api listarFilasProcesoBatch --param id=<id> --param estado=FALLIDO --todas

    Resultado esperado: las filas fallidas, cada una con su número de fila, errorCodigo y errorMensaje; las exitosas traen folio, los montos y urlPdf:

    {
    "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 (o resumen.fallidos del evento), no sólo el estado: un lote con filas fallidas puede terminar como COMPLETADO.

  7. 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.xlsx

    Resultado esperado: ✓ Guardé N bytes en …/resultados.xlsx. El CLI no imprime el contenido. Si el lote aún no terminó, responde 400.

  8. 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.

  • Se subió bien: 201, data.validacion.puedeIniciar: true y errores vacío.
  • Terminó: obtenerProcesoBatch muestra itemsProcesados igual a totalItems, o llegó batch.completado.
  • Salió entero: itemsFallidos es 0, y listarFilasProcesoBatch con estado=EXITOSO trae un folio por fila.
  • Eres el modo correcto: sandbox: true en toda respuesta del modo de prueba; los folios son simulados.
Si vesSignificaQué haces
400 con VALIDATION_ERROREl 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 filasMás de 5.000 filasParte el archivo en lotes de hasta 5.000
400 con MODO_PRUEBA_TOPE_DIARIOLas filas del lote no caben en lo que queda del tope diario de prueba; el lote queda PREPARADOEspera a las 00:00 de Chile, o sube un lote más chico. redcumbre estado muestra lo que queda
400 al iniciarEl lote no está PREPARADO o tiene errores de validaciónConsulta su estado; un lote ya iniciado no se vuelve a emitir
400 al descargar resultadosEl lote no terminó o el archivo no está disponibleEspera a que termine
403La 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 loteUna 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-AfterNo se pudo verificar la llave en ese momento; la llave no fue rechazadaReintenta 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.

  • 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 con iniciarInmediatamente=false y 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 en keys/redcumbre-produccion.json, no se muestra). Cada comando de redcumbre api que 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 de REDCUMBRE_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_emisor del 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_BHE o SII_BHET).
  • El tope diario deja de aplicar; en cambio, cada boleta cuenta para el consumo de tu plan (redcumbre consumo --produccion).
  • Una idempotencyKey gastada probando no devuelve el lote de prueba en producción: el modo es parte de su alcance.