Ir al contenido

Consulta de un RUT en el SII

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.

  • 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.
  • 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.
  1. Mira qué RUT de prueba hay. Comando:

    Ventana de terminal
    redcumbre escenarios --json

    Resultado 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-2 es una persona natural, 77777777-7 una empresa, y 99999999-9 está declarado «no encontrado». Cualquier otro RUT válido fuera del catálogo también responde «no encontrado».

  2. Consulta un RUT. Cuerpo:

    { "rut": "22222222-2" }

    El RUT va con guión y sin puntos (12345678-9 o 12345678-K). Comando:

    Ventana de terminal
    redcumbre api consultarRutEnSii --cuerpo '{"rut":"22222222-2"}' --json

    Resultado esperado: 200 (nunca 201: 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 source ni cacheHit (son de la consulta de producción) y consultaContribuyente va en null.

  3. Prueba el «no encontrado». Comando:

    Ventana de terminal
    redcumbre api consultarRutEnSii --cuerpo '{"rut":"99999999-9"}' --json

    Resultado esperado: sale con código 6 y el error trae status: 404 y el mensaje «No se encontraron datos para el RUT 99999999-9». Un 404 aquí 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».

  4. Lee el resultado como lo hará tu código. Qué mirar en cada bloque:

    • data: lo que entrega el Portal MiPyme del SII. Llega null para una persona natural sin inicio de actividades: en ese caso todo lo conocido viene en persona. Comprueba data !== null antes de leerlo.
    • persona: sólo para personas naturales (RUT con cuerpo menor a 50.000.000); null para una empresa. fallecido es una marca, no una fecha, y null significa «no se pudo consultar», nunca «no está fallecida». estadoSii vale PERSONA_NATURAL, PERSONA_FALLECIDA, PERSONA_JURIDICA, RUT_NO_ENCONTRADO o DESCONOCIDO.
    • consultaContribuyente (sólo en producción): la casilla de intercambio (emailContacto) y los documentos autorizados, con autorizado y desautorizado como fechas DD-MM-AAAA. Un documento está vigente si desautorizado es null. El código 890 no es un tipo de documento sino el sistema de boletas del propio SII: verlo desautorizado es normal.
    • data.tipoContribuyente (EMPRESA o PERSONA) es el estado ante el Portal MiPyme, no la naturaleza jurídica. Para saber si el RUT es de una persona natural usa persona.estadoSii.
    • data.giroGlosa casi siempre llega null para un tercero: el SII sólo lo entrega cuando se consulta el RUT propio.
  5. Úsalo para emitir. El bloque data sirve de datos del receptor: en una boleta de honorarios de terceros se pasa tal cual como siiLookup; en una de honorarios propios sólo se usan rut, razonSocial, email y las direcciones (con direccion, codigoComuna y comuna). Ver Boletas de honorarios y Boletas de terceros. Si emites una boleta con lookupRut, la plataforma hace esta misma consulta por ti, con el mismo precio.

  • La consulta de un RUT del catálogo responde 200 con sandbox: true, la identidad de prueba de ese RUT y cobro.modo: "prueba".
  • La del RUT 99999999-9 responde 404.
  • En producción, una consulta que salió del SII trae source: "SII" y cacheHit: false; una servida desde la copia que mantiene la plataforma trae cacheHit: true y no consulta al SII. redcumbre consumo --produccion muestra la métrica de consultas al SII.
Si vesSignificaQué haces
400 por dígito verificadorEl 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 habilitadosEs 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-9Trátalo como «sin datos». Una persona natural sin inicio de actividades no cae aquí: responde 200 con data: null y persona
500Falla interna al consultar el SIIReintenta con espera creciente; si persiste, repórtalo con el RUT consultado
503 con API_KEY_VERIFICATION_UNAVAILABLENo se pudo verificar la llave, que no fue rechazadaReintenta tras Retry-After. No la rotes
consultaContribuyente: null en producciónEl SII no respondió a la segunda consulta o el RUT no es contribuyente electrónico. La respuesta no falla por esoTu 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

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.

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

  2. Documentos tributarios habilitados en la empresa (ver arriba).

  3. Primera consulta de producción. Comando:

    Ventana de terminal
    redcumbre api consultarRutEnSii --produccion --cuerpo '{"rut":"<rut-a-consultar>"}' --json

    Resultado esperado: 200 con sandbox: false, source y cacheHit, y un bloque cobro que 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>.

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