---
title: "Primeros Pasos"
description: ""
type: "academy"
category: "module"
tags: []
authors: [Anonymous]
date: "2026-08-27"
last_update: "2026-08-21"
time_minutes: 22
draft: false
unlisted: false
url: "https://www.stage.apigateway.cl/academy/capacitacion-inicial/primeros-pasos"
---

# Primeros Pasos




---

## Configuración de Proxy para Consultas al SII

Aprende a configurar un proxy para consultas al SII

# Configuración de Proxy para Consultas al SII

## ¿Por qué necesitas un proxy?

Un proxy es tu propio camino exclusivo hacia el SII. Cuando el SII implementa restricciones temporales por volumen de consultas, tener tu proxy significa que tus operaciones continúan sin interrupciones, independiente de lo que les ocurra a otros usuarios de la plataforma.

## ¿Cómo implementarlo?

Configurar tu proxy es más sencillo de lo que imaginas. En nuestro [tutorial técnico completo](https://www.apigateway.cl/docs/tutoriales/proxy) te guiamos paso a paso para:

- Instalar y configurar Squid usando Docker
- Asegurar tu proxy con autenticación robusta
- Integrarlo con tu cuenta de API Gateway
- Verificar que todo funcione correctamente

No necesitas ser un experto en sistemas: si sabes usar Docker, puedes tener tu proxy funcionando en el tiempo que tardas en tomar un café.

---


    
---

## Navegando Swagger UI

Aprende a usar la interfaz de Swagger para explorar y probar la API de API Gateway

# Navegando Swagger UI

Swagger UI es una herramienta interactiva que te permite explorar, entender y probar la API directamente desde tu navegador. No necesitas escribir código ni usar herramientas externas - todo está integrado en una interfaz visual amigable.

---

## Accediendo a Swagger UI

### URL de Acceso

Para acceder a la documentación interactiva de API Gateway:

```
https://www.apigateway.cl/docs
```

### Primera Vista

Al ingresar, verás:
- **Título de la API**: "API Gateway"
- **Descripción general**: Información sobre los servicios disponibles
- **Versión**: Version actual de la API (1.0.0)
- **Servidor base**: URL donde se ejecutan las peticiones

---

## Estructura de la Interfaz

### Secciones de Endpoints [CORREGIR]

Los endpoints están organizados por categorías:

```
📁 SII - Consultas
  └── GET /sii/contribuyentes/{rut}
  └── POST /sii/situacion-tributaria
  └── POST /sii/actividades

📁 LibreDTE - Emisión
  └── POST /libredte/dte/documentos/generar
  └── POST /libredte/dte/envios/enviar

📁 Utilidades
  └── GET /utilidades/validar-rut
  └── POST /utilidades/convertir-moneda
```

### Colores y Métodos HTTP

Cada método HTTP tiene un color específico:

| Método | Color | Uso típico |
|--------|-------|------------|
| **GET** | 🟦 Azul | Consultar información |
| **POST** | 🟩 Verde | Enviar datos/Crear recursos |
| **PUT** | 🟨 Amarillo | Actualizar completo |
| **DELETE** | 🟥 Rojo | Eliminar recursos |

---

## Funcionalidad "Try it out"

### Activar el Modo de Prueba

> [!WARNING] Importante
>
> **Ojo que estarás probando directamente en el SII, no en la API Gateway.**

1. Selecciona cualquier endpoint
2. Haz clic en el botón **"Try it out"** (esquina superior derecha)
3. Los campos se vuelven editables

### Completar los Datos

Según el tipo de endpoint:

#### Para GET con parámetros:
```
Path parameter:
rut: [76192083-9] <- Editable

Query parameters:
formato: [json ▼] <- Dropdown con opciones
```

#### Para POST con body:
```json
{
  "auth": {
    "pass": {
      "rut": "11111111-1",
      "clave": "miclave"
    }
  }
}
```

### Configurar Autorización

Antes de ejecutar endpoints protegidos:

1. Busca el botón **"Authorize"** 🔐 (parte superior)
2. Ingresa tu Bearer Token:
   ```
   Bearer tu_access_token_aqui
   ```
3. Clic en **"Authorize"**
4. El candado se cierra indicando autorización activa

---

## Ejecutar y Ver Resultados

### Botón Execute

Una vez configurados los parámetros:
1. Clic en **"Execute"**
2. Swagger envía la petición real a la API
3. Aparece la sección de respuesta

### Interpretando la Respuesta

La respuesta muestra:

1. **Curl Command**
   ```bash
   curl -X POST "https://legacy.apigateway.cl/api/v1/sii/..." \
     -H "accept: application/json" \
     -H "Authorization: Bearer ..." \
     -d "{...}"
   ```

2. **Request URL**
   ```
   https://legacy.apigateway.cl/api/v1/sii/situacion-tributaria
   ```

3. **Response Status**
   ```
   Code: 200 OK
   ```

4. **Response Headers**
   ```
   content-type: application/json
   x-ratelimit-limit: 1000
   x-ratelimit-remaining: 999
   ```

5. **Response Body**
   ```json
   {
     "rut": "76192083-9",
     "razon_social": "EMPRESA DEMO",
     "estado": "ACTIVO"
   }
   ```


    
---

## Tu Primera Petición

Realiza tu primera consulta exitosa a la API de API Gateway usando Swagger UI

# Tu Primera Petición

Es momento de hacer tu primera petición real a la API. Comenzaremos con algo simple: validar un RUT. Este endpoint no requiere autenticación en el SII, por lo que es perfecto para empezar.

---

## Paso 1: Obtener tu Access Token

### ¿Qué es un Access Token?

Es tu "llave" para usar la API. Todas las peticiones deben incluir este token para identificarte como usuario autorizado.

### Dónde Obtenerlo

1. Ingresa a tu [Dashboard de API Gateway](https://legacy.apigateway.cl/dashboard)
2. En la sección **"[API Auth](https://legacy.apigateway.cl/dashboard#api-auth)"** podrás crear un nuevo token.
3. Haz clic en **"Crear Token"**
4. Copia el token generado.

> [!INFO] Importante
>
> Este token es como una contraseña. No lo compartas ni lo subas a repositorios públicos.

---

## Paso 2: Configurar Autorización en Swagger

### Proceso de Autorización

1. En Swagger UI, busca el botón **"Authorize"** 🔐 (parte superior derecha)
2. Se abrirá un modal de autorización
3. En el campo **"Value"**, ingresa:
   ```
   Bearer sk_live_50kB1cGciOiJSUzI1NiIsInR5c...
   ```

> [!NOTE] Nota
>
> Incluye la palabra "Bearer" seguida de un espacio antes del token

4. Haz clic en **"Authorize"**
5. El botón mostrará un candado cerrado 🔒 indicando que estás autenticado

### Verificar Autorización

Si la autorización fue exitosa:
- El candado aparece cerrado 🔒
- Verás tu token parcialmente oculto
- Opción para "Logout" disponible

---

## Paso 3: Seleccionar el Endpoint

### Endpoint Situación Tributaria de un Contribuyente

Busca en la sección **"API Contribuyentes"**:

```
GET /api/v1/sii/contribuyentes/situacion_tributaria/tercero/{rut}
```



**¿Por qué este endpoint?**
- Es simple (solo requiere un parámetro)
- No necesita autenticación SII
- Respuesta inmediata
- Útil para obtener la situación tributaria de un contribuyente

### Expandir el Endpoint

1. Haz clic sobre el endpoint
2. Se desplegará mostrando:
   - Descripción completa
   - Parámetros requeridos
   - Posibles respuestas

---

## Paso 4: Configurar la Petición

### Activar Modo de Prueba

1. Haz clic en **"Try it out"**
2. Los campos se vuelven editables

### Completar Parámetros

Para este endpoint solo necesitas:

```
Path Parameters
───────────────
rut*: 76192083-9
```

**Formato del RUT**:
- Sin puntos
- Con guión
- Con dígito verificador
- Ejemplo: `76192083-9` ✅
- No usar: `76.192.083-9` ❌

---

## Paso 5: Ejecutar la Petición

### Enviar la Solicitud

1. Verifica que el RUT esté correctamente ingresado
2. Haz clic en **"Execute"**
3. Swagger enviará la petición a la API

### Qué Sucede al Ejecutar

1. Swagger construye la petición completa
2. Añade tu Bearer Token automáticamente
3. Envía la solicitud al servidor
4. Espera la respuesta
5. Muestra los resultados

---

## Paso 6: Interpretar la Respuesta

### Respuesta Exitosa (200 OK)

```json
{
  "actividades": [
    {
      "afecta": true,
      "categoria": 1,
      "codigo": "620200",
      "glosa": "ACTIVIDADES DE CONSULTORIA DE INFORMATICA Y DE GESTION DE INSTALACIONE"
    }
  ],
  "documentos_timbrados": [
    {
      "documento": "Factura Electronica",
      "ultimo_timbraje": 2020
    },
  ],
  "dv": "9",
  "excepcion_dte": false,
  "fecha_inicio_actividades": "2012-06-08",
  "inicio_actividades": true,
  "moneda_extranjera": false,
  "obligacion_dte": true,
  "observaciones": {
    "actividad_esporadica": false,
    "domicilio_inexistente": false,
    "inconcurrente": false,
    "no_habido_domicilio": false,
    "no_ubicado": false,
    "suplantado": false,
    "termino_giro": false,
    "termino_giro_obligatorio": false
  },
  "pro_pyme": true,
  "razon_social": "SASCO SPA",
  "rut": 76192083
}
```

**Campos de la respuesta**:
| Campo | Descripción |
|-------|-------------|
| `valido` | true si el RUT es válido |
| `rut` | RUT sin formato |
| `dv_calculado` | Dígito verificador correcto |
| `dv_ingresado` | Dígito que proporcionaste |
| `formato_completo` | RUT con puntos y guión |

### Headers de Respuesta

```
content-type: application/json
x-ratelimit-limit: 1000
x-ratelimit-remaining: 999
x-request-id: 550e8400-e29b-41d4
```

**Headers importantes**:
| Header | Significado |
|--------|-------------|
| `x-ratelimit-limit` | Peticiones máximas por hora |
| `x-ratelimit-remaining` | Peticiones restantes |
| `x-request-id` | ID único de esta petición |

---

## Analizando el cURL

Swagger genera automáticamente el comando cURL:

```bash
curl -X 'GET' \
  'https://legacy.apigateway.cl/api/v1/sii/contribuyentes/situacion_tributaria/tercero/76192083-9' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer sk_live_50kB1cGciOiJSUzI1NiIsInR5c...'
```

**Componentes del comando**:
- `-X 'GET'`: Método HTTP
- URL completa con el RUT
- `-H 'accept: application/json'`: Esperamos JSON
- `-H 'Authorization: ...'`: Tu token de acceso

---

## Ejercicios Adicionales

### 1. Probar con RUT Inválido

Intenta con: `11111111-2` (dígito verificador incorrecto)

Respuesta esperada:
```json
{
    "rut": 11111111,
    "dv": "2",
    "razon_social": null,
    "inicio_actividades": null
}
```

### 2. Probar sin Autorización

1. Haz "Logout" en el modal de autorización
2. Ejecuta la misma petición
3. Observa el error 401

Respuesta esperada:
```json
{
  "message": "Unauthenticated."
}
```

### 3. Explorar Otro Endpoint Simple

Prueba con:
```
GET /api/v1/sii/contribuyentes/actividades_economicas
```

Este endpoint retorna el listado de actividades económicas.


    
---

## Autenticación SII - Método RUT/Clave

Aprende a autenticarte en el SII usando RUT y contraseña para realizar consultas tributarias

# 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
  }
};
```


    
---

## Autenticación SII - Firma Electrónica

Aprende a autenticarte en el SII usando tu firma electrónica a través de Swagger

# Autenticación SII - Firma Electrónica

La firma electrónica es el método más seguro para autenticarse en el SII. A diferencia del método RUT/Clave, la firma electrónica:
- No expone tu contraseña del SII
- Es obligatoria para ciertos trámites
- Permite automatización más segura

---

## Métodos de Autenticación con Firma

API Gateway ofrece **dos formas** de enviar tu firma electrónica:

### Método 1: cert-data y pkey-data (Recomendado)

Envías por separado:
- **cert-data**: Certificado público en formato PEM
- **pkey-data**: Llave privada en formato PEM

### Método 2: file-data y file-pass

Envías el archivo completo:
- **file-data**: Archivo .p12/.pfx codificado en Base64
- **file-pass**: Contraseña del archivo

---

## Preparación del Certificado

### Convertir .p12 a PEM

Si tienes un archivo `.p12` o `.pfx`, necesitas convertirlo a formato PEM:

#### Opción A: Usar API Gateway (Más fácil)

1. Ingresa a [tu perfil en API Gateway](https://legacy.apigateway.cl/home#utils)
2. Busca la sección "Utilidades"
3. Sube tu archivo .p12/.pfx
4. Ingresa la contraseña
5. Obtendrás el cert-data y pkey-data listos para usar

#### Opción B: Usar OpenSSL

```bash
openssl pkcs12 -in firma.p12 -out firma.crt -nodes
```

Este comando generará un archivo con:
```
-----BEGIN CERTIFICATE-----
[Tu certificado aquí]
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
[Tu llave privada aquí]
-----END PRIVATE KEY-----
```

---

## Usando Swagger con Firma Electrónica

### Método 1: Con cert-data y pkey-data

1. **Localiza un endpoint** que requiera autenticación SII
2. **Haz clic en "Try it out"**
3. **En el body, estructura el JSON**:

```json
{
  "auth": {
    "cert": {
      "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...[tu certificado]...XYZ\n-----END CERTIFICATE-----",
      "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...[tu llave privada]...ABC\n-----END PRIVATE KEY-----"
    }
  }
}
```

4. **Ejecuta** la petición

### Método 2: Con file-data y file-pass

1. **Codifica tu archivo .p12 en Base64**:
   - Puedes usar herramientas online o comandos del sistema
   - En Linux/Mac: `base64 -i firma.p12 -o firma_base64.txt`

2. **Estructura el JSON**:

```json
{
  "auth": {
    "cert": {
      "file-data": "[contenido base64 del archivo]",
      "file-pass": "contraseña_del_p12"
    }
  }
}
```

---

## Comparación de Métodos

| Aspecto | cert-data/pkey-data | file-data/file-pass |
|---------|---------------------|---------------------|
| **Seguridad** | Más seguro (sin contraseña) | Incluye contraseña |
| **Preparación** | Requiere conversión | Directo con .p12 |
| **Rendimiento** | Más rápido | Conversión en cada request |
| **Recomendado para** | Producción | Pruebas rápidas |

---

## Verificando en Swagger

### Respuesta Exitosa

Si la autenticación es correcta, verás:
- **Status**: 200 OK
- **Body**: Datos solicitados del SII

### Errores Comunes

- Certificado mal formateado
- Firma vencida
- Estructura incorrecta

---

## Tips Importantes

### 1. Formato de los Saltos de Línea

❌ **Incorrecto**: Copiar/pegar sin saltos
```json
"cert-data": "-----BEGIN CERTIFICATE-----MIIG...XYZ-----END CERTIFICATE-----"
```

✅ **Correcto**: Con \n en cada línea
```json
"cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...\n...XYZ\n-----END CERTIFICATE-----"
```

### 2. Validar el Certificado

Antes de usar en producción:
- Verifica que no esté expirado
- Confirma que sea el certificado correcto
- Prueba primero en un endpoint simple

### 3. Seguridad

- **Nunca** guardes las credenciales en el código
- **Usa** variables de entorno en producción


    
---

## Explorando Formatos de Respuesta

Aprende a trabajar con diferentes formatos de respuesta en API Gateway

# Explorando Formatos de Respuesta

API Gateway no solo devuelve JSON. Dependiendo de tus necesidades, puedes obtener los datos en diferentes formatos que faciliten su procesamiento o presentación. Esto es especialmente útil cuando necesitas mostrar información directamente a usuarios o integrar con sistemas que esperan formatos específicos.

---

## Formatos Disponibles

> **El formato disponible depende del endpoint que estés consultando.**

### Formatos Principales

| Formato | Parámetro | Descripción | Mejor para |
|---------|-----------|-------------|------------|
| **JSON** | `formato=json` o sin parámetro | Formato por defecto, estructurado | APIs, procesamiento |
| **HTML** | `formato=html` | Página web del SII directa | Mostrar a usuarios |
| **CSV** | `formato=csv` | Valores separados | Excel, análisis |
| **XML** | `formato=xml` | Formato del SII original | Integraciones legacy |

---

## Modificando el Formato en Swagger

### Paso 1: Localizar el Parámetro

1. **Busca un endpoint** que soporte múltiples formatos
2. **Observa la sección "Parameters"**
3. **Encuentra** el parámetro `formato` (query parameter)

### Paso 2: Cambiar el Formato

En Swagger UI:
1. **Click en "Try it out"**
2. **En la sección de parámetros**, busca `formato`
3. **Selecciona** o escribe el formato deseado
4. **Ejecuta** la petición

### Ejemplo Visual en URL

```
# JSON (default)
/api/v1/sii/ejemplo/11111111-1/datos

# HTML
/api/v1/sii/ejemplo/11111111-1/datos?formato=html

# CSV
/api/v1/sii/ejemplo/11111111-1/datos?formato=csv
```

---

## Trabajando con Cada Formato

### JSON - Procesamiento Programático

**Cuándo usar**:
- Integración con aplicaciones
- Procesamiento automatizado
- APIs REST

**Ejemplo de respuesta**:
```json
{
  "rut": "11111111-1",
  "razon_social": "EMPRESA DEMO",
  "actividades": [
    {
      "codigo": 620100,
      "descripcion": "ACTIVIDADES DE PROGRAMACION INFORMATICA"
    }
  ]
}
```

### HTML - Presentación Directa

**Cuándo usar**:
- Mostrar información al usuario final
- Evitar diseñar interfaces propias
- Mantener formato oficial del SII

**Características**:
- Incluye estilos del SII
- Listo para mostrar en iframe o ventana
- No requiere procesamiento

### CSV - Análisis de Datos

**Cuándo usar**:
- Exportar a Excel
- Análisis masivo
- Reportes

**Configuración adicional**:
```
?formato=csv&csv_delimiter=;
```

Delimitadores disponibles:
- `,` (coma) - Por defecto
- `;` (punto y coma) - Para Excel en español

**Ejemplo de respuesta**:
```csv
rut;razon_social;actividad_codigo;actividad_descripcion
11111111-1;EMPRESA DEMO;620100;ACTIVIDADES DE PROGRAMACION INFORMATICA
```

### XML - Formato Original SII

**Cuándo usar**:
- Sistemas que requieren XML
- Mantener estructura original del SII
- Validaciones con esquemas XSD

---

## Casos de Uso Prácticos

### Caso 1: Dashboard Ejecutivo

**Necesidad**: Mostrar datos del SII en pantalla
**Solución**: Formato HTML en iframe
```html
<iframe src="https://api.../datos?formato=html" />
```

### Caso 2: Reporte Mensual

**Necesidad**: Analizar datos en Excel
**Solución**: Formato CSV con delimitador ;
```
?formato=csv&csv_delimiter=;
```

### Caso 3: Integración con ERP

**Necesidad**: Procesar datos automáticamente
**Solución**: Formato JSON (default)

### Caso 4: Sistema Legacy

**Necesidad**: Sistema antiguo espera XML
**Solución**: Formato XML
```
?formato=xml
```

---

## Consideraciones Importantes

### Disponibilidad de Formatos

No todos los endpoints soportan todos los formatos. En Swagger verás:
- Si el parámetro `formato` está disponible
- Qué valores acepta


    
---

## Manejo de Errores

Aprende a identificar y resolver errores al usar API Gateway

# Manejo de Errores

Los errores son parte normal del desarrollo. Lo importante es saber identificarlos rápidamente y entender qué significan. Swagger UI facilita mucho este proceso al mostrar toda la información de manera visual.

---

## Códigos de Error Principales

### Tabla de Referencia Rápida

| Código | Nombre | Significado | Acción Requerida |
|--------|--------|-------------|------------------|
| **400** | Bad Request | Petición inválida o falla al ser procesada (error genérico). | Revisar JSON/parámetros |
| **401** | Unauthorized | Access Token incorrecto, credenciales SII incorrectas o problema con la sesión del SII. | Verificar token o credenciales |
| **402** | Payment Required | El período de prueba terminó y se debe pasar a un plan de pago. | Actualizar suscripción |
| **403** | Forbidden | No tiene autorización para acceder al recurso solicitado. | Verificar alcance del token |
| **404** | Not Found | Recurso solicitado no pudo ser encontrado. | Revisar URL/parámetros |
| **405** | Method Not Allowed | El método o acción solicitada no está permitida en el recurso. | Revisar método HTTP |
| **406** | Not Acceptable | Solicitó la respuesta en un formato de datos incorrecto. | Revisar formato de respuesta |
| **409** | Conflict | Solicitud no pudo ser procesada debido a conflicto con el origen de los datos en el SII. | Revisar datos |
| **410** | Gone | El recurso solicitado ya no existe en nuestra API. | Revisar URL/parámetros |
| **423** | Locked | La cuenta fue bloqueada por incumplir términos y condiciones. | Contactar soporte |
| **429** | Too Many Requests | Se alcanzó el límite de la cuota, se debe dejar de hacer consultas hasta que se renueven. | Esperar o revisar headers |

> [!NOTE] Nota
>
>Con el paso del tiempo podríamos ir agregando o eliminando tipos de errores. Se recomienda verificar que la aplicación se adapte a estos cambios o al menos maneje un caso por defecto cuando hay un error que no conoce.

---

## Bloqueo de la cuenta

API Gateway tiene [términos y condiciones](https://www.apigateway.cl/legal) que norman el uso. En estos términos hay 2 condiciones que pueden llevar a un bloqueo de la cuenta:

- Compartir IP.
- Tener muchas consultas con código de respuesta HTTP 429.

Ambos puntos se explican en los términos y condiciones de API Gateway.

Este bloqueo no puede ser removidor por el equipo de soporte. Por lo que:

- Deberás esperar a que se desbloqueen las consultas.
- Contratar un plan con más consultas.

---

## Identificando Errores

### Ubicación de la Información

Cuando ocurre un error, encontrarás:

1. **Status Code**: En la parte superior de la respuesta
2. **Response Body**: El mensaje de error en JSON
3. **Response Headers**: Información adicional importante

### Ejemplo Visual de Error 401

```
Response
Code: 401
Details: Error: Unauthorized

Response body:
{
  "code": 401,
  "message": "Token de acceso inválido o expirado"
}

Response headers:
content-type: application/json
x-request-id: 123e4567-e89b-12d3-a456-426614174000
```

---

## Interpretando Headers de Respuesta

### Headers de Rate Limiting

Estos headers aparecen en **TODAS** las respuestas:

| Header | Significado | Ejemplo |
|--------|-------------|---------|
| `X-RateLimit-Limit` | Máximo de peticiones permitidas cada 24 horas | 1000 |
| `X-RateLimit-Remaining` | Peticiones restantes | 847 |

> **Nota**: Se recomienda hacer uso de estas cabeceras para monitorear el uso de la API. Con esto evitarás que se bloqueen tus consultas, una vez que llegues al límite.

### Headers cuando llegas al límite

| Header | Significado | Ejemplo |
|--------|-------------|---------|
| `Retry-After` | Segundos hasta poder reintentar | 3600 |
| `X-RateLimit-Reset` | Timestamp cuando se resetea | 1640995200 |

## Errores Comunes y Soluciones

### Error 401: Unauthorized

**Variante 1: Token API inválido**
```json
{
  "message": "Unauthenticated."
}
```
**Solución**:
- Verifica que el token esté en Authorization: Bearer
- Regenera el token si es necesario

**Variante 2: Credenciales SII incorrectas**
```json
{
  "code": 401,
  "message": "Autenticación con SII falló: clave incorrecta"
}
```
**Solución**:
- Verifica RUT y clave
- Prueba en el sitio del SII directamente

**Variante 3: Sesión SII expirada**
```json
{
  "code": 401,
  "message": "Se debe volver a autenticar al usuario en la sesión del SII."
}
```
**Solución**:
- Agrega `?auth_cache=0` para forzar nueva sesión


### Error 429: Too Many Requests

```json
{
  "message": "Too Many Attempts."
}
```

**Información en headers**:
```
Retry-After: 3600
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
```

**Solución**:
1. **Lee** el header `Retry-After`
2. **Espera** ese tiempo (en segundos)
3. **Opcional**: Revisa tu plan para más cuota

### Error 400: Bad Request

```json
{
  "code": 400,
  "message": "El campo 'rut' es requerido"
}
```

**Causas comunes**:
- JSON mal formateado
- Campos requeridos faltantes
- Tipos de datos incorrectos

**Cómo debuggear en Swagger**:
1. Revisa el JSON en el editor
2. Verifica que no falten comillas
3. Usa la validación de Swagger (marca errores en rojo)

---

## Estrategias de Prevención

### 1. Monitoreo de Rate Limit

**En cada respuesta exitosa**, revisa:
```
X-RateLimit-Remaining: 150
```

Si es menor a 100, considera:
- Espaciar las consultas
- Implementar caché local
- Optimizar las llamadas

### 2. Manejo de Sesiones SII

**Problema**: El header `X-Stats-NavegadorSessionProblem: 1`

**Prevención**:
- No abuses del `auth_cache=0`
- Deja expirar sesiones naturalmente (2 horas)

### 3. Validación Previa

Antes de enviar:
- Revisa que el JSON esté bien formateado
- Verifica que todos los campos requeridos estén presentes
- Confirma que los tipos de datos sean correctos


    

---
Last updated on 21/08/2026