--- title: "Tu Primera Petición" description: "Realiza tu primera consulta exitosa a la API de API Gateway usando la documentación interactiva" type: "academy" category: "lesson" tags: [] authors: [Anonymous] date: "2026-08-27" last_update: "2026-08-21" time_minutes: 7 draft: false unlisted: false url: "https://www.stage.apigateway.cl/academy/primeros-pasos/punto-de-partida/primera-peticion" --- # 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:** | Qué necesitas | Dónde | |---------------|--------| | Probar y leer la documentación | [www.apigateway.cl/docs/api](https://www.apigateway.cl/docs/api) | | Iniciar sesión, token, datos de conexión | [app.apigateway.cl](https://app.apigateway.cl) | | Llamadas reales a la API | Base `https://app.apigateway.cl/api/v2/` | 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](https://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](https://app.apigateway.cl/connections/manage)**. 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. > [!INFO] Importante > > Trátalo como una contraseña. No lo subas a repositorios públicos ni lo pegues en capturas. Si se filtra, **regenera** el token en la misma pestaña. 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](https://www.apigateway.cl/docs). ```http Authorization: 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](https://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. > [!NOTE] Nota > > Si recibes **401**, revisa que no falte la palabra `Token`, que no haya espacios de más al copiar/pegar y que el token corresponda a la conexión activa. 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: ```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 | Campo | Descripción | |-------|-------------| | `rut` | RUT numérico (sin guión) del contribuyente consultado | | `dv` | Dígito verificador | | `razon_social` | Nombre o razón social | | `inicio_actividades` | Si tiene inicio de actividades | | `fecha_inicio_actividades` | Fecha de inicio si aplica | | `actividades` | Listado de actividades económicas vigentes | | `documentos_timbrados` | Documentos timbrados y último año de timbraje | | `observaciones` | Banderas de situación (domicilio, término de giro, etc.) | 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 ```http 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 | Cabecera | Qué indica | |----------|------------| | `content-type` | Tipo del cuerpo (habitualmente `application/json`). | | `X-RateLimit-Limit` | Tope de peticiones de la ventana que aplica a tu conexión. | | `X-RateLimit-Remaining` | Cuántas peticiones te quedan antes de llegar al tope. | | `X-RateLimit-Reset` | Instante (segundos Unix, UTC) en que se renueva la ventana del contador. | | `X-Stats-Credits-Used` | Créditos consumidos en esta respuesta. | | `X-Stats-Credits-Remaining` | Créditos disponibles tras esta operación (según estado al responder). | | `X-Stats-Time` | Tiempo de procesamiento en el servidor (segundos, texto). | | `X-Stats-Started-At` / `X-Stats-Ended-At` | Inicio y fin del procesamiento. | | `X-Stats-Operations` | Operaciones internas contadas en esa petición. | | `X-Source-Request-Count` | Solicitudes hacia el SII u orígenes externos para armar la respuesta. | | `X-Source-Request-Time` | Tiempo agregado de esas solicitudes externas. | | `X-Source-Proxy` | `1` si se usó proxy de conexión hacia el SII, `0` si no. | | `X-Source-Captcha-Attempts` | Intentos de captcha en la petición (a menudo `0`). | #### 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](./manejo-de-errores). ## Analizando el cURL La documentación suele generar un comando equivalente: ```bash 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). --- Last updated on 21/08/2026