1. Authentication

Antes de consumir cualquier endpoint de la API de Forpay, es obligatorio autenticarse y obtener un token de acceso. Todos los endpoints posteriores requieren que se incluya este token en el encabezado Authorization como un Bearer JWT.

Endpoint de login

GET /login

URL base: https://devapi.forpayservices.cl/white/label

Headers requeridos

Header	Descripción	Ejemplo
`x-api-key`	API key asignada a tu empresa	`r3M*************HC^`
`country`	Código de país	`CL`
`commerce`	RUT + ID interno de tu empresa	`77209349.150`
`channel`	Canal de integración asignado	`EMPRESA_WEB`
`requestDateTime`	Fecha/hora de la solicitud en formato ISO 8601	`2024-01-01T00:00:00.000`
`correlationId`	ID único para trazabilidad de la solicitud	`12345`
`processId`	Proceso de integración asignado	`HYBRID`
`salesExecutiveId`	Identificador del ejecutivo (puede ser fijo)	`12345`

Query parameters

Parámetro	Tipo	Requerido	Descripción
`username`	string	Sí	RUT + ID interno de la empresa (igual que `commerce`)
`password`	string	Sí	Password cifrado en formato JWE

Cómo generar el password JWE

El password debe enviarse cifrado en formato JWE (JSON Web Encryption) utilizando:

Algoritmo: RSA-OAEP-256
Cifrado: A256GCM
Librería recomendada: jose (Node.js/JavaScript)

El proceso de cifrado debe realizarse en el backend de tu sistema. Nunca compartas el password en texto plano.

Ejemplo con la librería `jose` (Node.js)

import { CompactEncrypt, importSPKI } from 'jose';

const publicKeyPem = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----`;

const plainPassword = '(7g7e28hj83d';

const publicKey = await importSPKI(publicKeyPem, 'RSA-OAEP-256');

const jwe = await new CompactEncrypt(
  new TextEncoder().encode(plainPassword)
)
  .setProtectedHeader({ alg: 'RSA-OAEP-256', enc: 'A256GCM' })
  .encrypt(publicKey);

// jwe es el valor a enviar como query param `password`
console.log(jwe);

Respuesta exitosa (200 OK)

{
  "statusCode": 200,
  "message": "ACCESS_CONFIRM",
  "payload": {
    "token": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0..."
  }
}

Respuesta de error (403 Forbidden)

{
  "statusCode": 403,
  "message": "Prohibido",
  "code": "FORBIDDEN"
}

Cómo usar el token JWT

Una vez obtenido el token del payload de respuesta, inclúyelo en todas las solicitudes posteriores mediante el encabezado:

Authorization: Bearer <token>

Consideraciones importantes

El token tiene una validez de 30 minutos desde su emisión.
El token está asociado a la empresa con la que se realizó el login. Usar un token de otra empresa puede generar mandatos cruzados.
Cuando el token expire, debes volver a llamar a /login para obtener uno nuevo.
Automatiza la generación del JWE en tu backend para evitar errores manuales.
Implementa mecanismos de re-autenticación automática: si recibes un error de token expirado, genera un nuevo JWE, autentica y actualiza el JWT en tu sistema.