---
title: "Manual de la plataforma"
description: "Manual de la plataforma"
type: "docs"
category: "doc"
tags: []
authors: [Anonymous]
date: "2026-09-11"
last_update: "2026-09-11"
time_minutes: 1
draft: false
unlisted: false
url: "https://www.apigateway.cl/docs/manual"
---

# Manual de la plataforma

Este manual cubre el uso de la **plataforma web** de API Gateway: cómo administrar tu cuenta, tus conexiones, los productos que contratas, los créditos y los pagos.

Es la contraparte de la [documentación de la API](https://www.apigateway.cl/docs/api), que describe cada recurso, y de la [academia](https://www.apigateway.cl/academy), que enseña a consumirlos paso a paso. Acá se explica todo lo que ocurre **antes** de la primera consulta y todo lo que sostiene el servicio después.

> [!TIP] Si estás partiendo
>
> Parte por [Conceptos del servicio](https://www.apigateway.cl/docs/manual/introduccion): explica en una página qué es una conexión, qué es un producto y cómo funciona el modelo de créditos. Casi todas las dudas de facturación que atendemos vienen de no tener claros esos tres conceptos.



---

## Conceptos del servicio

Los cuatro conceptos que sostienen API Gateway: cuenta, conexión, producto y crédito.

# Conceptos del servicio

Cuatro conceptos explican cómo funciona todo el servicio. Vale la pena leerlos antes de configurar nada.

## Cuenta

La **cuenta** es tu identidad como usuario: el correo con que ingresas, tu contraseña, tu verificación en dos pasos y tu API Key personal.

Una cuenta puede tener **varias conexiones**.

## Conexión

La **conexión** es la unidad de trabajo. Todo lo operativo vive dentro de ella:

- El **token** con que autenticas las consultas a la API.
- El **saldo de créditos** desde el cual se descuenta cada consulta.
- Los **productos activos**, que determinan a qué recursos tienes acceso.
- El **proxy** por el que salen las consultas al SII.
- Los **datos de facturación** con que se emite la factura.
- El **límite de usuarios de autenticación** y el de consultas por minuto.

Lo más importante: **los créditos son de la conexión, no de la cuenta**. Dos conexiones no comparten saldo ni productos, y cada una paga su propia base mensual.

## Producto y operación

Un **producto** agrupa un conjunto de **operaciones** de la API. Para consumir una operación, el producto que la contiene debe estar activo en tu conexión.

Las operaciones tienen un código jerárquico que refleja el producto al que pertenecen. Por ejemplo, `sii.rcv.compras.get_resumen` pertenece al producto *Registro de Compra y Venta*. Cuando la API rechaza una consulta por autorización, el mensaje nombra ese código, y con eso sabes qué producto activar.

## Crédito

El **crédito** es la unidad de consumo. Se compra en números enteros, con un mínimo por compra que la plataforma indica al generar el cobro, y se consume de tres formas:

1. **La base mensual**, el día 1 de cada mes: la suma de los productos activos más el pack de usuarios contratado.
2. **Cada consulta** a la API, según el costo de la operación.
3. **Cada usuario de autenticación adicional**, una vez por usuario y por período.

Los costos se expresan con tres decimales, porque la mayoría de las consultas cuesta una fracción de crédito.

> [!WARNING] La coma es separador de decimales
>
> `20,000 créditos` son **veinte** créditos, no veinte mil. Es el error más costoso que cometen los usuarios nuevos al comprar. Revisa [Créditos](https://www.apigateway.cl/docs/manual/creditos).

## Cómo se relacionan

```txt
Cuenta (tu usuario)
 └── Conexión  ──  token · proxy · datos de facturación
      ├── Créditos (saldo propio)
      ├── Productos activos  ──  habilitan operaciones
      └── Usuarios de autenticación (credenciales del SII que usas)
```

## Y una cosa que API Gateway no es

API Gateway es una **pasarela**: no tiene una base de datos con información tributaria propia. Cada consulta inicia sesión en el organismo con las credenciales que tú envías, obtiene el dato en ese momento y te lo devuelve.

De ahí se desprende que necesitas credenciales válidas del contribuyente, que una intermitencia del SII te afecta directamente, y que **no existe un ambiente de pruebas aislado**: cada consulta va al SII real.




---

## Cuenta y usuario

Registro, verificación de correo, contraseña, verificación en dos pasos y API Key personal.

# Cuenta y usuario

## Registro

Crea tu cuenta en [app.apigateway.cl/signup](https://app.apigateway.cl/signup). Tras el registro recibirás un correo con un enlace de verificación que debes confirmar.

Si no llega, revisa spam y solicita el reenvío en [/signup/resend_verification/](https://app.apigateway.cl/signup/resend_verification/).

> [!WARNING] Si tu cuenta es anterior al lanzamiento de la plataforma actual
>
> Existen dos servicios con bases de usuarios independientes. Si tu cuenta es de la versión anterior, el ingreso es en [legacy.apigateway.cl/login](https://legacy.apigateway.cl/login) y no en `app.apigateway.cl`. Revisa [Al iniciar sesión me dice que mi usuario no existe](https://www.apigateway.cl/faq/cuenta-y-acceso/mi-usuario-no-existe-al-iniciar-sesion).

## Ingreso

El ingreso es en [app.apigateway.cl/signin](https://app.apigateway.cl/signin).

## Recuperación de contraseña

En [/users/password/recovery](https://app.apigateway.cl/users/password/recovery) indicas tu correo y recibes un enlace para definir una contraseña nueva.

Esta es la contraseña de la plataforma. **No es tu clave tributaria del SII**, que se administra en [www.sii.cl](https://www.sii.cl) y viaja en el cuerpo de cada consulta a la API.

## Perfil

En [Mi perfil](https://app.apigateway.cl/users/profile) administras:

**Datos personales.** Nombre, correo y datos de contacto.

**Contraseña.** Cambio de contraseña desde la sesión activa.

**Verificación en dos pasos (2FA).** Al activarla se genera un código que registras en tu aplicación de autenticación, y desde entonces el ingreso pide el código además de la contraseña. Puedes desactivarla desde la misma sección.

> [!WARNING] Guarda el respaldo del 2FA
>
> Si pierdes el acceso a tu aplicación de autenticación quedarás sin poder ingresar, y recuperar el acceso requiere un [ticket de soporte](https://www.apigateway.cl/help).

**API Key personal.** Puedes generarla y eliminarla desde el perfil. Sirve para operar sobre tu propia cuenta y tus conexiones de forma programática.

> [!INFO] No confundas la API Key con el token de la conexión
>
> Para consumir los recursos del SII y Previred necesitas el **token de la conexión**, que se genera en [Gestionar conexión → Token](https://app.apigateway.cl/connections/manage#token). Revisa [Token y certificado](https://www.apigateway.cl/docs/manual/token-y-certificado).

## Datos de facturación del usuario

En [/users/profile/billing](https://app.apigateway.cl/users/profile/billing) están los datos de facturación asociados a tu usuario. Al registrar una conexión puedes optar por reutilizarlos, en lugar de ingresarlos de nuevo.

Ten presente que la facturación efectiva se emite con los **datos de la conexión**. Revisa [Cobros y pagos](https://www.apigateway.cl/docs/manual/cobros-y-pagos).

## Eliminación de la cuenta

Se solicita por [ticket](https://www.apigateway.cl/help), desde el correo titular de la cuenta. Abarca la cuenta y sus datos asociados: conexiones, identificador fiscal registrado e historial. El saldo de créditos se pierde.




---

## Conexiones

Registro, selección y administración de conexiones, incluidos sus datos, su proxy y su estado.

# Conexiones

## Registrar una conexión

En [Registrar conexión](https://app.apigateway.cl/connections/register) defines:

- **Nombre**: cómo identificarás la conexión. Debe ser único en tu cuenta.
- **Descripción**: opcional, útil cuando manejas varias.
- **Datos de facturación**: identificador fiscal, razón social, giro, país, dirección, comuna, correo y teléfono. Puedes marcar la opción de **usar los datos del usuario principal** para no reingresarlos.
- **Aceptación de los [términos y condiciones](https://www.apigateway.cl/legal)**.

El proxy se puede configurar después, pero es obligatorio antes de operar en serio.

Al crear tu primera conexión recibes créditos de bienvenida para una prueba de concepto.

## Varias conexiones y el mismo RUT

Puedes tener varias conexiones y **facturarlas al mismo identificador fiscal**. La restricción que antes lo impedía fue eliminada.

Lo típico es una conexión por sistema o por ambiente, por ejemplo producción y desarrollo, de modo que el consumo y el registro de actividad queden separados.

Lo que sigue siendo por conexión: los créditos, la base mensual, el proxy y el token. Dos conexiones con los mismos productos pagan la base **dos veces**.

## Seleccionar la conexión con que trabajas

En [Mis conexiones](https://app.apigateway.cl/dashboard) ves el listado y con **"Ingresar"** entras a una. Desde ese momento toda la administración —productos, créditos, cobros, token— aplica a esa conexión.

## Administrar la conexión

[Gestionar conexión](https://app.apigateway.cl/connections/manage) tiene estas pestañas:

| Pestaña | Contenido |
|---|---|
| **Datos** | Nombre, descripción y URL del proxy |
| **Datos de facturación** | Identificador fiscal, razón social, dirección, correo y **referencias** (por ejemplo, orden de compra) |
| **Productos** | Productos activos, pack de usuarios y base mensual estimada |
| **Créditos** | Compra de créditos |
| **Cobros** | Cotizaciones y pagos |
| **Token** | Token de la conexión |
| **Certificado** | Conversión del certificado digital a formato PEM |

## El proxy de la conexión

La URL del proxy se configura en la pestaña **Datos**, con este formato:

```txt
http://<usuario>:<contraseña>@<ip_del_proxy>:3128
```

Es un **requisito obligatorio** del servicio, independiente del volumen de consultas. El [tutorial de proxy](https://www.apigateway.cl/docs/tutoriales/proxy) trae la configuración completa de Squid lista para usar.

Para verificar que se está usando, revisa la cabecera `X-Stats-HttpClientProxy` en la respuesta de la API: `1` significa que la consulta salió por tu proxy.

## Estado de la conexión

Una conexión puede quedar **suspendida por créditos insuficientes** si el día 1 del mes el saldo no cubre la base mensual. En ese estado la API responde `La conexión está inactiva.`

Se reactiva **automáticamente** al comprar créditos suficientes: el sistema descuenta el proporcional del mes en curso y la habilita. No requiere intervención de soporte.

Revisa [Créditos y conexión suspendida](https://www.apigateway.cl/docs/solucion-de-problemas/creditos-y-conexion-suspendida).

## Restricción de IP antes del primer pago

Las conexiones que **nunca han pagado un cobro** solo pueden consultar desde una IP que ninguna otra conexión haya usado. La restricción se levanta al registrar el primer pago.

Existe porque compartir una IP entre varias conexiones sin pagos es el patrón de las cuentas creadas para reciclar créditos de bienvenida, lo que está prohibido por los [términos y condiciones](https://www.apigateway.cl/legal).




---

## Productos y límites

Activación de productos, packs de usuarios de autenticación y límite de consultas por minuto.

# Productos y límites

Todo se administra en [Gestionar conexión → Productos](https://app.apigateway.cl/connections/manage#products).

## Qué es un producto

Un **producto** agrupa un conjunto de **operaciones** de la API. Para consumir una operación, el producto que la contiene debe estar activo en tu conexión.

Cada producto tiene un costo mensual en créditos, que se descuenta el día 1 de cada mes y es independiente de cuántas consultas hagas.

> [!INFO] Dónde ver los costos
>
> El listado de productos con su costo mensual, y el costo por consulta de cada recurso, están en el [cotizador de precios](https://www.apigateway.cl/pricing). Ahí puedes armar tu combinación y estimar el total mensual antes de contratar. La misma pantalla de **Productos** de tu conexión muestra el costo de cada uno y la **"Base mensual estimada (tu selección)"** según lo que marques.

Los productos cubren: información de contribuyentes, Registro de Compra y Venta, Documentos Tributarios, Cesión de DTE, Boletas de Honorarios, Boletas de Terceros, Portal MiPYME, Portal eBoleta, Formulario 29, Bienes Raíces, Vehículos e Indicadores Previsionales.

## Qué operaciones incluye cada producto

El código de cada operación indica el producto que la contiene. Cuando la API rechaza una consulta por autorización, el mensaje nombra ese código:

| Prefijo de la operación | Producto |
|---|---|
| `sii.contribuyentes.*` | Info. Contribuyentes |
| `sii.rcv.*` | Registro de Compra y Venta |
| `sii.dte.*` | Documentos Tributarios |
| `sii.rtc.*` | Cesión de DTE |
| `sii.bhe.*` | Boletas de Honorarios |
| `sii.bte.*` | Boletas de Terceros |
| `sii.mipyme.*` | Portal MiPYME |
| `sii.eboleta.*` | Portal eBoleta |
| `sii.f29.*` | Formulario 29 |
| `sii.bienes_raices.*` | Bienes Raíces |
| `sii.vehiculos.*` | Vehículos |
| `previred.indicadores.*` | Indicadores Previsionales |

Todos los productos incluyen además el acceso a `sii.misii.*` y `sii.indicadores.*`.

## Activar productos

1. Marca los productos que necesitas.
2. Revisa la **"Base mensual estimada (tu selección)"**, que muestra el total que pagarás cada mes. La cantidad se muestra también en texto, para evitar confusiones con la coma decimal.
3. Presiona **"Actualizar productos y límites"**.

> [!WARNING] El paso 3 no es opcional
>
> Marcar los casilleros no guarda nada. Sin presionar **"Actualizar productos y límites"** la selección se pierde al recargar la página, y la API seguirá respondiendo `403`. Es la causa más frecuente de los reportes de "activé el producto y no funciona".

## Lo que cuesta activar y desactivar

- **Activar** un producto descuenta créditos en ese momento, de forma **proporcional a los días que restan del mes**.
- **Desactivar** no tiene costo, pero **tampoco devuelve** lo cobrado.
- **Volver a activar** lo cobra otra vez, aunque sea el mismo mes y el mismo producto.

La plataforma advierte de esto al guardar:

> ¿Estás seguro de querer actualizar los productos y usuarios de autenticación? Los créditos consumidos no se reembolsarán, según las políticas explicadas en los Términos y Condiciones.

Por eso no conviene activar y desactivar productos para explorar: usa el [cotizador](https://www.apigateway.cl/pricing), que es gratis y no consume créditos.

## Usuarios de autenticación

Un **usuario de autenticación** es cada credencial distinta con la que la conexión inicia sesión en el SII: cada RUT y clave, o cada certificado, diferente.

Si eres una oficina contable que consulta por doce clientes con las credenciales de cada uno, esos son doce usuarios de autenticación.

- El servicio incluye un **usuario gratuito**.
- Cada usuario adicional distinto tiene un costo en créditos, que se descuenta **una sola vez por usuario y por período mensual**. Si vuelves a consultar por ese mismo usuario en el mismo mes, no se cobra de nuevo.
- Para muchas credenciales conviene contratar un **pack de usuarios**, que resulta más económico que pagarlos uno por uno.

> [!WARNING] Los packs no se suman
>
> Los packs son tramos fijos: no puedes combinar dos para llegar a una cantidad intermedia. Debes elegir el tramo que cubra la cantidad que necesitas, y solo están disponibles los publicados. Al indicar la cantidad de usuarios, el sistema calcula automáticamente el pack que corresponde.

Los tramos disponibles y su costo están en el [cotizador](https://www.apigateway.cl/pricing) y en la propia pantalla de **Productos** de tu conexión. Los usuarios con que ya te has autenticado en el período se ven en el [dashboard de la conexión](https://app.apigateway.cl/connections/dashboard).

## Límite de consultas

El límite estándar es de **60 consultas por minuto** por conexión. Los límites de API Gateway están basados en los del SII y se ajustan si estos cambian.

Las respuestas traen `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RateLimit-Reset` para que puedas controlarlo desde tu integración. Revisa [Bloqueos y límites de uso](https://www.apigateway.cl/docs/solucion-de-problemas/bloqueos-y-limites-de-uso).




---

## Créditos

Qué es un crédito, las tres formas en que se consume y cómo monitorear el saldo.

# Créditos

El **crédito** es la unidad con que se mide y se cobra todo en API Gateway.

- Se compran en **números enteros**, con un mínimo por compra que la plataforma indica al generar el cobro.
- Son **de la conexión**: cada conexión tiene su propio saldo, no se comparten ni se traspasan entre conexiones.
- El servicio es **prepago**: no hay saldo negativo ni facturación a posteriori.

> [!INFO] Dónde ver el valor del crédito y los costos
>
> El valor del crédito, el costo mensual de cada producto y el costo por consulta de cada recurso están en el [cotizador de precios](https://www.apigateway.cl/pricing), que además incluye un video explicativo del modelo de cobro. Los costos no se listan acá para que siempre consultes el valor vigente.

Los saldos y costos se expresan con tres decimales, porque la mayoría de las consultas cuesta una fracción de crédito.

> [!WARNING] La coma es separador de decimales
>
> Cuando la plataforma dice `20,000 créditos` está diciendo **veinte** créditos, no veinte mil. Al comprar, escribir la cantidad con separador de miles genera una cotización por un monto miles de veces mayor al que buscabas. Revisa siempre la cantidad y el monto de la cotización antes de transferir.

## Las tres formas en que se consumen

### 1. Base mensual, el día 1 de cada mes

Se descuenta la suma del costo de **cada producto activo** más el **pack de usuarios de autenticación** contratado. Ese total es tu **base mensual**, y lo ves en [Gestionar conexión → Productos](https://app.apigateway.cl/connections/manage#products) como *"Base mensual estimada (tu selección)"*.

Si el día 1 tu saldo no cubre la base **completa**, la conexión se suspende. No hay cobro parcial.

Al comprar créditos después de una suspensión, el sistema cobra solo el **proporcional de los días que quedan** del mes y reactiva la conexión automáticamente.

### 2. Cada consulta a la API

**Además** de la base mensual, cada llamada descuenta el costo de su operación. Tener el producto activo te da **acceso** a los recursos; no incluye las consultas.

El costo varía según lo que la operación implica del lado del SII: una consulta simple cuesta mucho menos que una que descarga y procesa un documento. El detalle por recurso está en el [cotizador](https://www.apigateway.cl/pricing) y en la [documentación de la API](https://www.apigateway.cl/docs/api).

### 3. Usuarios de autenticación adicionales

Cada credencial distinta con que te autentiques en el SII, más allá de las incluidas en tu pack, descuenta créditos una vez por período. Revisa [Productos y límites](https://www.apigateway.cl/docs/manual/productos-y-limites).

## Créditos de bienvenida

Al crear tu primera conexión recibes créditos de bienvenida, pensados para una **prueba de concepto**: validar que los recursos entregan lo que tu sistema necesita.

Se agotan rápido si activas varios productos, porque la activación cobra de inmediato. Conviene activar solo el producto que vas a probar y revisar antes la [documentación del recurso](https://www.apigateway.cl/docs/api), porque una consulta mal armada consume créditos igual y devuelve un error.

No es posible ampliarlos ni entregar una segunda tanda. Y crear cuentas o conexiones adicionales para acumularlos provoca el **bloqueo de las cuentas involucradas**, conforme a los [términos y condiciones](https://www.apigateway.cl/legal).

## Qué consultas consumen créditos

**No consumen** los rechazos que ocurren antes de llegar al SII: token inválido, producto no activo, créditos insuficientes o IP en uso por otra conexión.

**Sí pueden consumir** las consultas que llegaron al SII, incluso si terminan en error. Un `409` por indisponibilidad del SII descuenta el costo de la operación, porque la operación se ejecutó.

## Cómo monitorear el saldo

- La cabecera **`X-Stats-Credits-Remaining`** viene en las respuestas de la API. Léela en tu integración y dispara una alerta interna cuando el saldo baje de tu base mensual.
- El [dashboard de la conexión](https://app.apigateway.cl/connections/dashboard) muestra el consumo por consulta y por día.
- El **historial de eventos de la conexión** registra los descuentos mensuales y las activaciones de productos. Revisa [Dashboard y registros](https://www.apigateway.cl/docs/manual/dashboard-y-registros).

## Vencimiento y reembolsos

Los créditos **no caducan por fecha**, pero se consumen: mientras haya productos activos, la base mensual descuenta créditos cada día 1 aunque no hagas consultas.

**No hay reembolsos** de créditos comprados ni consumidos, y **no se traspasan** entre conexiones. Revisa los [términos y condiciones](https://www.apigateway.cl/legal).

> [!TIP] Si vas a dejar de usar una conexión por un tiempo
>
> Desactivar los productos detiene el cargo fijo mensual, y desactivar no tiene costo. El saldo restante queda disponible. Ten presente que volver a activarlos se cobra de nuevo.




---

## Cobros y pagos

Cómo generar un cobro, pagarlo, notificar una transferencia y con qué datos se emite la factura.

# Cobros y pagos

Todo el proceso ocurre en la plataforma. **Soporte no genera cotizaciones, no valida pagos manualmente y no activa servicios.**

## El flujo completo

**1. Prepara los datos de facturación.** En [Gestionar conexión → Datos de facturación](https://app.apigateway.cl/connections/manage#billing-data). Si necesitas que la factura incluya una **orden de compra** u otra referencia, ingrésala acá **antes** de generar el cobro: después no se puede modificar.

**2. Genera el cobro.** En [Gestionar conexión → Créditos](https://app.apigateway.cl/connections/manage#credits) indicas la cantidad de créditos que quieres comprar.

**3. Verifica la cantidad y el monto.** La cotización muestra la cantidad de créditos y el monto exacto a pagar, con IVA incluido, y la cantidad también en texto.

> [!WARNING] Revisa el monto antes de transferir
>
> La coma es separador de decimales: `20,000 créditos` son veinte. Si escribes la cantidad con separador de miles, la cotización saldrá por un monto miles de veces mayor. Si el monto no es el que esperabas, elimina el cobro y genera uno nuevo.

**4. Paga.** En [Gestionar conexión → Cobros](https://app.apigateway.cl/connections/manage#charges), opción **"Pagar"** del cobro generado. Ahí eliges el medio de pago y, si vas a transferir, encuentras los datos bancarios.

**5. Si pagaste por transferencia, notifícala.**

## Medios de pago

En el enlace de pago del cobro se ofrecen **Webpay** (tarjetas de crédito y débito) y **transferencia electrónica**. Los medios disponibles y los datos bancarios aparecen ahí según el monto del cobro: no se entregan por soporte, para asegurar que correspondan a la cotización que estás pagando.

No existe **pago automático**, débito automático ni suscripción con cargo recurrente.

## Notificar una transferencia

Después de transferir, entra al enlace de pago y usa **"Realizar y notificar pago"**. Eso notifica el pago mediante **Linkify** y el sistema lo valida automáticamente.

Casos particulares:

- **Varias transferencias para un mismo cobro**: al notificar, indica la fecha de la **primera**.
- **Pagos masivos o "modo proveedores"**, cuando tu empresa no puede usar Linkify: envía el comprobante a `pagos@sasco.cl`.

> [!WARNING] El monto debe ser exacto
>
> El sistema valida comparando el monto transferido con el del cobro. Una diferencia mínima, de unos pocos pesos, impide la validación. Transfiere siempre el monto exacto que indica la cotización.

## Eliminar un cobro

En [Gestionar conexión → Cobros](https://app.apigateway.cl/connections/manage#charges), opción **"Eliminar"**.

Es lo que debes hacer si generaste el cobro por una cantidad equivocada, o si necesitas emitirlo con otros datos de facturación: eliminas el cobro, corriges y generas uno nuevo.

Un cobro **ya pagado** no se elimina ni se modifica, y sus datos —RUT a facturar, referencias— tampoco.

> [!WARNING] Genera el cobro antes de pagar
>
> Un pago que no corresponde a un cobro vigente **no se puede aplicar**, y los pagos no se devuelven. Genera siempre el cobro primero y transfiere el monto que ese cobro indica.

## Facturación

Emitimos **factura electrónica** por el pago del servicio, al RUT registrado en los datos de facturación de la conexión. **No se emite boleta.**

Los datos se toman al momento de generar el cobro, así que actualízalos antes.

## Si tu empresa opera con cotización, orden de compra y factura

El flujo funciona, con la condición de que **la cotización la generas tú en la plataforma**:

1. Ingresa referencias y datos de facturación en la conexión.
2. Genera la cotización. Ahí obtienes el documento con el monto exacto.
3. Tramita tu orden de compra interna con esa cotización.
4. Paga el monto exacto y notifica.

> [!WARNING] Hazlo con anticipación
>
> La conexión se suspende si el día 1 no hay saldo para la base mensual. Si tus procesos internos de pago toman días, genera la cotización con holgura: regularizar después toma más tiempo que anticiparse.




---

## Token y certificado

Generación del token de la conexión y obtención del certificado digital en formato PEM.

# Token y certificado

## Token de la conexión

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** las 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 también donde se configuran. El token por sí solo no "lleva" servicios: la autorización se resuelve al consultar, según los productos activos de la conexión.

**Regenerar el token invalida el anterior de inmediato.** Actualiza tu integración al hacerlo.

Trátalo como una contraseña: no lo publiques en repositorios ni en código que compartas. Si sospechas que se filtró, regenéralo.

> [!WARNING] No es la API Key de tu usuario
>
> La API Key de [Mi perfil](https://app.apigateway.cl/users/profile) es otra credencial, para operar sobre tu cuenta y tus conexiones. Para consumir recursos del SII necesitas el **token de la conexión**.

## Formato de la cabecera

La única forma admitida es el esquema `Token`. La API **no acepta** `Bearer`, ni `X-Api-Key`, ni el token como parámetro en la URL.

```http
Authorization: Token 0123456789abcdef0123456789abcdef01234567   ← correcto
Authorization: Bearer 0123456789abcdef0123456789abcdef01234567  ← incorrecto
Authorization: 0123456789abcdef0123456789abcdef01234567         ← incorrecto
```

Enviar la clave sin la palabra `Token` produce `Las credenciales de autenticación no se proveyeron.`

## Certificado digital en formato PEM

Algunos recursos requieren autenticación con **certificado digital**, y la API lo espera en formato **PEM**. Tu certificado normalmente viene en un archivo `.p12` o `.pfx`.

La pestaña [Gestionar conexión → Certificado](https://app.apigateway.cl/connections/manage#certificate) convierte tu certificado al formato requerido. También puedes usar la utilidad pública de [tools.libredte.cl](https://tools.libredte.cl/utilities/certificate/inspect), o seguir 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 la conexión: debes enviarlo en el cuerpo de cada consulta que lo requiera.

Una vez que tienes el PEM:

```json
{
  "auth": {
    "cert": {
      "cert-data": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
      "pkey-data": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----"
    }
  }
}
```

También se acepta el archivo PFX en base64, según el recurso:

```json
{
  "auth": {
    "cert": {
      "file-data": "<pfx en base64>",
      "file-pass": "<clave del certificado>"
    }
  }
}
```

## Qué método de autenticación usar

**Lo define cada recurso**, y su documentación lo indica. 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. Revisa [Errores de autenticación en la API](https://www.apigateway.cl/docs/solucion-de-problemas/errores-de-autenticacion-en-la-api).

## Caché de sesión del SII

Cuando envías credenciales en el cuerpo, API Gateway inicia sesión en el SII y **reutiliza esa sesión unas dos horas**. Es intencional: acelera las consultas siguientes y reduce el riesgo de bloqueos por exceso de logins.

Si la sesión queda en mal estado, la API responde `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 forzar una sesión nueva agregando `auth_cache=0` a la URL.

> [!WARNING] No uses `auth_cache=0` en todas tus peticiones
>
> Cada forzado equivale a un login nuevo en el SII. Usarlo permanentemente en producción aumenta el riesgo de que el SII bloquee tus accesos.




---

## Dashboard y registros

Métricas de uso de la conexión, actividad reciente de la API e historial de eventos.

# Dashboard y registros

Hay dos lugares donde ver qué está pasando con tu conexión, y responden preguntas distintas.

## Dashboard de la conexión

[El dashboard](https://app.apigateway.cl/connections/dashboard) responde **"¿cuánto estoy consumiendo y en qué?"**. Incluye:

- **Información de la conexión**: estado, saldo de créditos, base mensual y fecha del próximo cobro.
- **Métricas de uso**: consultas por día, por hora y por día de la semana.
- **Créditos consumidos** en el tiempo.
- **Recursos más consultados**.
- **Códigos de respuesta**, útil para detectar un patrón de errores que estás pagando.
- **Actividad reciente (Últimas 10 peticiones)**: el detalle de cada llamada. Ver más abajo.
- **Usuarios de autenticación** con los que te has autenticado en el período.

## Actividad reciente

Dentro del mismo dashboard, el panel **"Actividad reciente (Últimas 10 peticiones)"** detalla llamada por llamada:

| Columna | Qué muestra |
|---|---|
| Hora | Momento en que se recibió la petición |
| Método | `GET`, `POST`, etc. |
| Endpoint | El recurso consultado |
| Status | El código de respuesta que devolvió la API |
| Créditos utilizados | Lo que descontó esa llamada |
| Tiempo | Cuánto tardó realmente en responder |
| IP | Desde dónde se consultó |

> [!WARNING] Solo las últimas 10
>
> El panel guarda únicamente las **10 peticiones más recientes**. Si tu integración sigue consultando, una llamada que quieras revisar desaparece rápido. Ante un error que necesites investigar, míralo de inmediato.

Sirve para dos cosas:

**Verificar un consumo que no cuadra.** Cada línea muestra los créditos que descontó esa llamada, así que puedes identificar cuál costó más de lo esperado. Un descuento mayor al costo del recurso suele corresponder a un **usuario de autenticación adicional**, que se cobra una vez por período.

**Comparar el tiempo de respuesta real** con lo que mide tu cliente: si tu cliente cortó por timeout antes de que la API respondiera, la diferencia queda a la vista en la columna Tiempo.

## Historial de eventos de la conexión

El historial responde **"¿por qué cambió mi configuración o mi saldo?"**. Registra:

- Los **descuentos mensuales** del día 1, con el monto exacto.
- Las **actualizaciones de productos y límites**, con lo que se cobró.
- Las **suspensiones por créditos insuficientes**, con el compromiso mensual y el saldo disponible en ese momento.
- Los **intentos rechazados por IP en uso** por otra conexión.

Para llegar, estando dentro de tu conexión, haz clic en el **logo verde** ubicado en la parte superior derecha del sitio y entra a **"Historial de eventos de la conexión"**.

> [!TIP] Ante una duda de cobro, parte por acá
>
> Antes de abrir un ticket por un descuento inesperado, revisa el historial de eventos y la actividad reciente. La gran mayoría de las diferencias corresponde al cargo fijo mensual, a la activación de un producto o a un usuario de autenticación adicional, y las tres quedan registradas con su monto.





---
Última actualización el 11/09/2026