---
title: "Autenticación SII - Método RUT/Clave"
description: "Aprende a autenticarte en el SII usando RUT y contraseña para realizar consultas tributarias"
type: "academy"
category: "lesson"
tags: []
authors: [Anonymous]
date: "2026-08-27"
last_update: "2026-08-21"
time_minutes: 4
draft: false
unlisted: false
url: "https://www.stage.apigateway.cl/academy/capacitacion-inicial/primeros-pasos/autenticacion-rut-clave"
---

# 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

```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 ejemplo: BHE emitidas

### Descripción

Lista de boletas de honorarios **emitidas** por un contribuyente en un período. Es útil para comprobar que la autenticación con RUT y clave funciona y que recibes datos coherentes.

### 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

1. En Swagger, busca la sección **"API Boletas de Honorarios (BHE)"**
2. Encuentra `POST /sii/bhe/emitidas/documentos/{emisor}/{periodo}`
3. 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
```json
{
  "auth": {
    "pass": {
      "rut": "11111111-1",
      "clave": "tu_clave_sii"
    }
  }
}
```

> [!NOTE] 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)

```json
{
    "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

```json
{
  "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**:
1. Verifica credenciales en www.sii.cl
2. Revisa formato del RUT (con guión, sin puntos)

### Error 401: Sesión Expirada

```json
{
  "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
```

> [!WARNING] 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

```javascript
// ❌ 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
  }
};
```


---
Last updated on 21/08/2026