Validación masiva de RUT
Qué resuelve
Sección titulada «Qué resuelve»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.
| Nivel | Qué entrega cada fila |
|---|---|
PERSONA | Nombre y condición de fallecido. Resuelve personas naturales sin inicio de actividades |
COMPLETO | Lo anterior, más razón social, dirección, comuna, actividades económicas y casilla de intercambio |
Qué necesitas antes
Sección titulada «Qué necesitas antes»- Una llave de prueba conectada al proyecto. Si
keys/redcumbre-prueba.jsonno existe, parte por el arranque o correredcumbre 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
.xlsxcon una columnaruten 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 pormultipart/form-dataen el campoarchivo, y se manda uno de los dos, nunca ambos. La plantilla del archivo se baja condescargarPlantillaValidacionRut. - 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.
-
Cotiza el nivel. Comando:
Ventana de terminal redcumbre api consultarPrecioValidacionRut --param nivel=COMPLETO --jsonResultado esperado:
200con el precio unitario por RUT según el plan de la empresa y sudesglosepor métrica (modelo de cobro, precio fijo por fila y tramos). Si alguna métrica se cobra por tramos (graduatedovolume), por paquete o por dimensión, no tiene un precio fijo por fila: respondeavailable: truesinpricetotal, y esa métrica viene en eldesgloseconprice: nully 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 igual200conavailable: falsey 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. -
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"]}' --jsonResultado esperado:
201con el proceso enestado: "PREPARADO",totalFilas: 4y unid. Este paso sólo cuenta filas y guarda el archivo: no valida ningún RUT y no consulta al SII.forzarActualizacion: truesalta 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 esfalse. -
Inicia el proceso. Comando:
Ventana de terminal redcumbre api iniciarProcesoValidacionRut --param id=<id> --jsonResultado esperado:
201casi de inmediato, sin esperar el procesamiento, con el proceso enEN_COLA. Sólo se puede iniciar un proceso enPREPARADO. 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. -
Sigue el avance. Comando, repetido con espera entre llamadas:
Ventana de terminal redcumbre api consultarProcesoValidacionRut --param id=<id> --jsonResultado esperado: el
estadorecorrePREPARADO,EN_COLA,EN_EJECUCIONy termina en uno deCOMPLETADO,COMPLETADO_CON_ERRORES,CANCELADOoFALLIDO. Los contadores sontotalFilas,filasProcesadas,filasValidas,filasInvalidasyfilasFallidas. CuandotieneResultadoestrue, el archivo de resultado ya se puede descargar. Si perdiste elid,redcumbre api listarProcesosValidacionRut --jsonlista los procesos de la empresa (admite--param estado=y--param nivel=). En vez de consultar en bucle, suscríbete avalidacion_rut.completadayvalidacion_rut.fallida: el primero traeprocesoId,estado, los contadores ytieneResultado; el segundo,error, y avisa que no hay resultado y que conviene reintentar el lote entero. -
Lee el resultado fila por fila. Comando:
Ventana de terminal redcumbre api listarFilasProcesoValidacionRut --param id=<id> --jsonResultado esperado:
200condata(una fila por RUT, en el orden del archivo) ymeta(total,limit,offset). Cada fila traerutOriginal(como lo enviaste),rutCanonico,esValido(si el dígito verificador cuadra),estado(PENDIENTE,PROCESADOoFALLIDO),datosSalidayorigenDato(SIIoLOCAL). EndatosSalida,tipoContribuyentees lo que respondió el SII:PERSONA_NATURAL,PERSONA_FALLECIDA,PERSONA_JURIDICA,RUT_NO_ENCONTRADOoDESCONOCIDO;fallecidoes una marca, no una fecha. En el ejemplo, las dos primeras filas salenPERSONA_NATURAL, la terceraRUT_NO_ENCONTRADO, y la cuarta conesValido: false. -
Descarga el archivo si lo necesitas. Comando:
Ventana de terminal redcumbre api descargarResultadoValidacionRut --param id=<id> --salida resultado.xlsxResultado 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.descargarArchivoOriginalValidacionRutdevuelve el archivo tal como se subió. -
Cancela si hace falta. Comando:
Ventana de terminal redcumbre api cancelarProcesoValidacionRut --param id=<id> --jsonResultado esperado: sólo funciona con el proceso en
EN_COLAoEN_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.
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»- El proceso llegó a
COMPLETADO(oCOMPLETADO_CON_ERRORES, que sigue siendo un término con resultado: mirafilasFallidasy las filas conestado: "FALLIDO") ytieneResultadoestrue. filasProcesadasalcanza lo esperado y cada fila delistarFilasProcesoValidacionRuttieneestado: "PROCESADO"o su motivo de falla.- Tu receptor recibió
validacion_rut.completadaconsandbox: 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_ENCONTRADOes un resultado válido, no un error del proceso.
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
400 al crear: «Envía un archivo … o una lista …» | No mandaste ni archivo ni ruts, o mandaste los dos | Envía exactamente uno |
400 al crear por exceder 5.000 filas, o ruts vacío | El lote no cabe o no tiene contenido | Divide el lote en procesos de hasta 5.000 |
400 al iniciar con MODO_PRUEBA_TOPE_DIARIO | El lote no cabe en el tope diario de prueba (200 RUT, cuenta uno por fila) y se rechaza entero, sin tocar ninguna fila | Reduce el lote o espera hasta las 00:00 de Chile. redcumbre estado dice cuánto queda |
Error al iniciar un proceso que no está PREPARADO | Ya se inició, terminó o se canceló | Crea uno nuevo; un proceso no se reinicia |
404 al consultar | El 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.fallida | El lote falló por una condición de la plataforma y no hay resultado | Reintenta el lote entero con un proceso nuevo |
COMPLETADO_CON_ERRORES | Terminó, pero algunas filas fallaron | Lee las filas con estado: "FALLIDO" (campo errorMensaje); reprocesa sólo esas en otro proceso |
Filas con esValido: false | El dígito verificador no cuadra; esa fila no se consultó | Corrige el RUT en tu origen |
available: false en la cotización | Alguna métrica del nivel no está en el plan | Elige otro nivel o pide el cambio de plan; no inicies el proceso |
503 con API_KEY_VERIFICATION_UNAVAILABLE | No se pudo verificar la llave, que no fue rechazada | Reintenta tras Retry-After. No la rotes |
Antes de pasar a producción
Sección titulada «Antes de pasar a producción»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.
-
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. -
Llave de producción.
redcumbre pasar-a-produccion --servicios validacion-rutrevisa 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 enkeys/redcumbre-produccion.json. -
Webhooks de producción. Endpoint y secreto de firma de producción, distintos de los de prueba.
-
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 --jsonredcumbre api iniciarProcesoValidacionRut --produccion --confirmar <identificador-de-la-empresa> --param id=<id> --jsonResultado esperado:
201con el proceso enEN_COLAy, en el inicio, un bloquecobroconmodo: "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.