Lookup RUT: consulta de contribuyentes

TL;DR - Acceso Rápido

Endpoint: POST /{tenantSlug}/herramientas/lookup-rut

👉 Ver endpoint en Swagger

El endpoint de Lookup RUT permite consultar información de cualquier RUT chileno directamente desde el SII. Los datos incluyen razón social, direcciones, actividades económicas, fecha de autorización y más.

Para una persona natural consulta además el carril de personas del SII, que resuelve su nombre y si está fallecida — incluso cuando no tiene inicio de actividades, caso en el que el resto del SII no sabe nada de ella.

El sistema implementa un caché inteligente que evita consultas innecesarias al SII, optimizando costos y tiempos de respuesta.

---

Requisitos Previos

Antes de usar el endpoint necesitas:

1. Una API Key con uno de estos roles: ADMIN, SUPER-ADMIN, o FULL-API
2. El tenant debe tener DTE habilitado (dteEnabled: true)

Importante

El lookup usa internamente un emisor MASTER para autenticarse con el SII. Esto es transparente para el usuario y no requiere configuración adicional.

---

Sistema de Caché y Billing

El sistema mantiene un repositorio maestro de contribuyentes (ContribuyenteMaestro) que actúa como caché. Esto significa que no todas las consultas generan cobro.

Cuándo se Cobra

Escenario	¿Cobra?	Campo source
Datos frescos en caché (< 180 días)	No	LOCAL
Datos vencidos → consulta al SII	Sí	SII
Modo Sandbox activo	No	N/A
El SII responde sin datos, pero hay datos locales	Sí	LOCAL_FALLBACK
No se pudo alcanzar al SII (red, timeout, 5xx)	No	LOCAL_FALLBACK

Un lookup que no llegó al SII no se cobra

LOCAL_FALLBACK cubre dos situaciones distintas: que el SII haya respondido y no tenga datos del RUT, o que no hayamos podido llegar al SII. Solo la primera se cobra — si no hubo consulta, no hay servicio prestado que facturar.

Optimización de Costos

Si consultas el mismo RUT múltiples veces dentro de 180 días, solo la primera consulta genera cobro. Las siguientes usan el caché local.

Flujo de Decisión

POST /herramientas/lookup-rut
           │
           ▼
  ¿Modo Sandbox? ───SÍ───▶ Retorna fixture (NO billing)
           │ NO
           ▼
  ¿DTE habilitado? ───NO───▶ Error 400
           │ SÍ
           ▼
  ¿Caché fresco (< 180 días)? ─SÍ─▶ Retorna del caché
           │ NO                     (NO billing)
           ▼
     Consulta al SII
       (BILLABLE)
           │
           ▼
  Sincroniza con repositorio maestro
           │
           ▼
  Retorna datos + registra evento billing

Campos de Respuesta Relacionados

La respuesta incluye campos que indican el origen de los datos:

• source: "SII" | "LOCAL" | "LOCAL_FALLBACK" - De dónde provienen los datos
• cacheHit: true | false - Si se usó el caché (no hubo consulta al SII)

Forzar consulta al SII

Si necesitas datos frescos sí o sí (por ejemplo, el contribuyente acaba de cambiar su casilla de intercambio), envía forceRefresh: true en el body. Salta el caché, consulta al SII y siempre se cobra.

{
  "rut": "78012039-8",
  "forceRefresh": true
}

---

Personas naturales y empresas

El RUT decide a qué fuentes se pregunta. El corte está en el cuerpo del RUT (la parte antes del guión):

Cuerpo del RUT	Qué se consulta	Bloques de la respuesta
Desde 50.000.000 — persona jurídica	Sólo el carril tributario	data
Bajo 50.000.000 — persona natural	El carril tributario y el de personas	data + persona

En una empresa el carril de personas no aporta nada, así que no se ejercita y persona llega null.

Una persona natural puede tener giro comercial o no tenerlo, y eso cambia lo que llega:

Caso	data	persona
Persona natural con inicio de actividades	Poblado	Poblado
Persona natural sin inicio de actividades	null	Poblado
Ningún registro del RUT en el SII	—	— (responde 404)

data puede llegar en null

Para una persona natural sin inicio de actividades el Portal MiPyme no tiene absolutamente nada que entregar: no hay razón social, ni dirección, ni actividades. Todo lo que se sabe de ella viaja en persona. Si tu integración asume que data siempre viene, agrégale la comprobación.

Antes este caso respondía 404. El 404 quedó reservado para cuando ninguna de las dos fuentes conoce el RUT.

El bloque persona

Campo	Tipo	Descripción
nombre	string | null	Nombre completo de la persona natural
fallecido	boolean | null	Si el SII la registra como fallecida
estadoSii	string | null	PERSONA_NATURAL, PERSONA_FALLECIDA, PERSONA_JURIDICA, RUT_NO_ENCONTRADO o DESCONOCIDO

{
  "success": true,
  "data": null,
  "persona": {
    "nombre": "SOTO RAMIREZ CAMILA ANDREA",
    "fallecido": false,
    "estadoSii": "PERSONA_NATURAL"
  },
  "consultaContribuyente": null,
  "source": "SII",
  "cacheHit": false
}

fallecido es una marca, no una fecha

El SII entrega la condición pero no la fecha de defunción, así que no hay forma de saber desde cuándo. Y un null en ese campo significa no se pudo consultar — nunca no está fallecida.

La clasificación por rango decide a quién preguntar, no qué responder

El corte en 50.000.000 es una convención de asignación de RUT, no una regla publicada del SII. Cuando la fuente contradice al rango —responde PERSONA_JURIDICA para un RUT bajo el umbral— manda la fuente, y eso se lee en persona.estadoSii.

No cambia lo que pagas

El bloque persona no agrega ningún cargo. Las métricas del lookup son las mismas de antes de que existiera: si la consulta salió del caché, sigue sin costar nada.

---

Modo Sandbox (Testing)

El modo sandbox permite probar la integración sin realizar consultas reales al SII y sin generar cobros.

Activación

El modo sandbox se activa automáticamente cuando tu API Key tiene el flag isSandbox: true configurado en sus metadata.

RUTs de Prueba Disponibles

RUT	Descripción	Resultado
78012039-8	FIRERAISE SPA - Empresa completa con todos los datos	Éxito
77425402-1	LA GRANJERA LIMITADA - Múltiples direcciones y sucursales	Éxito
13830230-k	Persona natural con inicio de actividades	Éxito — data + persona
19673431-7	Persona natural con datos tributarios, sin actividades económicas	Éxito — data + persona
20111222-0	Persona natural sin inicio de actividades	Éxito — data: null, sólo persona
9876543-5	Persona natural fallecida, sin inicio de actividades	Éxito — data: null, persona.fallecido: true
22222222-2	Empresa con datos parciales (sin giro)	Éxito
11111111-1	Empresa sin Portal Mipyme habilitado	Éxito
99999999-9	RUT no encontrado	Error 404

Solo RUTs de Prueba

En modo sandbox, solo los RUTs listados arriba retornan datos. Cualquier otro RUT retorna un error indicando los RUTs disponibles.

La respuesta sandbox no es idéntica a la de producción

En sandbox la respuesta trae sandbox: true y no incluye consultaContribuyente, source ni cacheHit: los fixtures cubren los bloques data y persona, y dentro de data tampoco traen emailIntercambio. Si tu integración depende de la casilla de intercambio o de los documentos autorizados, esa parte debe probarse contra producción.

---

Request

Endpoint

POST /{tenantSlug}/herramientas/lookup-rut

Headers

Authorization: Bearer {api_key}
Content-Type: application/json

Body

{
  "rut": "78012039-8"
}

Campo	Tipo	Requerido	Descripción
rut	string	Sí	RUT a consultar en formato 12345678-9
forceRefresh	boolean	No	true ignora el caché y consulta al SII (siempre cobrable). Por defecto false

Formato del RUT

El RUT debe enviarse con guión y sin puntos: 12345678-9 o 12345678-K

Ejemplo con curl

curl -X POST "https://api.redcumbre.cl/{tenantSlug}/herramientas/lookup-rut" \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "rut": "78012039-8"
  }'

---

Response

La respuesta trae cuatro bloques independientes:

• data — datos del contribuyente obtenidos del Portal MiPyme del SII. null para una persona natural sin inicio de actividades.
• persona — nombre y condición de fallecido de una persona natural. null para una empresa. Ver Personas naturales y empresas.
• consultaContribuyente — datos del registro de contribuyentes electrónicos del SII: casilla de intercambio, resolución que autoriza a emitir DTE y documentos autorizados.
• source / cacheHit — trazabilidad del origen de los datos.

Una consulta exitosa responde 200 OK, nunca 201: el lookup consulta datos, no crea ningún recurso. Si tu integración valida el código de estado, compáralo contra 200.

Respuesta Exitosa (200)

{
  "success": true,
  "data": {
    "rut": "78012039-8",
    "razonSocial": "FIRERAISE SPA",
    "giroGlosa": null,
    "tipoContribuyente": "EMPRESA",
    "fechaAutorizacion": "2021-09-27",
    "portalMipymeHabilitado": true,
    "emailIntercambio": "intercambio@firemail.cl",
    "direcciones": [
      {
        "direccion": "LOS PEUMOS ST. 3 LT B",
        "comuna": "BULNES",
        "codigoComuna": "16108",
        "ciudad": "",
        "codigoSucursal": "90866365",
        "unidadSii": {
          "direccionRegional": "Dirección Regional de Ñuble",
          "nombreCorto": "DR Ñuble",
          "codigoRegion": "16",
          "unidad": "Unidad de Chillán"
        },
        "comunaId": 101,
        "comunaBheId": 8402,
        "comunaSiiId": "16108",
        "regionId": 16,
        "regionNombre": "Ñuble",
        "origen": "SII"
      }
    ],
    "actividadesEconomicas": [
      {
        "codigo": "620900",
        "descripcion": "OTRAS ACTIVIDADES DE TECNOLOGÍA DE LA INFORMACIÓN Y DE SERVICIOS INFORMÁTICOS"
      }
    ],
    "emails": [],
    "telefonos": [],
    "contactos": []
  },
  "consultaContribuyente": {
    "rut": "78012039-8",
    "razonSocial": "FIRERAISE SPA",
    "nroResolucion": "80",
    "fechaResolucion": "22-08-2014",
    "emailContacto": "intercambio@firemail.cl",
    "documentos": [
      {
        "codigo": 33,
        "descripcion": "FACTURA ELECTRONICA",
        "autorizado": "28-12-2024",
        "desautorizado": null
      },
      {
        "codigo": 61,
        "descripcion": "NOTA CREDITO ELECTRONICA",
        "autorizado": "28-12-2024",
        "desautorizado": null
      },
      {
        "codigo": 890,
        "descripcion": "SIST. SII DE EMISIÓN DE BOLETAS ELECTRÓNICAS",
        "autorizado": "05-09-2022",
        "desautorizado": "19-12-2022"
      }
    ]
  },
  "source": "SII",
  "cacheHit": false
}

Campos de la Respuesta

Campo	Tipo	Descripción
success	boolean	Indica si la operación fue exitosa
data.rut	string	RUT consultado
data.razonSocial	string	Nombre o razón social del contribuyente
data.giroGlosa	string | null	Giro comercial. El SII solo lo entrega en lookup auto-referencial, por eso normalmente llega null
data.tipoContribuyente	string	Estado ante el Portal MiPyme, no naturaleza jurídica. "PERSONA" cubre dos condiciones que el SII reporta por separado: sin inicio de actividades, o no habilitado para recibir documentos electrónicos. Para saber si el RUT es de una persona natural, usa persona.estadoSii
data.fechaAutorizacion	string | null	Fecha de autorización en SII (YYYY-MM-DD)
data.portalMipymeHabilitado	boolean	Si tiene acceso al Portal Mipyme del SII
data.emailIntercambio	string | null	Casilla de intercambio DTE (ver sección siguiente)
data.direcciones	array	Lista de direcciones registradas
data.actividadesEconomicas	array	Lista de actividades económicas (ACTECO)
data.emails	array	Emails cargados en la plataforma (el SII no entrega emails)
data.telefonos	array	Teléfonos cargados en la plataforma
data.contactos	array	Contactos unificados (nombre + email + teléfono)
persona	object | null	Nombre y condición de fallecido de una persona natural. null en una empresa
persona.nombre	string | null	Nombre completo. Es el único lugar donde llega el de quien no tiene inicio de actividades
persona.fallecido	boolean | null	Marca, no fecha. null = no se pudo consultar
persona.estadoSii	string | null	Veredicto del SII: PERSONA_NATURAL, PERSONA_FALLECIDA, PERSONA_JURIDICA, RUT_NO_ENCONTRADO, DESCONOCIDO
consultaContribuyente	object | null	Registro de contribuyentes electrónicos del SII (ver sección siguiente)
source	string	Origen de los datos: SII, LOCAL, LOCAL_FALLBACK
cacheHit	boolean	true si los datos vinieron del caché local

giroGlosa normalmente llega null

El SII solo entrega el giro cuando el RUT consultado es el mismo del certificado que hace la consulta. Para cualquier otro contribuyente —que es el caso al facturarle a un cliente— llega null: en el repositorio maestro, dos de cada tres RUT consultados no tienen giro.

Como receptor.giro es obligatorio para emitir una factura, la receta para resolverlo está en Emitir un DTE — el giro del receptor.

Estructura de Dirección

Campo	Tipo	Descripción
direccion	string	Dirección completa
comuna	string	Nombre de la comuna
codigoComuna	string	Código SII de la comuna
ciudad	string	Ciudad (puede estar vacío)
codigoSucursal	string	Código de sucursal SII
unidadSii	object	Información de la unidad SII correspondiente
comunaId	number	ID interno de comuna
comunaBheId	number	ID de comuna para BHE
comunaSiiId	string	Código SII de la comuna
regionId	number	ID de la región
regionNombre	string	Nombre de la región
origen	string	"SII" (obtenida del SII) o "PERSONALIZADA" (agregada manualmente, no la pisa el SII)

Estructura de Actividad Económica

Campo	Tipo	Descripción
codigo	string	Código ACTECO (6 dígitos)
descripcion	string	Descripción de la actividad económica

---

Casilla de Intercambio y Documentos Autorizados

Además de los datos del Portal MiPyme, el lookup consulta el registro de contribuyentes electrónicos del SII y devuelve el resultado en el bloque consultaContribuyente.

Enriquecimiento best-effort

Si el SII no responde a esta segunda consulta, consultaContribuyente llega en null y el resto de la respuesta se entrega igual. Nunca hace fallar el lookup.

Campos de consultaContribuyente

Campo	Tipo	Descripción
rut	string | null	RUT del contribuyente
razonSocial	string | null	Razón social según el registro de contribuyentes electrónicos
nroResolucion	string | null	Número de la resolución del SII que lo autoriza a emitir documentos electrónicos
fechaResolucion	string | null	Fecha de la resolución, formato DD-MM-AAAA
emailContacto	string | null	Casilla de intercambio publicada en el SII
documentos	array	Tipos de documento autorizados (ver abajo)

Casilla de intercambio

consultaContribuyente.emailContacto es la casilla que el contribuyente declaró ante el SII para recibir DTE y devolver los acuses de recibo. El mismo valor se replica en data.emailIntercambio para tenerlo a mano junto al resto de los datos del contribuyente.

Si el contribuyente no publicó casilla en el SII, ambos campos llegan en null.

Documentos autorizados

Cada entrada de consultaContribuyente.documentos indica desde cuándo el contribuyente puede emitir ese tipo de documento y, si corresponde, desde cuándo dejó de poder hacerlo.

Campo	Tipo	Descripción
codigo	number	Código del documento según el SII (33 = factura electrónica, 61 = nota de crédito, etc.)
descripcion	string	Nombre del documento según el SII
autorizado	string | null	Fecha desde la que está autorizado, formato DD-MM-AAAA
desautorizado	string | null	Fecha desde la que dejó de estarlo, formato DD-MM-AAAA. null si sigue vigente

Ambas fechas son fechas, no banderas

autorizado y desautorizado son fechas en formato DD-MM-AAAA tal como las publica el SII, no booleanos. Para saber si un documento está vigente hoy, la regla es desautorizado === null.

El código 890 no es un DTE

Los códigos sobre 800 no son tipos de documento tributario sino sistemas del SII. En particular, el 890 (SIST. SII DE EMISIÓN DE BOLETAS ELECTRÓNICAS) aparece desautorizado en muchos contribuyentes que migraron del portal del SII a un facturador externo. Eso no significa que el contribuyente esté inhabilitado.

Validar antes de emitir

El uso típico es verificar que el receptor puede recibir el tipo de DTE que vas a emitirle:

const { consultaContribuyente } = await lookupRut('78012039-8');

const puedeRecibirFactura = consultaContribuyente?.documentos.some(
  (doc) => doc.codigo === 33 && doc.desautorizado === null
);

if (!puedeRecibirFactura) {
  throw new Error('El receptor no está autorizado para factura electrónica');
}

---

Códigos de Error

La consulta exitosa responde 200 OK. Estos códigos indican que algo falló:

Código	Descripción	Causa
400	DTE no habilitado	El tenant no tiene dteEnabled: true
404	RUT no encontrado	Ninguna de las dos fuentes del SII conoce el RUT. Una persona natural sin inicio de actividades ya no cae acá: responde 200 con data: null y el bloque persona
500	Error interno	Error en servicios internos

Ejemplo de Error 404

{
  "statusCode": 404,
  "message": "No se encontraron datos para el RUT 99999999-9",
  "error": "Not Found"
}

---

Casos de Uso

Validar Destinatario antes de Emitir BHE

Antes de emitir una Boleta de Honorarios, puedes validar que el destinatario existe en el SII:

# 1. Consultar datos del destinatario
curl -X POST "https://api.redcumbre.cl/{tenant}/herramientas/lookup-rut" \
  -H "Authorization: Bearer {api_key}" \
  -d '{"rut": "76123456-7"}'

# 2. Si existe, usar los datos para emitir la BHE con modo siiLookup
curl -X POST "https://api.redcumbre.cl/{tenant}/bhe" \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "emisorTributarioId": "tu-emisor-tributario-id",
    "sinDestinatario": false,
    "siiLookup": {
      "rut": "76123456-7",
      "razonSocial": "EMPRESA CLIENTE SA",
      "direcciones": [
        {
          "direccion": "AV PROVIDENCIA 1234 OF 501",
          "codigoComuna": "13101",
          "comuna": "SANTIAGO"
        }
      ]
    },
    "prestaciones": [
      { "descripcion": "Servicios profesionales", "valor": "500000" }
    ],
    "tipoRetencion": "RETRECEPTOR"
  }'

El monto va en prestaciones, y valor es un string

No existen detalle ni montoTotal. El detalle y el monto viajan juntos en cada ítem de prestaciones (descripcion + valor), y valor se envía como string, no como número. El bruto es la suma de las prestaciones; la retención la calcula la plataforma.

Obtener Datos Fiscales de un Cliente

Para mostrar información fiscal de un cliente en tu aplicación:

const response = await fetch(`https://api.redcumbre.cl/${tenant}/herramientas/lookup-rut`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ rut: '78012039-8' })
});

const { data, cacheHit } = await response.json();

console.log(`Razón Social: ${data.razonSocial}`);
console.log(`Actividad: ${data.actividadesEconomicas[0]?.descripcion}`);
console.log(`Dirección: ${data.direcciones[0]?.direccion}, ${data.direcciones[0]?.comuna}`);
console.log(`Datos desde caché: ${cacheHit ? 'Sí' : 'No'}`);

---

Integración con BHE y BHET

El lookup de RUT está integrado con la emisión de BHE y BHET: el bloque data de la respuesta se pasa como siiLookup y evita una segunda consulta al SII durante la emisión.

Los dos endpoints no aceptan el mismo objeto. BHET declara el lookup completo; BHE declara sólo el núcleo. Es una asimetría real del contrato, y conviene conocerla antes de reutilizar el mismo código para ambos.

En BHE: sólo el núcleo del lookup

POST /{tenantSlug}/bhe usa cuatro campos —rut, razonSocial, email y direcciones— y de cada dirección sólo direccion, codigoComuna y comuna.

{
  "emisorTributarioId": "tu-emisor-tributario-id",
  "sinDestinatario": false,
  "siiLookup": {
    "rut": "78012039-8",
    "razonSocial": "FIRERAISE SPA",
    "direcciones": [
      {
        "direccion": "LOS PEUMOS ST. 3 LT B",
        "codigoComuna": "16108",
        "comuna": "BULNES"
      }
    ]
  },
  "prestaciones": [
    { "descripcion": "Servicios de consultoría", "valor": "1000000" }
  ],
  "tipoRetencion": "RETRECEPTOR"
}

Obligatorios: rut, razonSocial y al menos una entrada en direcciones con direccion, codigoComuna y comuna. email es opcional.

En BHE los campos extra del lookup se descartan en silencio

Si le pasas a BHE el data completo del lookup, la emisión funciona y responde 2xx: los campos que el contrato de BHE no declara se descartan antes de llegar al handler. No se guardan, no viajan al SII y no obtienes un 400 que te avise.

Sobre el objeto de más abajo son doce los que se pierden: tipoContribuyente, fechaAutorizacion, portalMipymeHabilitado, actividadesEconomicas, y dentro de cada dirección ciudad, codigoSucursal, comunaId, comunaBheId, comunaSiiId, regionId, regionNombre y origen.

Manda a BHE sólo los campos del contrato. Si necesitas el resto del lookup, guárdalo de tu lado.

En BHET: el objeto completo del lookup

POST /{tenantSlug}/bhet declara el lookup entero, así que ahí sí puedes pasar el data de la respuesta tal cual, sin transformarlo ni podarlo. Lo que acepta BHET es un superconjunto de lo que acepta BHE.

{
  "emisorTributarioId": "tu-emisor-tributario-id",
  "siiLookup": {
    "rut": "78012039-8",
    "razonSocial": "FIRERAISE SPA",
    "tipoContribuyente": "EMPRESA",
    "fechaAutorizacion": "2021-09-27",
    "portalMipymeHabilitado": true,
    "direcciones": [
      {
        "direccion": "LOS PEUMOS ST. 3 LT B",
        "comuna": "BULNES",
        "codigoComuna": "16108",
        "ciudad": "",
        "codigoSucursal": "90866365",
        "comunaId": 101,
        "comunaBheId": 8402,
        "comunaSiiId": "16108",
        "regionId": 16,
        "regionNombre": "Ñuble",
        "origen": "SII"
      }
    ],
    "actividadesEconomicas": [
      {
        "codigo": "620900",
        "descripcion": "OTRAS ACTIVIDADES DE TECNOLOGÍA DE LA INFORMACIÓN Y DE SERVICIOS INFORMÁTICOS"
      }
    ]
  },
  "prestaciones": [
    { "descripcion": "Servicios de consultoría", "valor": "1000000" }
  ]
}

Una BHET no lleva sinDestinatario ni tipoRetencion: siempre tiene tercero. Ver Boletas de Terceros.

El listado de campos con sus tipos, para ambos endpoints, está en Swagger.

👉 Ver más detalles en Boletas de Honorarios