Autenticación SII - Método RUT/Clave

La mayoría de las consultas al SII requieren autenticación. El método más simple es usar el RUT y contraseña del contribuyente. API Gateway actúa como intermediario, enviando estas credenciales al SII de forma segura para obtener los datos solicitados.

Conceptos Clave

¿Por qué POST para consultas?

Aunque estemos “consultando” información, usamos POST porque:

Necesitamos enviar credenciales en el body
Las credenciales no deben ir en la URL
Es más seguro que GET con parámetros

Caché de Sesión

API Gateway mantiene la sesión del SII activa por 2 horas para:

Mejorar velocidad de respuesta
Evitar bloqueos por múltiples inicios de sesión
Optimizar el uso de recursos

Estructura del Objeto auth.pass

Formato JSON

{
  "auth": {
    "pass": {
      "rut": "11111111-1",
      "clave": "mi_clave_sii"
    }
  }
}

Componentes

Campo	Formato	Ejemplo	Descripción
`rut`	String	“76192083-9”	Sin puntos, con guión
`clave`	String	“miClave123”	Contraseña del SII

Endpoint de Prueba: Situación Tributaria

Descripción

Consultaremos la situación tributaria de un contribuyente - información básica y pública una vez autenticado.

Endpoint

POST /api/v1/sii/bhe/emitidas/documentos/{emisor}/{periodo}

¿Por qué este endpoint?

✅ Respuesta simple y útil
✅ Permite verificar autenticación
✅ Bajo riesgo de errores

Paso a Paso en Swagger

1. Localizar el Endpoint

En Swagger, busca la sección “API Boletas de Honorarios (BHE)”
Encuentra POST /sii/bhe/emitidas/documentos/{emisor}/{periodo}
Expande el endpoint

2. Revisar la Documentación

Lee la descripción que indica:

Qué información retorna
Parámetros requeridos
Posibles respuestas

3. Activar “Try it out”

Haz clic en el botón para habilitar la edición

4. Configurar Parámetros

Query Parameters

emisor: 11111111-1  (RUT del emisor a consultar)
periodo: 2024-01

Request Body

{
  "auth": {
    "pass": {
      "rut": "11111111-1",
      "clave": "tu_clave_sii"
    }
  }
}

Nota: El RUT en query es el emisor a consultar. El RUT en auth es quien hace la consulta. En este caso coincide el RUT del emisor con el RUT del contribuyente que hace la consulta.

5. Ejecutar

Clic en “Execute” y espera la respuesta

Interpretando la Respuesta

Respuesta Exitosa (200 OK)

{
    "n_boletas": 9,
    "n_paginas": 1,
    "boletas": [
        {
            "numero": 133,
            "rut": 76111111,
            "dv": "9",
            "nombre": "TESTING SPA",
            "fecha": "2025-07-14",
            "total_honorarios": 1000,
            "retencion_emisor": 0,
            "retencion_receptor": 145,
            "total_liquido": 855,
            "sociedad_profesional": "NO",
            "estado": "S",
            "anulada": "2025-07-14",
            "codigo": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "fecha_emision": "2025-07-14",
            "usuario_emisor": "TESTING USER",
            "email_envio": ""
        },
    ]
}

Campos Importantes

Campo	Descripción
`numero`	Número de la boleta
`rut`	RUT del receptor
`dv`	Dígito verificador del RUT del receptor
`nombre`	Nombre o razón social del receptor
`fecha`	Fecha de emisión de la boleta
`total_honorarios`	Total de honorarios
`retencion_emisor`	Retención del emisor
`retencion_receptor`	Retención del receptor
`total_liquido`	Total líquido
`sociedad_profesional`	Si es sociedad profesional

Manejo de Errores

Error 401: Credenciales Incorrectas

{
  "code": 401,
  "message": "No se pudo autenticar con las credenciales proporcionadas"
}

Causas:

RUT o contraseña incorrectos
Formato de RUT incorrecto
Credenciales incorrectas

Solución:

Verifica credenciales en www.sii.cl
Revisa formato del RUT (con guión, sin puntos)

Error 401: Sesión Expirada

{
  "code": 401,
  "message": "Se debe volver a autenticar al usuario en la sesión del SII."
}

Headers de respuesta:

X-Stats-NavegadorSessionProblem: 1

Solución: Agregar ?auth_cache=0 a la URL para forzar nueva sesión

Control de Caché de Sesión

Comportamiento por Defecto

Sesión se mantiene por 2 horas
Se reutiliza automáticamente
Mejora performance significativamente

Forzar Nueva Sesión

Agrega a la URL:

?auth_cache=0

Cuándo usarlo:

Error de sesión persistente
Cambio de contraseña reciente
Debugging de problemas

Ejemplo completo:

POST /api/v1/sii/situacion_tributaria/tercero?auth_cache=0

⚠️ Advertencia: No uses auth_cache=0 en cada petición. Puede causar bloqueo por múltiples inicios de sesión.

Mejores Prácticas

Seguridad

Nunca hardcodees credenciales en tu código
Usa variables de entorno
Revoca accesos no utilizados

Performance

Aprovecha el caché de 2 horas
No fuerces nueva sesión innecesariamente
Agrupa consultas cuando sea posible
Monitorea los tiempos de respuesta

Ejemplo de Uso Seguro

// ❌ MALO
const auth = {
  pass: {
    rut: "76192083-9",
    clave: "miClave123"  // Never do this!
  }
};

// ✅ BUENO
const auth = {
  pass: {
    rut: process.env.SII_RUT,
    clave: process.env.SII_CLAVE
  }
};

Capacitación inicial