Autenticación y ambientes

Autenticación y ambientes

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.efipay.co/api/v1. Todos los endpoints de esta documentación cuelgan de ahí.

Ambiente	Host	Cuándo lo usas
Producción	`https://sag.efipay.co/api/v1`	Siempre que integres de verdad, con token de prueba o de producción
QA	`https://sag-qa.efipay.co/api/v1`	Solo si te pedimos probar contra QA en un acompañamiento

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.

Prueba y producción

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

	Token de prueba	Token de producción
Para qué	Construir y probar tu integración	Cobrar de verdad
Movimiento de dinero	Ninguno	Real
Resultado de un pago	Lo decides tú con las tarjetas de prueba	Lo decide la red
Se ve en tu reporte	Sí, marcado como prueba	Sí
Se abona a tu cuenta virtual	No	Sí

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

Qué necesitas antes de empezar

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.
Un token, de prueba para empezar.
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.


Alcance	Uno por comercio. No hay uno por sede: todas las sedes firman con el mismo token
Ambientes	El mismo para prueba y producción. No se puede tener uno distinto por ambiente
Rotación	Hoy no se puede rotar desde el panel

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

Errores de autenticación

Código	Significa	Qué revisar
`401`	No llegó el token, o no es válido	El header `Authorization: Bearer ...`. Que no lo hayas revocado
`403`	El token es válido pero no puede operar	Que tu comercio esté activo y habilitado, y que el usuario del token esté activo
`404` en un recurso que sí creaste	Estás mirando el otro ambiente	Que el token sea del mismo tipo con el que creaste el recurso

200OK 401Unauthorized

{
    "message": "Unauthenticated."
}

403Forbidden

{
    "message": "Unauthorized"
}