> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zonavirtual.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticación

> Cómo autenticarse con el API de Zonapagos.

## Modelo actual

Zonapagos autentica cada request **dentro del cuerpo JSON**. No hay headers `Authorization`, ni API keys en la URL, ni JWT, ni OAuth.

Cada endpoint espera tres campos de autenticación, con un detalle de naming que hay que conocer:

| Endpoint                 | Campo ID                                             | Campo usuario      | Campo clave        |
| ------------------------ | ---------------------------------------------------- | ------------------ | ------------------ |
| `POST /InicioPago`       | `int_id_comercio` (dentro de `InformacionSeguridad`) | `str_usuario`      | `str_clave`        |
| `POST /VerificacionPago` | `int_id_comercio` (raíz)                             | `str_usr_comercio` | `str_pwd_Comercio` |

<Warning>
  Los nombres de los campos son **diferentes** entre los dos endpoints. `str_usuario` en uno y `str_usr_comercio` en el otro contienen el mismo valor. Lo mismo aplica para `str_clave` / `str_pwd_Comercio`. Hay que respetar el naming exacto de cada endpoint.
</Warning>

## Obtener credenciales

Las credenciales se asignan al activar tu cuenta comercial. Son:

<ParamField path="int_id_comercio" type="integer" required>
  Identificador único del comercio. Ej. `31416`.
</ParamField>

<ParamField path="str_usuario / str_usr_comercio" type="string" required>
  Nombre de usuario técnico. Máximo 40 caracteres.
</ParamField>

<ParamField path="str_clave / str_pwd_Comercio" type="string" required>
  Clave. Máximo 50 caracteres. Se puede cambiar desde el portal de Zonapagos.
</ParamField>

Contacta a [comercial@zonapagos.com](mailto:comercial@zonapagos.com) si aún no las tienes.

## Seguridad operativa

<Check>**Usa siempre HTTPS.** El API solo acepta conexiones TLS.</Check>
<Check>**Guarda las credenciales en secret manager** (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, Vault de Hashicorp, variables de entorno cifradas). Nunca en código ni en repositorios.</Check>
<Check>**Rota la clave** periódicamente desde el portal de Zonapagos.</Check>
<Check>**Monitorea accesos** a tus credenciales en tu infra. Una clave comprometida permite iniciar pagos a tu nombre (aunque el dinero va a tu cuenta comercial, no a la del atacante).</Check>

<Warning>
  **Limitaciones de seguridad actuales del API (conocer y planificar mitigaciones):**

  * No existe mecanismo de firma HMAC de los requests.
  * No hay TOTP ni MFA para el cambio de clave.
  * El callback GET al comercio no incluye una firma verificable. El parámetro `rut` de la URL del ciclo de pago **no se devuelve al comercio en el callback** — solo `id_comercio` e `id_pago`. Debes verificar el estado final llamando `VerificacionPago` desde tu backend; nunca confíes en el callback como fuente de verdad.

  *\[Pendiente con TI: evaluar incorporación de firma de request y verificación de callback.]*
</Warning>

## Errores de autenticación

| Síntoma                                                                       | Diagnóstico                                                                                      |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `int_codigo: 2` con `str_descripcion_error` mencionando credenciales          | Usuario o clave incorrectos.                                                                     |
| `int_codigo: 2` con `"Object reference not set to an instance of an object."` | `int_id_comercio` inválido, o estás usando credenciales dummie contra el API REST de producción. |
| HTTP 200 pero `int_codigo: 2` sin descripción útil                            | Validar que el JSON está bien formado y que todos los campos obligatorios están presentes.       |

Más detalle en [Manejo de errores](/docs/zonapay/guias/manejo-errores).

## Próximo paso

<Card title="Convenciones del API →" icon="book" href="/docs/zonapay/api/convenciones">
  Tipos de dato, formatos numéricos y reglas generales.
</Card>