Autenticacion

API Keys

Todas las peticiones a la External API requieren una API key valida en la cabecera HTTP X-API-KEY.

Cabeceras requeridas

Cabecera	Requerida	Descripcion
`X-API-KEY`	Si	Tu API key de acceso
`Content-Type`	Si (POST)	`application/json`
`Idempotency-Key`	No	UUID unico para evitar duplicados (recomendado en POST)

Ejemplo

curl -X POST https://aviratopayments.com/external/v1/payment/session \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ ... }'

Entornos

La External API dispone de dos entornos independientes: Live y Test. Cada entorno tiene sus propias API keys, su propio client secret y sus propios datos (completamente aislados entre si).

Live	Test
Proposito	Pagos reales en produccion	Desarrollo e integracion sin dinero real
Rutas	`/external/v1/...`	`/external/v1/test/...`
API Key	Key de entorno Live	Key de entorno Test
Client Secret	Secret del entorno Live	Secret del entorno Test
Datos	Datos de produccion	Datos aislados de test

API Keys de Live

Las API keys de Live procesan pagos reales contra el procesador. Solo usa keys de Live cuando tu integracion este completamente validada.

API Keys de Test

Las API keys de Test permiten probar toda la integracion sin mover dinero real. Los pagos se simulan, los webhooks se generan automaticamente, y los datos se almacenan de forma completamente aislada.

Flujo de integracion recomendado: Empieza siempre con una API key de Test. Desarrolla y valida toda tu integracion. Cuando todo funcione correctamente, crea una API key de Live y cambia las URLs (anade o quita /test/).

Restriccion por IP

Las API keys pueden tener restricciones de IP configuradas desde el dashboard. Si tu IP no esta en la lista permitida, recibiras un error 403 Forbidden.

Recomendacion: Configura restricciones de IP en produccion para mayor seguridad. En el entorno Test, puedes dejar las IPs sin restriccion para facilitar el desarrollo.

Restriccion por Webcode

Cada API key esta vinculada a un webcode especifico (identificador de tu negocio en Avirato Payments). Solo puedes operar con el webcode asociado a tu key.

El campo webcode es obligatorio en todas las peticiones y debe coincidir con el webcode de tu API key.

Scopes

Las API keys tienen un scope que determina a que endpoints pueden acceder:

Entorno	Scope	Rutas accesibles
Live	`external_api_live`	`/external/v1/...`
Test	`external_api_test`	`/external/v1/test/...`

Una key de Live no puede acceder a rutas de Test, y viceversa.

Idempotencia

Los endpoints de escritura (crear sesion, modificaciones, pago POS) soportan la cabecera Idempotency-Key. Si envias la misma Idempotency-Key con los mismos parametros:

La primera peticion se procesa normalmente
Las siguientes peticiones con la misma key devuelven la misma respuesta sin ejecutar la operacion de nuevo

La idempotencia funciona de forma identica en ambos entornos (Live y Test). Los registros de idempotencia de cada entorno estan aislados entre si.

Conflictos de idempotencia (409)

Si reutilizas una Idempotency-Key de forma incorrecta, la API responde con 409 Conflict para evitar comportamientos inconsistentes:

Caso	Mensaje (literal)
Misma `Idempotency-Key` con body distinto en el mismo endpoint	`Idempotency key reused with a different request body.`
Misma `Idempotency-Key` en otro endpoint	`Idempotency key already used for a different endpoint.`

Recomendacion: usa Idempotency-Key siempre en produccion para evitar cobros duplicados, pero asocia una clave unica por intento logico (por ejemplo, derivada del orderId + retry). Si necesitas modificar el body, usa una clave nueva.

# Primera llamada: crea el pago
curl -X POST .../payment/session \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{ "webcode": "SHOP01", "amount": { "value": 10000, "currency": "EUR" }, ... }'

# Segunda llamada con la misma key y mismo body: devuelve la misma respuesta sin crear otro pago
curl -X POST .../payment/session \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{ "webcode": "SHOP01", "amount": { "value": 10000, "currency": "EUR" }, ... }'

# Tercera llamada con la misma key pero distinto body: 409 Conflict
curl -X POST .../payment/session \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{ "webcode": "SHOP01", "amount": { "value": 99999, "currency": "EUR" }, ... }'

Client Secret

Cada entorno tiene su propio client secret. El client secret se usa para descifrar los datos cifrados que llegan en el redirect post-pago (parametro data en la urlOk).

Client secret de Live: se genera al crear la primera API key de Live.
Client secret de Test: se genera al crear la primera API key de Test.

El client secret solo se muestra una vez al momento de crear la primera key del entorno. Si lo pierdes, puedes rotarlo desde el dashboard (seccion Integraciones > API Keys > Rotar Secret).

Importante: Los client secrets de Live y Test son diferentes. Asegurate de usar el secret correcto para descifrar los datos del redirect en cada entorno.

Gestion de API Keys

Las API keys se gestionan desde el Dashboard de Avirato Payments (seccion Integraciones > API Keys):

Accion	Descripcion
Crear	Genera una nueva key para el entorno seleccionado (Live o Test). Si es la primera key de ese entorno, tambien genera el client secret
Listar	Ver todas las keys activas con su configuracion y entorno
Editar IPs	Modificar restricciones de IP
Revocar	Desactiva permanentemente una key
Regenerar	Genera un nuevo valor de key (mantiene la configuracion)
Rotar Secret	Genera un nuevo client secret para un entorno

Documentación para desarrolladores