Tu Primera Petición

Una API es el canal por el que tu programa (o la documentación interactiva) envía peticiones HTTP y recibe respuestas; casi siempre en JSON (texto con llaves { } y listas [ ]). Para que el servidor sepa quién eres, API Gateway exige un token ligado a tu conexión (no basta con abrir la página web).

URLs que debes conocer:

En esta guía el ejemplo es un GET a la situación tributaria de un tercero: no pide clave del SII en el cuerpo y sirve para practicar token y la documentación antes de mezclar autenticación al SII.

Paso 1: Obtener tu token de API

El token es la llave que identifica qué conexión usa la API; esa conexión define créditos, productos y configuración. Sin token válido, las rutas protegidas suelen responder 401 Unauthorized.

Para obtener el token de API, debes seguir los siguientes pasos:

1. Entra a app.apigateway.cl e inicia sesión.
2. Si tienes varias conexiones, en el panel selecciona la conexión con la que vas a integrar.
3. Abre Gestionar conexión.
4. Pestaña Token API.
5. Si no tienes token: Generar Token. Si ya hay uno y quieres otro: Regenerar Token (el que reemplazas deja de valer).
6. Copia y guarda el token en un lugar seguro.

Para incluir el token en las solicitudes a la API, debes agregar la siguiente cabecera:

Incluye esta cabecera en todas las solicitudes a la API: palabra Token, un espacio y la clave (sin comillas). Hay un resumen en la introducción a la documentación.

Authorization: Token <tu_token>

Paso 2: Configurar autorización

Para configurar la autorización en la documentación interactiva, debes seguir los siguientes pasos:

1. Abre www.apigateway.cl/docs/api.
2. Busca el botón Authorize 🔐 (o el control de seguridad equivalente).
3. En el campo que indique la herramienta, pega el token o el valor completo Token tu_token, según lo que pida el formulario.
4. Confirma con Authorize.
5. Un candado cerrado 🔒 suele indicar que las pruebas enviarán el token.

Para verificar que la autorización fue exitosa, deberías ver un candado cerrado 🔒, una vista parcial del token y la opción Logout en el modal si quieres probar sin token.

Paso 3: Seleccionar el endpoint

Para realizar algunas pruebas, puedes seleccionar el endpoint que desees consultar. En este caso, se seleccionará el endpoint de la Situación tributaria de un contribuyente.

En la documentación, bajo Contribuyentes, localiza:

GET /api/v2/sii/contribuyentes/situacion_tributaria/tercero/{rut}

¿Por qué este endpoint? Solo pides el RUT en la ruta, no envías auth del SII en el cuerpo y la respuesta es rica en información para validar que todo funciona.

Para revisar la información del endpoint, debes seguir los siguientes pasos:

1. Haz clic sobre la operación.
2. Lee la descripción, parámetros y códigos de respuesta listados.

Paso 4: Configurar la petición

Para activar el modo de prueba, debes seguir los siguientes pasos:

1. Try it out
2. Edita el campo del path {rut}

Para completar los parámetros, debes seguir los siguientes pasos:

Path parameter
──────────────
rut: 76192083-9

Formato del RUT: sin puntos, con guión y dígito verificador. Válido: 76192083-9 ✅. Evitar: 76.192.083-9 ❌.

Paso 5: Ejecutar la petición

Para enviar la solicitud, debes seguir los siguientes pasos:

1. Comprueba el RUT
2. Execute
3. Espera la respuesta bajo el bloque de la operación

Para verificar qué sucede al ejecutar la petición, debes seguir los siguientes pasos:

1. La herramienta arma la URL completa (https://app.apigateway.cl/api/v2/...)
2. Añade la cabecera Authorization: Token … si configuraste Authorize
3. Envía el GET al servidor
4. Muestra código HTTP, cabeceras y cuerpo

Paso 6: Interpretar la respuesta

Respuesta exitosa (200 OK)

Ejemplo ilustrativo de cuerpo JSON:

{
  "data": {
    "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
  }
}

Algunos campos de la respuesta

La documentación interactiva puede describir cada campo con más detalle.

Cabeceras de respuesta

Junto al JSON vienen cabeceras HTTP con cuota, créditos y tiempos. Los números del ejemplo son ilustrativos; los tuyos dependen del plan y del momento.

Fragmento típico

content-type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1735689600
X-Stats-Time: 1.234
X-Stats-Memory: 45219840
X-Stats-Credits-Used: 0.010
X-Stats-Credits-Remaining: 1523.450
X-Stats-Started-At: 2026-04-08T15:30:00.123456+00:00
X-Stats-Ended-At: 2026-04-08T15:30:01.357890+00:00
X-Stats-Operations: 1
X-Source-Request-Count: 4
X-Source-Request-Time: 0.85
X-Source-Proxy: 0
X-Source-Captcha-Attempts: 0

Tabla rápida

Error 429 (demasiadas peticiones)

Puede venir Retry-After (segundos sugeridos de espera); no reintentes en bucle al instante.

Cabeceras opcionales de sesión SII

Con login al SII en el cuerpo pueden aparecer cabeceras X-Auth-* o X-Auth-Session-Problem. En este GET de ejemplo (sin credenciales SII) muchas no vienen: es normal. Si en otro flujo ves X-Auth-Session-Problem: 1, revisa Manejo de errores.

Analizando el cURL

La documentación suele generar un comando equivalente:

curl -X 'GET' \
  'https://app.apigateway.cl/api/v2/sii/contribuyentes/situacion_tributaria/tercero/76192083-9' \
  -H 'accept: application/json' \
  -H 'Authorization: Token TU_TOKEN_AQUI'

Qué significa cada parte: -X 'GET' es el método de lectura; la URL lleva el RUT en la ruta; accept: application/json indica que esperas JSON; Authorization: Token … es tu token de la pestaña Token API. Para ver cabeceras en terminal, usa curl -i o curl -D -.

Ejercicios adicionales

Probar con un RUT que devuelva pocos datos

Prueba por ejemplo 11111111-2 (dígito verificador incorrecto o sin datos en el SII) y observa cómo cambian campos como razon_social o inicio_actividades.

Probar sin autorización

1. Logout en el modal de autorización.
2. Ejecuta de nuevo el mismo GET.
3. Deberías ver 401 y un cuerpo de error (el texto exacto puede variar).

Otro GET simple

En la misma documentación, prueba:

GET /api/v2/sii/contribuyentes/actividades_economicas

(sin parámetros de ruta; revisa si exige solo el token de conexión).