> ## 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.

# API Reference

> Referencia técnica completa del API REST de Zonapagos.

## URL base

<CodeGroup>
  ```txt Producción theme={null}
  https://www.zonapagos.com/Apis_CicloPago/api
  ```

  ```txt Sandbox REST theme={null}
  (No disponible públicamente — contactar soporte para credenciales de preproducción)
  ```
</CodeGroup>

## Endpoints

| Método | Ruta                                                                 | Propósito                                                                        |
| ------ | -------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| POST   | [`/InicioPago`](/docs/zonapay/api/endpoints/inicio-pago)             | Crear una transacción y obtener la URL del ciclo de pago.                        |
| POST   | [`/VerificacionPago`](/docs/zonapay/api/endpoints/verificacion-pago) | Consultar el estado de una o más transacciones.                                  |
| GET    | [callback del comercio](/docs/zonapay/api/endpoints/callback)        | Zonapagos redirige al usuario a tu URL de retorno con `id_comercio` e `id_pago`. |

## Resumen de diseño

* **REST sobre HTTPS**. Nunca llames por HTTP plano.
* **Formato**: `application/json` tanto en request como en response.
* **Siempre HTTP 200**. Los errores de negocio se señalan vía `int_codigo: 2` dentro del cuerpo JSON. Códigos HTTP distintos a 200 indican error de infraestructura (URL mal escrita, content-type faltante, caída de red, etc.).
* **Autenticación por credenciales en el body** (no hay headers de Authorization). Ver [Autenticación](/docs/zonapay/api/autenticacion).
* **Endpoints sin paginación ni límites de rate publicados**. Si necesitas hacer consultas masivas, coordina con soporte.

<Warning>
  **Importante sobre códigos HTTP:** hemos verificado empíricamente que el API responde HTTP 200 incluso ante credenciales inválidas o payloads incompletos. No asumas HTTP 200 como sinónimo de éxito — siempre lee `int_codigo` del cuerpo. *\[Pendiente de TI: documentar formalmente esta convención y considerar si algún escenario sí retorna HTTP ≠ 200.]*
</Warning>

## Modelo de objetos

<CardGroup cols={2}>
  <Card title="InformacionPago" icon="receipt" href="/docs/zonapay/api/objetos/informacion-pago">
    Datos del pago y del cliente.
  </Card>

  <Card title="InformacionSeguridad" icon="lock" href="/docs/zonapay/api/objetos/informacion-seguridad">
    Credenciales del comercio.
  </Card>

  <Card title="AdicionalPago" icon="plus" href="/docs/zonapay/api/objetos/adicional-pago">
    Array de información adicional del pago.
  </Card>

  <Card title="AdicionalConfiguracion" icon="sliders" href="/docs/zonapay/api/objetos/adicional-configuracion">
    Array de configuración del comportamiento del ciclo de pago.
  </Card>

  <Card title="RespuestaInicioPago" icon="arrow-right-from-bracket" href="/docs/zonapay/api/objetos/respuesta-inicio-pago">
    Estructura del response de `InicioPago`.
  </Card>

  <Card title="RespuestaVerificacion" icon="magnifying-glass-chart" href="/docs/zonapay/api/objetos/respuesta-verificacion">
    Estructura del response de `VerificacionPago`.
  </Card>
</CardGroup>

## Tablas de referencia

<CardGroup cols={2}>
  <Card title="Estados de pago" icon="list-check" href="/docs/zonapay/api/referencia/estados-pago">
    Todos los valores de `int_estado_pago` con su acción recomendada.
  </Card>

  <Card title="Medios de pago" icon="credit-card" href="/docs/zonapay/api/referencia/medios-pago-codigos">
    Códigos `int_id_forma_pago` y campos adicionales por medio.
  </Card>

  <Card title="Tipos de identificación" icon="id-card" href="/docs/zonapay/api/referencia/tipos-id">
    Valores válidos para `str_tipo_id`.
  </Card>

  <Card title="Configuraciones adicionales" icon="gear" href="/docs/zonapay/api/referencia/adicionales-configuracion">
    Todos los códigos de `AdicionalesConfiguracion`.
  </Card>
</CardGroup>

## Formatos especiales

El API usa dos formatos que merecen atención especial:

<CardGroup cols={2}>
  <Card title="Parsear str_res_pago" icon="code" href="/docs/zonapay/api/formatos/parsear-str-res-pago">
    El campo viene como texto plano con separadores `|` y `|;|`. Tenemos parser en JS, Python y C#.
  </Card>

  <Card title="Campos por medio de pago" icon="code-compare" href="/docs/zonapay/api/formatos/campos-por-medio-pago">
    Cada medio de pago añade campos extra al final de `str_res_pago`.
  </Card>
</CardGroup>

## Próximo paso

<Card title="Ir a /InicioPago →" icon="play" href="/docs/zonapay/api/endpoints/inicio-pago">
  El endpoint donde empieza todo.
</Card>