--- title: "Autenticación en la API" description: "Autenticación en la API" type: "faq" category: "question" tags: [] authors: [Anonymous] date: "2026-09-11" last_update: "2026-09-11" time_minutes: 1 draft: false unlisted: false url: "https://www.apigateway.cl/faq/autenticacion-api" --- # Autenticación en la API --- ## ¿Qué es el token de conexión y dónde lo obtengo? Es la credencial con que autenticas tus consultas, y va en la cabecera Authorization de cada petición. # ¿Qué es el token de conexión y dónde lo obtengo? Es la credencial con que tu sistema se identifica ante API Gateway. Se genera en [Gestionar conexión → Token](https://app.apigateway.cl/connections/manage#token) y va en la cabecera de **todas** tus consultas: ```http Authorization: Token <tu_token> ``` Tres cosas que conviene tener claras: - **El token está asociado a la conexión, no a los productos.** No cambia al activar o desactivar un producto y **no hay que regenerarlo** tras un cambio de configuración. - **La pestaña Token no muestra qué servicios incluye.** Los productos activos se ven en la pestaña *Productos*, que es donde se configuran. - **Regenerarlo invalida el anterior** de inmediato: actualiza tu integración al hacerlo. Trátalo como una contraseña. Si sospechas que se filtró, regenéralo. > [!WARNING] No lo confundas con la API Key de tu usuario > > Revisa [¿Para qué sirve la API Key de mi usuario?](https://www.apigateway.cl/faq/cuenta-y-acceso/para-que-sirve-la-api-key-de-mi-usuario). --- ## ¿Cuál es la URL base de la API? La URL base de la versión actual es app.apigateway.cl/api/v2/, distinta del sitio web y de la versión Legacy. # ¿Cuál es la URL base de la API? | Servicio | URL base | |---|---| | API Gateway V2 (actual) | `https://app.apigateway.cl/api/v2/` | | API Gateway Legacy (V1) | `https://legacy.apigateway.cl/api/v1/` | Errores frecuentes: - **Usar `apigateway.cl` o `www.apigateway.cl`**: ese es el sitio web, no la API. - **Agregar una barra final de más** antes de los parámetros de query: hace que la ruta no calce y la respuesta sea una página HTML de "Página no encontrada". - **Mezclar versiones**: los paths de `/api/v1` no existen en `/api/v2` y viceversa. > [!WARNING] No pruebes rutas inventadas > > Si un recurso no aparece en la [documentación de la API](https://www.apigateway.cl/docs/api), no existe: no hay recursos ocultos. Hacer muchas peticiones a rutas inexistentes puede provocar un bloqueo de IP. Si necesitas algo que no está, [consúltalo por ticket](https://www.apigateway.cl/help). --- ## ¿Debo autenticarme con RUT y clave o con certificado digital? Cada recurso indica en su documentación el método que corresponde, y usar el otro puede provocar errores difíciles de diagnosticar. # ¿Debo autenticarme con RUT y clave o con certificado digital? **Lo define cada recurso.** Su documentación indica qué método corresponde, y ese es el que debes usar. Algunos aceptan ambos, otros exigen uno. Con RUT y clave tributaria: ```json { "auth": { "pass": { "rut": "11111111-1", "clave": "tu_clave_tributaria" } } } ``` Con certificado digital: ```json { "auth": { "cert": { "cert-data": "-----BEGIN CERTIFICATE-----...", "pkey-data": "-----BEGIN PRIVATE KEY-----..." } } } ``` O con el archivo PFX en base64, según el recurso: ```json { "auth": { "cert": { "file-data": "<pfx en base64>", "file-pass": "<clave del certificado>" } } } ``` > [!WARNING] Usar el método equivocado no siempre da un error claro > > Puede aparecer como un `409` de indisponibilidad del SII o como un `401` intermitente, y hacerte buscar el problema en el lugar equivocado. Confirma el método en la [documentación del recurso](https://www.apigateway.cl/docs/api) antes de asumirlo. Revisa [Token y certificado](https://www.apigateway.cl/docs/manual/token-y-certificado) y [Errores 401 al consumir la API](https://www.apigateway.cl/docs/solucion-de-problemas/errores-de-autenticacion-en-la-api). --- ## ¿Cómo obtengo mi certificado digital en formato PEM? Se convierte con la herramienta de la plataforma o con las utilidades públicas, y no queda almacenado. # ¿Cómo obtengo mi certificado digital en formato PEM? La API necesita el certificado en formato **PEM**, es decir el certificado y la llave privada como texto. Tu certificado normalmente viene en un archivo `.p12` o `.pfx`. Tienes dos formas de convertirlo: - Desde **Gestionar conexión → Certificado** en la plataforma. - Con la utilidad pública de [tools.libredte.cl](https://tools.libredte.cl/utilities/certificate/inspect). También puedes revisar el [tutorial para extraer el PEM](https://www.apigateway.cl/docs/tutoriales/extraer-pem). > [!WARNING] Esa sección no almacena tu certificado > > Es solo una herramienta de conversión: el certificado **no queda cargado** en API Gateway ni en tu conexión, y debes enviarlo en el cuerpo de cada consulta que lo requiera. Si obtienes errores de PEM al consultar, vuelve a generarlo, verifica que copiaste el bloque completo incluyendo las líneas `BEGIN` y `END`, y confirma que el certificado esté vigente. --- ## ¿Por qué mis consultas reutilizan la sesión del SII y cómo fuerzo una nueva? La sesión del SII se reutiliza un tiempo para mejorar el rendimiento; auth_cache permite forzar una nueva. # ¿Por qué mis consultas reutilizan la sesión del SII y cómo fuerzo una nueva? Cuando envías credenciales en el cuerpo de la consulta, API Gateway inicia sesión en el SII y **reutiliza esa sesión** un tiempo, del orden de dos horas. Es intencional: acelera las consultas siguientes, evita iniciar sesión una y otra vez y reduce el riesgo de que el SII bloquee tus accesos. Por eso la primera consulta de una serie es más lenta que las siguientes. Cuando la sesión queda en mal estado, la API lo indica: ```json { "code": 401, "detail": "Se debe volver a autenticar al usuario en la sesión del SII." } ``` y puede acompañarlo con la cabecera `X-Auth-Session-Problem: 1`. En ese caso puedes agregar `auth_cache=0` a la URL para forzar un inicio de sesión nuevo. > [!WARNING] No lo uses en todas tus peticiones > > Cada `auth_cache=0` equivale a un login nuevo en el SII. Usarlo permanentemente en producción **aumenta el riesgo de que el SII bloquee tus accesos** y empeora el rendimiento. Es para casos puntuales. Si consultas varias empresas en secuencia, revisa [¿Por qué recibo documentos de otra empresa?](https://www.apigateway.cl/faq/mipyme/recibo-documentos-de-otra-empresa). --- ## ¿En qué formato debo enviar el RUT? Sin puntos, con guión y con dígito verificador; enviarlo con puntos provoca errores difíciles de diagnosticar. # ¿En qué formato debo enviar el RUT? **Sin puntos, con guión y con dígito verificador**, y la `K` en mayúscula. | Correcto | Incorrecto | |---|---| | `11111111-1` | `11.111.111-1` | | `22222222-2` | `222222222` | Aplica tanto al RUT en la **ruta** de la operación como al `rut` dentro del objeto `auth`. > [!WARNING] Un RUT con puntos no siempre da un error claro > > Puede producir errores que parecen de otra naturaleza, incluidos timeouts de navegación al portal del SII, y hacerte buscar el problema en el lugar equivocado. ## Cuidado con el RUT que va en cada lugar Es frecuente confundir el RUT del **contribuyente que se consulta** con el de la **credencial que inicia sesión**. En muchos recursos son distintos: - En la **ruta**: el RUT del contribuyente cuya información pides. - En `auth.pass.rut`: el RUT de quien **inicia sesión**, que puede ser una persona natural autorizada por esa empresa. Revisa [Errores 400: estructura del request](https://www.apigateway.cl/docs/solucion-de-problemas/errores-de-estructura-del-request). --- Última actualización el 11/09/2026