Consulta de un RUT en el SII
Qué resuelve
Sección titulada «Qué resuelve»Saber qué dice el SII de un RUT antes de usarlo: la razón social de una empresa, sus direcciones y actividades, la casilla donde recibe documentos electrónicos y qué tipos de documento tiene autorizados; o, para una persona natural, su nombre y si el SII la registra como fallecida. Sirve para validar un cliente, un proveedor, un destinatario de boleta o un receptor antes de emitirle.
Es una consulta de un RUT, de respuesta inmediata. Para revisar una lista de RUT o un archivo con miles de filas, la ficha es Validación masiva de RUT.
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. - En producción, la empresa tiene que tener documentos tributarios (DTE) habilitados; si no, la consulta responde
400. En el modo de prueba esa condición no se exige. - Qué cambia entre los modos: Modo de prueba y producción. Forma de los errores y límites: Reglas comunes.
-
Mira qué RUT de prueba hay. Comando:
Ventana de terminal redcumbre escenarios --jsonResultado esperado: código de salida 0 y un JSON con
ruts, una fila por RUT y rol. En el modo de prueba la consulta responde sólo por ese catálogo, sin llamar al SII. Para esta ficha:22222222-2es una persona natural,77777777-7una empresa, y99999999-9está declarado «no encontrado». Cualquier otro RUT válido fuera del catálogo también responde «no encontrado». -
Consulta un RUT. Cuerpo:
{ "rut": "22222222-2" }El RUT va con guión y sin puntos (
12345678-9o12345678-K). Comando:Ventana de terminal redcumbre api consultarRutEnSii --cuerpo '{"rut":"22222222-2"}' --jsonResultado esperado:
200(nunca201: consulta, no crea nada) con esta forma, acortada aquí:{"success": true,"data": {"rut": "22222222-2","razonSocial": "CONTRIBUYENTE DE PRUEBA DOS","tipoContribuyente": "EMPRESA","direcciones": [{ "direccion": "Pasaje de Prueba 222", "comuna": "Ñuñoa", "ciudad": "Santiago" }],"actividadesEconomicas": [{ "codigo": "692000" }],"fechaAutorizacion": null,"portalMipymeHabilitado": false,"emailIntercambio": "contribuyente.dos@ejemplo.rcapi.cl"},"persona": { "nombre": "CONTRIBUYENTE DE PRUEBA DOS", "fallecido": false, "estadoSii": "PERSONA_NATURAL" },"consultaContribuyente": null,"sandbox": true,"cobro": { "modo": "prueba", "mensaje": "En modo de prueba no se cobra." }}La respuesta de prueba no trae
sourcenicacheHit(son de la consulta de producción) yconsultaContribuyenteva ennull. -
Prueba el «no encontrado». Comando:
Ventana de terminal redcumbre api consultarRutEnSii --cuerpo '{"rut":"99999999-9"}' --jsonResultado esperado: sale con código 6 y el error trae
status: 404y el mensaje «No se encontraron datos para el RUT 99999999-9». Un404aquí es un resultado de negocio (el SII no conoce el RUT), no una falla de la plataforma: tu código tiene que tratarlo como «RUT sin datos». -
Lee el resultado como lo hará tu código. Qué mirar en cada bloque:
data: lo que entrega el Portal MiPyme del SII. Lleganullpara una persona natural sin inicio de actividades: en ese caso todo lo conocido viene enpersona. Compruebadata !== nullantes de leerlo.persona: sólo para personas naturales (RUT con cuerpo menor a 50.000.000);nullpara una empresa.fallecidoes una marca, no una fecha, ynullsignifica «no se pudo consultar», nunca «no está fallecida».estadoSiivalePERSONA_NATURAL,PERSONA_FALLECIDA,PERSONA_JURIDICA,RUT_NO_ENCONTRADOoDESCONOCIDO.consultaContribuyente(sólo en producción): la casilla de intercambio (emailContacto) y los documentos autorizados, conautorizadoydesautorizadocomo fechasDD-MM-AAAA. Un documento está vigente sidesautorizadoesnull. El código 890 no es un tipo de documento sino el sistema de boletas del propio SII: verlo desautorizado es normal.data.tipoContribuyente(EMPRESAoPERSONA) es el estado ante el Portal MiPyme, no la naturaleza jurídica. Para saber si el RUT es de una persona natural usapersona.estadoSii.data.giroGlosacasi siempre lleganullpara un tercero: el SII sólo lo entrega cuando se consulta el RUT propio.
-
Úsalo para emitir. El bloque
datasirve de datos del receptor: en una boleta de honorarios de terceros se pasa tal cual comosiiLookup; en una de honorarios propios sólo se usanrut,razonSocial,emaily lasdirecciones(condireccion,codigoComunaycomuna). Ver Boletas de honorarios y Boletas de terceros. Si emites una boleta conlookupRut, la plataforma hace esta misma consulta por ti, con el mismo precio.
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»- La consulta de un RUT del catálogo responde
200consandbox: true, la identidad de prueba de ese RUT ycobro.modo: "prueba". - La del RUT
99999999-9responde404. - En producción, una consulta que salió del SII trae
source: "SII"ycacheHit: false; una servida desde la copia que mantiene la plataforma traecacheHit: truey no consulta al SII.redcumbre consumo --produccionmuestra la métrica de consultas al SII.
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
400 por dígito verificador | El RUT no es válido (se valida igual en los dos modos) | Corrige el RUT; no se consultó nada |
400 «DTE no habilitado» (sólo producción) | La empresa no tiene documentos tributarios habilitados | Es una configuración de la empresa: quien la administra la activa. No la reintentes |
404 con «No se encontraron datos para el RUT …» | Ninguna fuente del SII conoce el RUT. En prueba: un RUT fuera del catálogo o 99999999-9 | Trátalo como «sin datos». Una persona natural sin inicio de actividades no cae aquí: responde 200 con data: null y persona |
500 | Falla interna al consultar el SII | Reintenta con espera creciente; si persiste, repórtalo con el RUT consultado |
503 con API_KEY_VERIFICATION_UNAVAILABLE | No se pudo verificar la llave, que no fue rechazada | Reintenta tras Retry-After. No la rotes |
consultaContribuyente: null en producción | El SII no respondió a la segunda consulta o el RUT no es contribuyente electrónico. La respuesta no falla por eso | Tu código debe aceptarlo y seguir con data |
source: "LOCAL_FALLBACK" | El SII no entregó datos nuevos y se respondió con lo último conocido | Úsalo con cuidado: puede estar desactualizado. forceRefresh: true fuerza una consulta nueva al SII |
Antes de pasar a producción
Sección titulada «Antes de pasar a producción»En producción la consulta va al SII de verdad; lo que cuesta depende de tu plan: redcumbre tarifas consultarRutEnSii --produccion. La plataforma guarda lo que consulta: si el dato tiene menos de 180 días responde desde esa copia (source: "LOCAL", cacheHit: true) sin ir al SII; un dato vencido se consulta de nuevo. forceRefresh: true salta la copia y siempre consulta al SII, así que no lo mandes por defecto.
-
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. -
Documentos tributarios habilitados en la empresa (ver arriba).
-
Primera consulta de producción. Comando:
Ventana de terminal redcumbre api consultarRutEnSii --produccion --cuerpo '{"rut":"<rut-a-consultar>"}' --jsonResultado esperado:
200consandbox: false,sourceycacheHit, y un bloquecobroque dice qué métrica se usó y cuánto queda del plan. Si la consulta cruza el límite incluido en el plan, el CLI se detiene y pide confirmar con--confirmar <identificador-de-la-empresa>. -
Datos de personas. El nombre y la condición de fallecido de una persona natural son datos personales: guárdalos sólo si los necesitas, y no los muestres a quien no corresponde.
Más sobre qué cambia entre modos: Modo de prueba y producción.