Login

Qué hace

Autentica al comercio y obtiene un JWT para consumir endpoints protegidos.

Cuándo usarlo

Úsalo al iniciar una sesión de integración o cuando el JWT actual expire.

Endpoint

POST /login

Consulta URL base y rutas para seleccionar el ambiente de tu integración.

Autenticación

Requiere la API key del ambiente en x-api-key. Esta operación obtiene el token para las solicitudes protegidas posteriores.

Headers requeridos

• country obligatorio con valor CL.
• commerce obligatorio, de 5 a 30 caracteres, con el identificador de comercio asignado.
• channel obligatorio, de al menos 3 caracteres, con el canal autorizado.
• requestDateTime obligatorio, con fecha y hora en formato ISO 8601.
• correlationId obligatorio, de al menos un carácter. Se recomienda un UUID para trazabilidad.
• processId: obligatorio. Para el flujo de nuevas integraciones documentado en esta guía, utiliza HYBRID.
• salesExecutiveId obligatorio, de al menos un carácter.
• x-api-key correspondiente al ambiente y al plan de consumo asignado.

Identificadores soportados

username debe corresponder al comercio/RUT configurado por Forpay y debe ser consistente con el header commerce.

Body / Parámetros

password debe venir en formato JWE. No se acepta la contraseña en texto plano.

Reglas de negocio

• Usar POST /login como estándar para nuevas integraciones.
• Guardar el token solo en backend seguro y renovarlo antes de expirar.

Respuesta exitosa

Devuelve payload.token. El token de acceso es un JWT cifrado, entregado como JWE compacto de cinco segmentos y con una vigencia de 30 minutos. Envíalo en Authorization: Bearer <token>, junto con la API key del ambiente y el contexto y permisos autorizados para el comercio y la ruta.

Errores comunes

Los errores capturados por el handler de login se responden con 403, incluidos datos mal formados, credenciales inválidas y ciertas fallas internas. Un 403 requiere revisar el detalle recibido y el contexto de la solicitud.

API Gateway también puede rechazar una solicitud antes del handler. Sus errores pueden usar un cuerpo con message, y tienen sus propios códigos de autenticación, límites o timeout. Consulta los límites de tasa, ráfaga y cuota asignados a tu API key con Forpay. Ante un 429, reduce la frecuencia y aplica espera progresiva antes de reintentar.

Notas de integración

Genera un JWE de contraseña nuevo para cada intento, también al reintentar después de un error o timeout. La entrada cifrada puede quedar registrada antes de validar la contraseña. Conserva el token de acceso en el backend y renueva el login cuando expire.

Ejemplo recomendado

Usa el ejemplo incluido en el body del request como plantilla inicial y reemplaza los placeholders {{...}} o <...>.