Lookup RUT

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:

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

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
SII falla pero hay datos locales	Sí	`LOCAL_FALLBACK`

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)

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

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`

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

Respuesta Exitosa (200)

{
  "success": true,
  "data": {
    "rut": "78012039-8",
    "razonSocial": "FIRERAISE SPA",
    "giroGlosa": null,
    "tipoContribuyente": "EMPRESA",
    "fechaAutorizacion": "2021-09-27",
    "portalMipymeHabilitado": true,
    "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"
      }
    ],
    "actividadesEconomicas": [
      {
        "codigo": "620900",
        "descripcion": "OTRAS ACTIVIDADES DE TECNOLOGÍA DE LA INFORMACIÓN Y DE SERVICIOS INFORMÁTICOS"
      }
    ]
  },
  "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 (puede ser null en lookup normal)
`data.tipoContribuyente`	string	`"EMPRESA"` o `"PERSONA"`
`data.fechaAutorizacion`	string	Fecha de autorización en SII (YYYY-MM-DD)
`data.portalMipymeHabilitado`	boolean	Si tiene acceso al Portal Mipyme del SII
`data.direcciones`	array	Lista de direcciones registradas
`data.actividadesEconomicas`	array	Lista de actividades económicas (ACTECO)
`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

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

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