Gestión de credenciales

Primeros pasos

Procedimiento para dar de alta tu empresa y gestionar las credenciales necesarias para consumir las APIs REST a través del API Manager de Frisvy.

Alta de cliente (empresa recaudadora)

Para que tu empresa pueda usar las APIs REST expuestas por Frisvy, primero debe darse de alta como empresa recaudadora. Para esto se gestionan las credenciales con el equipo de producto, que solicitará la siguiente información:

• Correo electrónico a asociar a la cuenta cliente.
• CUIT de la empresa.
• IPs de origen: lista de IPs v4 desde las cuales los sistemas del cliente generarán las solicitudes HTTPS (requerido para UAT y producción).
• Flujos / productos a los que se requiere acceso (definen los scopes asignados).

Según los productos a contratar, internamente se asigna a la cuenta un grupo de usuario que define la lista de scopes: los permisos explícitos de consumo sobre cada API.

Frisvy nunca administra tu contraseña Una vez confirmada la información, se da de alta la cuenta y se envía un correo al email asociado con un link para que vos mismo establezcas tu contraseña, a través del Self Management Portal: portal.apim.frisvy.com

Resumen del flujo de alta

1. Coordinás con el equipo de producto el alta de la empresa.
2. Informás el email, las IPs y los flujos a asociar a la cuenta.
3. Frisvy da de alta la cuenta cliente.
4. Recibís un correo en el email asociado para establecer tu contraseña.
5. Ya podés generar tokens de sesión a través de los endpoints de login usando tus credenciales.

Consumo de las APIs REST

Para consumir cualquier API expuesta por Frisvy primero hay que generar un token de sesión contra el endpoint de login. El flujo es el siguiente:

1. Enviás tus credenciales en el header Authorization con la estructura Basic Base64(user:pass), y el header Scope con los scopes para los que querés generar la sesión (separados por espacios).
2. Frisvy valida las reglas de seguridad y el origen de la solicitud (la IP debe estar registrada como válida para el cliente).
3. Si las credenciales coinciden, se genera un token de sesión JWT con la información de scopes, grupo de usuario y tiempo de expiración (normalmente 1 hora).
4. Enviás ese token en cada solicitud subsecuente a través del header Authorization: Bearer {access_token} hasta que expire.

Generar un token de sesión

Request — POST /auth/login

curl -X POST \
  'https://apim.{ambiente}.frisvy.com/auth/login' \
  --header 'Authorization: Basic {CREDENCIALES_BASE_64}' \
  --header 'Scope: ibcobros.renditions.read'

Una respuesta exitosa devuelve la siguiente estructura:

Response 200

{
  "access_token": "eyJraWQiOiJMcWRE....",
  "refresh_token": "eyJjdHkiOiJKV1Qi...",
  "expires_in": 3600
}

Reutilizá el token El token JWT está diseñado para reutilizarse durante su vigencia (≈1 hora). No se recomienda generar un token nuevo por cada solicitud, ya que puede impactar la performance del lado del cliente. Si las credenciales son erróneas, el login responde HTTP 401.

Renovación del token

El token expira a los expires_in segundos (normalmente 3600 = 1 hora). Cuando detectes que ya no es válido (por ejemplo, al recibir un HTTP 401 en una API de negocio), volvé a llamar al endpoint de login con tus credenciales para obtener un nuevo access_token. La respuesta también incluye un refresh_token para los flujos que lo soporten.

Una buena práctica es cachear el token y su vencimiento, y renovarlo de forma anticipada (por ejemplo, unos minutos antes de expires_in) en lugar de esperar al 401.

Dominios de login por ambiente

En la URL se reemplaza {ambiente} por el ambiente correspondiente. Los ambientes disponibles para usuarios son qa y uat; en producción no se incluye la parte de ambiente.

Scopes por producto

Cada scope habilita acciones concretas sobre un producto o flujo. Se envían en el header Scope separados por espacios. Los scopes que tiene asignada tu cuenta dependen de los productos contratados.

Login externo de plataforma (Botón de Pago)

Además del login de APIs de negocio, Frisvy expone un login externo de plataforma que permite a sistemas externos autenticar a un usuario y abrir la interfaz de Frisvy (por ejemplo, para el flujo de Botón de Pago). Se consume con el scope ibcobros.externallogin.write contra el endpoint POST /platform/v1/account/login/external, y devuelve un token_key que luego se usa para iniciar una orden de pago. El detalle de ese flujo está en la sección de Publicación de deuda.