Ir al contenido

Validación masiva de RUT

Revisar muchos RUT de una vez, por ejemplo una cartera de clientes o un archivo que llega de otro sistema, sin consultarlos uno por uno. Por cada RUT el proceso dice si el dígito verificador cuadra y, según el nivel que elijas, qué sabe el SII de él. Para un solo RUT con respuesta inmediata, la ficha es Consulta de un RUT.

Un proceso tiene hasta 5.000 filas y pasa por pasos separados, a propósito: primero se crea (sin consultar nada), después se cotiza y recién entonces se inicia.

NivelQué entrega cada fila
PERSONANombre y condición de fallecido. Resuelve personas naturales sin inicio de actividades
COMPLETOLo anterior, más razón social, dirección, comuna, actividades económicas y casilla de intercambio
  • Una llave de prueba conectada al proyecto. Si keys/redcumbre-prueba.json no existe, parte por el arranque o corre redcumbre init. No hace falta ningún emisor.
  • Rol FULL-API, que es el de la llave del proyecto.
  • Los RUT, como lista JSON (hasta 5.000) o como archivo Excel .xlsx con una columna rut en la primera fila (el resto de las columnas se conserva en el resultado). El CLI envía sólo la lista JSON; el archivo lo sube tu código por multipart/form-data en el campo archivo, y se manda uno de los dos, nunca ambos. La plantilla del archivo se baja con descargarPlantillaValidacionRut.
  • Para avisos al terminar: un endpoint de webhooks, ver Webhooks. Qué cambia entre los modos: Modo de prueba y producción. Paginación y errores: Reglas comunes.
  1. Cotiza el nivel. Comando:

    Ventana de terminal
    redcumbre api consultarPrecioValidacionRut --param nivel=COMPLETO --json

    Resultado esperado: 200 con el precio unitario por RUT según el plan de la empresa y su desglose por métrica (modelo de cobro, precio fijo por fila y tramos). Si alguna métrica se cobra por tramos (graduated o volume), por paquete o por dimensión, no tiene un precio fijo por fila: responde available: true sin price total, y esa métrica viene en el desglose con price: null y sus tramos; lo que cuesta depende de lo consumido en el período, también fuera de la validación. Si alguna métrica del nivel no está en el plan, responde igual 200 con available: false y un mensaje, nunca un precio parcial: el proceso se ejecuta entero o no se ejecuta. El precio es el mismo en prueba y en producción.

  2. Crea el proceso. Cuerpo de prueba (los dos primeros RUT son del catálogo de prueba, el tercero está declarado «no encontrado» y el cuarto tiene un dígito verificador que no cuadra):

    {
    "nivel": "PERSONA",
    "ruts": ["22222222-2", "33333333-3", "99999999-9", "11111111-2"]
    }

    Los RUT se aceptan en cualquier formato (con o sin puntos y guión, con ceros a la izquierda). Comando:

    Ventana de terminal
    redcumbre api crearProcesoValidacionRut --cuerpo '{"nivel":"PERSONA","ruts":["22222222-2","33333333-3","99999999-9","11111111-2"]}' --json

    Resultado esperado: 201 con el proceso en estado: "PREPARADO", totalFilas: 4 y un id. Este paso sólo cuenta filas y guarda el archivo: no valida ningún RUT y no consulta al SII. forzarActualizacion: true salta la copia que guarda la plataforma y consulta al SII aunque el dato sea reciente; en producción consulta todas las filas, por eso por defecto es false.

  3. Inicia el proceso. Comando:

    Ventana de terminal
    redcumbre api iniciarProcesoValidacionRut --param id=<id> --json

    Resultado esperado: 201 casi de inmediato, sin esperar el procesamiento, con el proceso en EN_COLA. Sólo se puede iniciar un proceso en PREPARADO. Al iniciar se sanea cada RUT, se descartan los de dígito verificador inválido (sin consultarlos) y se deduplican los repetidos (un RUT repetido se consulta una vez y su resultado se copia a todas sus filas). En el modo de prueba cada fila cuenta uno en el tope diario de 200 RUT, y todo se resuelve contra el catálogo de RUT de prueba: nunca se llama al SII.

  4. Sigue el avance. Comando, repetido con espera entre llamadas:

    Ventana de terminal
    redcumbre api consultarProcesoValidacionRut --param id=<id> --json

    Resultado esperado: el estado recorre PREPARADO, EN_COLA, EN_EJECUCION y termina en uno de COMPLETADO, COMPLETADO_CON_ERRORES, CANCELADO o FALLIDO. Los contadores son totalFilas, filasProcesadas, filasValidas, filasInvalidas y filasFallidas. Cuando tieneResultado es true, el archivo de resultado ya se puede descargar. Si perdiste el id, redcumbre api listarProcesosValidacionRut --json lista los procesos de la empresa (admite --param estado= y --param nivel=). En vez de consultar en bucle, suscríbete a validacion_rut.completada y validacion_rut.fallida: el primero trae procesoId, estado, los contadores y tieneResultado; el segundo, error, y avisa que no hay resultado y que conviene reintentar el lote entero.

  5. Lee el resultado fila por fila. Comando:

    Ventana de terminal
    redcumbre api listarFilasProcesoValidacionRut --param id=<id> --json

    Resultado esperado: 200 con data (una fila por RUT, en el orden del archivo) y meta (total, limit, offset). Cada fila trae rutOriginal (como lo enviaste), rutCanonico, esValido (si el dígito verificador cuadra), estado (PENDIENTE, PROCESADO o FALLIDO), datosSalida y origenDato (SII o LOCAL). En datosSalida, tipoContribuyente es lo que respondió el SII: PERSONA_NATURAL, PERSONA_FALLECIDA, PERSONA_JURIDICA, RUT_NO_ENCONTRADO o DESCONOCIDO; fallecido es una marca, no una fecha. En el ejemplo, las dos primeras filas salen PERSONA_NATURAL, la tercera RUT_NO_ENCONTRADO, y la cuarta con esValido: false.

  6. Descarga el archivo si lo necesitas. Comando:

    Ventana de terminal
    redcumbre api descargarResultadoValidacionRut --param id=<id> --salida resultado.xlsx

    Resultado esperado: el CLI imprime Guardé N bytes en …/resultado.xlsx. Es el Excel original con sus columnas intactas y, a continuación, las columnas de resultado. Se llama <archivo>_resultado.xlsx, y pedirlo de nuevo lo sobrescribe. descargarArchivoOriginalValidacionRut devuelve el archivo tal como se subió.

  7. Cancela si hace falta. Comando:

    Ventana de terminal
    redcumbre api cancelarProcesoValidacionRut --param id=<id> --json

    Resultado esperado: sólo funciona con el proceso en EN_COLA o EN_EJECUCION. Las filas que no se procesaron no se consultan al SII; las ya resueltas conservan su resultado y siguen en el listado de filas.

  • El proceso llegó a COMPLETADO (o COMPLETADO_CON_ERRORES, que sigue siendo un término con resultado: mira filasFallidas y las filas con estado: "FALLIDO") y tieneResultado es true.
  • filasProcesadas alcanza lo esperado y cada fila de listarFilasProcesoValidacionRut tiene estado: "PROCESADO" o su motivo de falla.
  • Tu receptor recibió validacion_rut.completada con sandbox: true (en el modo de prueba) y firma válida.
  • No des por buena una fila sólo porque el proceso terminó: el término del lote no dice que cada RUT haya tenido datos. Una fila RUT_NO_ENCONTRADO es un resultado válido, no un error del proceso.
Si vesSignificaQué haces
400 al crear: «Envía un archivo … o una lista …»No mandaste ni archivo ni ruts, o mandaste los dosEnvía exactamente uno
400 al crear por exceder 5.000 filas, o ruts vacíoEl lote no cabe o no tiene contenidoDivide el lote en procesos de hasta 5.000
400 al iniciar con MODO_PRUEBA_TOPE_DIARIOEl lote no cabe en el tope diario de prueba (200 RUT, cuenta uno por fila) y se rechaza entero, sin tocar ninguna filaReduce el lote o espera hasta las 00:00 de Chile. redcumbre estado dice cuánto queda
Error al iniciar un proceso que no está PREPARADOYa se inició, terminó o se cancelóCrea uno nuevo; un proceso no se reinicia
404 al consultarEl proceso no existe, es de otra empresa o es del otro modo (no se distingue)Revisa el id y que uses la llave del mismo modo con que lo creaste
Proceso en FALLIDO o evento validacion_rut.fallidaEl lote falló por una condición de la plataforma y no hay resultadoReintenta el lote entero con un proceso nuevo
COMPLETADO_CON_ERRORESTerminó, pero algunas filas fallaronLee las filas con estado: "FALLIDO" (campo errorMensaje); reprocesa sólo esas en otro proceso
Filas con esValido: falseEl dígito verificador no cuadra; esa fila no se consultóCorrige el RUT en tu origen
available: false en la cotizaciónAlguna métrica del nivel no está en el planElige otro nivel o pide el cambio de plan; no inicies el proceso
503 con API_KEY_VERIFICATION_UNAVAILABLENo se pudo verificar la llave, que no fue rechazadaReintenta tras Retry-After. No la rotes

En producción cada fila se consulta al SII de verdad; lo que cuesta depende de tu plan (redcumbre tarifas iniciarProcesoValidacionRut --produccion) y se registra al completarse el proceso. El cargo base cuenta cada fila, incluidas las repetidas y las inválidas; el cargo de la consulta al SII se aplica sólo a los RUT distintos y válidos que efectivamente se consultaron, y los que la plataforma ya tenía guardados y vigentes (origenDato: "LOCAL" en la fila) no pagan esa consulta. forzarActualizacion: true consulta al SII todas las filas.

  1. Cotiza siempre antes de iniciar. El paso 1 usa la tarifa del plan. Crear el proceso no consulta nada y deja el costo estimado (costoEstimadoClp) en el proceso: úsalo para decidir si se inicia.

  2. Llave de producción. redcumbre pasar-a-produccion --servicios validacion-rut revisa que todo esté en orden, dice qué falta y dónde configurarlo, y recién entonces crea la llave de producción, que 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. Endpoint y secreto de firma de producción, distintos de los de prueba.

  4. Inicio en producción. Los mismos comandos con --produccion; las operaciones que escriben o cobran piden además --confirmar <identificador-de-la-empresa>:

    Ventana de terminal
    redcumbre api crearProcesoValidacionRut --produccion --confirmar <identificador-de-la-empresa> --cuerpo @ruts.json --json
    redcumbre api iniciarProcesoValidacionRut --produccion --confirmar <identificador-de-la-empresa> --param id=<id> --json

    Resultado esperado: 201 con el proceso en EN_COLA y, en el inicio, un bloque cobro con modo: "produccion". El resultado trae datos de personas naturales (nombre y condición de fallecido): guárdalo sólo si lo necesitas.

Más sobre qué cambia entre modos: Modo de prueba y producción.