Lookup RUT

Lookup RUT

TL;DR - Acceso Rápido

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

👉 Ver endpoint en Swagger

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

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é (< 30 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 30 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 (< 30 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
}

---

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
19673431-7	Persona natural sin inicio de actividades	Éxito
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 solo el bloque data, 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 tres bloques independientes:

• data — datos del contribuyente obtenidos del Portal MiPyme del SII.
• 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.

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	"EMPRESA" o "PERSONA"
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)
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

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

Código	Descripción	Causa
400	DTE no habilitado	El tenant no tiene dteEnabled: true
404	RUT no encontrado	El RUT no existe en el SII o no tiene inicio de actividades
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}" \
  -d '{
    "emisorTributarioId": "...",
    "siiLookup": { ... datos del lookup ... },
    "detalle": "Servicios profesionales",
    "montoTotal": 500000
  }'

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

El lookup de RUT está integrado con el sistema de emisión de BHE. Puedes usar los datos obtenidos directamente con el modo siiLookup al emitir una boleta:

{
  "emisorTributarioId": "...",
  "siiLookup": {
    "rut": "78012039-8",
    "razonSocial": "FIRERAISE SPA",
    "direcciones": [...],
    "actividadesEconomicas": [...]
  },
  "detalle": "Servicios de consultoría",
  "montoTotal": 1000000
}

Esto evita una segunda consulta al SII durante la emisión, optimizando tiempos y costos.

👉 Ver más detalles en Boletas de Honorarios