Autenticación y ambientes

• Autenticación y ambientes
  • Cómo autenticas cada llamada
  • Prueba y producción
  • Qué necesitas antes de empezar
  • Sucursal (office)
  • Token de webhooks
  • Errores de autenticación

Cómo autenticas cada llamada

Todas las llamadas a la API van con tu token en el header Authorization:

curl -X GET \
'/api/v1/offices/get' \
-H 'Authorization: Bearer TU_TOKEN' \
-H 'Content-type: application/json'

La URL base de la API es https://sag-qa.efipay.co/api/v1. Todos los endpoints de esta documentación cuelgan de ahí.

{warning} Usa sag.efipay.co. sag-qa.efipay.co es nuestro ambiente interno de pruebas: puede reiniciarse o quedarse abajo sin aviso. Para construir y probar tu integración, apunta a sag.efipay.co con un token de prueba: ahí no se mueve dinero y el servicio tiene la disponibilidad de producción.

{info} Esta documentación se publica en los dos ambientes y muestra el host del ambiente en el que la estás leyendo. Si copiaste una URL desde la doc de QA, te llevaste el host de QA sin darte cuenta. Ahora mismo estás leyendo la de https://sag-qa.efipay.co.

Genera y revoca tus tokens en el panel, en Documentación → API key. El token se muestra una sola vez: guárdalo en tu gestor de secretos, no en el código.

{danger} Un token da acceso a cobrar en nombre de tu comercio. Nunca lo pongas en código de frontend, en un repositorio, ni en una aplicación móvil. Todas las llamadas se hacen desde tu servidor.

Prueba y producción

Hay dos tipos de token y el tipo decide en qué ambiente ocurre todo:

No cambies de URL para probar. Dentro de un mismo host es la misma API; lo que decide si el dinero se mueve es el token. Un cobro creado con token de prueba solo se puede consultar y pagar con token de prueba, y viceversa: los dos ambientes de datos no se ven entre sí.

{info} Al listar transacciones, el ambiente lo decide el token (api-access:test o api-access:production), no un query param. Si envías production, se ignora. Es la causa número uno de «no aparece mi transacción»: estás consultando con el token del otro ambiente.

{warning} Las reservas de cupo en modalidad api solo funcionan con token de producción: retienen fondos reales y no hay forma de simular una retención que después puedas cobrar o liberar.

Qué necesitas antes de empezar

1. Una cuenta de comercio activa. Si tu comercio está deshabilitado o su estado no es activo o en revisión, la API responde 403 en todo.
2. Un token, de prueba para empezar.
3. El id de tu sucursal, que piden casi todos los endpoints que crean algo.

Sucursal (office)

Muchos endpoints piden un campo office con el id de una de tus sucursales: generar un pago, crear un plan, un suscriptor, un cupón. Obtén el tuyo con GET /api/v1/offices/get y guárdalo en tu configuración; no cambia.

Si tu comercio tiene una sola sucursal, siempre será ese id.

Token de webhooks

Es distinto del token de la API y tiene un solo propósito: verificar que un webhook que recibes viene de nosotros y no de un tercero. Lo encuentras en el mismo lugar del panel.

Nunca lo envíes en una petición; solo se usa para calcular la firma de los webhooks que recibes. Ver Webhooks.

{danger} Como el token es único y no rotable, trátalo como un secreto de larga vida: guárdalo en tu gestor de secretos, no lo dejes en el repositorio y no lo registres en logs. Si crees que se filtró, escríbenos: la rotación hay que coordinarla.

Errores de autenticación

{success} Respuesta de una llamada autenticada correctamente code: 200

{danger} Token ausente o inválido code: 401

{
"message": "Unauthenticated."
}

{danger} Comercio o usuario que no puede operar code: 403

{
"message": "Unauthorized"
}