La API PSB de eConnect utiliza OAuth 2.0 para la autenticación. Cada solicitud API contiene un Bearer token que se obtiene del Identity Server de eConnect. Este token es válido durante una hora y contiene toda la información que la PSB necesita para determinar quién es usted, en nombre de qué organización trabaja y qué está autorizado a hacer.

En este artículo recorrerá el proceso completo de autenticación: desde la comprensión del modelo de autenticación hasta la solicitud y el uso de tokens.

La PSB funciona con cuatro capas de identificación. Cada capa responde a una pregunta diferente, y juntas determinan el acceso a la API.

Capa 1: Aplicación (clientId + clientSecret) Identifica el software que se conecta a la PSB. Por lo general, un socio de software utiliza un único conjunto clientId/clientSecret para todos sus clientes finales. Esto simplifica la incorporación: los clientes finales necesitan completar menos datos técnicos y la probabilidad de errores de configuración es menor. Todos los clientIds tienen el mismo scope (ap) y, por tanto, los mismos permisos funcionales.

Capa 2: Cliente final (username + password) Identifica en nombre de qué organización se trabaja. Para cada cliente final, eConnect crea una cuenta de usuario PSB vinculada a uno o varios partyIds (número de cámara de comercio, número de IVA, OIN, número de empresa belga). Con el flujo Resource Owner Password Credentials, se proporcionan un username y un password que determinan a qué parties se puede acceder. Con el flujo Client Credentials, esto no es necesario porque los permisos están vinculados directamente a la aplicación. El nombre de usuario y la contraseña se proporcionan normalmente directamente al cliente final; el cliente final los comparte después con el proveedor de software.

Capa 3: Entorno (tenantId) Ofrece separación administrativa entre entornos. Cada cliente final recibe normalmente su propio tenant, lo que garantiza una separación completa de mensajes, configuración y logging. Algunos socios de software agrupan varios clientes finales en un solo tenant para una gestión centralizada; otros eligen un tenant separado por cliente para un aislamiento máximo. Los tenants no se pueden fusionar, pero las cuentas de usuario se pueden modificar o ampliar.

Capa 4: Logging (subscription key, legacy) El header Subscription-Key estaba originalmente destinado a la identificación en los archivos de log de la API. Para la API PSB, este header ya no es obligatorio. Si lo envía, el valor debe ser válido. eConnect emite a veces aún subscription keys porque permiten rastrear cada solicitud hasta un socio de software específico en los logs. Nota: para la plataforma eConnect (platform.econnect.eu) la subscription key sigue siendo obligatoria.

Para solicitar un token, envíe una solicitud POST al endpoint /connect/token del Identity Server.

Este es el flujo recomendado para integraciones de servidor a servidor. Solo envía su clientId y clientSecret.

POST /connect/token HTTP/1.1
Host: identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=su-client-id
&client_secret=su-client-secret
&scope=ap

Con este flujo, también proporciona un nombre de usuario y una contraseña. Esto es útil cuando los permisos están vinculados a un usuario final específico.

POST /connect/token HTTP/1.1
Host: identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=password
&client_id=su-client-id
&client_secret=su-client-secret
&username=su-nombre-de-usuario
&password=su-contrasena
&scope=ap

En caso de una solicitud exitosa, recibirá un objeto JSON con el access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "ap"
}

El campo expires_in indica cuántos segundos es válido el token. Por defecto son 3600 segundos (1 hora).

Envíe el Bearer token en el header Authorization de cada solicitud API a la PSB:

GET /api/v1/me HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

La PSB valida el token en cada solicitud. Si el token es inválido o ha expirado, recibirá una respuesta 401 Unauthorized.

Un Bearer token es válido durante 3600 segundos. Después de expirar, debe solicitar un nuevo token a través del mismo endpoint /connect/token. No existe un flujo de actualización separado: simplemente repite la solicitud de token.

En la práctica, es conveniente solicitar un nuevo token poco antes de que expire el actual, por ejemplo después de 3500 segundos. De este modo evita que una llamada API falle debido a un token expirado mientras la solicitud está en tránsito.

1. Token solicitado              → válido hasta t+3600s
2. Después de ~3500s: nuevo token → token anterior aún ~100s válido
3. Cambiar al nuevo token

Almacene el token en su aplicación y reutilícelo para múltiples solicitudes. No solicite un nuevo token en cada solicitud API, ya que esto genera carga innecesaria en el Identity Server.

Por defecto, un socio de software utiliza un único conjunto clientId/clientSecret para todos sus clientes finales. En algunas situaciones, es recomendable utilizar múltiples conjuntos:

• Separar pruebas y producción. Utilice un clientId distinto para el entorno de aceptación (accp-identity.econnect.eu) y para producción (identity.econnect.eu). Así evita que credenciales de prueba terminen accidentalmente en producción.
• Instalaciones on-premise. Si el software se ejecuta en las instalaciones del cliente final y este tiene acceso a la configuración, un clientSecret compartido puede representar un riesgo de seguridad. Con un clientId distinto por cliente, limita el daño en caso de filtración de credenciales.
• Permisos separados por integración. Si desarrolla múltiples aplicaciones independientes que necesitan diferentes funcionalidades API (por ejemplo, un módulo de facturación y un módulo de pedidos), puede utilizar un clientId propio por aplicación con solo los permisos necesarios.

La revocación de un clientSecret solo afecta al clientId correspondiente. Los demás clientes o integraciones no se ven afectados.

Si recibe un 401 al realizar una llamada API a la PSB, verifique primero si el token todavía es válido. En la mayoría de los casos ha expirado y basta con solicitar un nuevo token.

El diagrama a continuación muestra cómo una aplicación solicita un token al Identity Server y luego utiliza ese token para llamar a la API PSB.

La referencia API completa, incluyendo todos los endpoints y los formatos de solicitud/respuesta, se encuentra en la documentación Swagger interactiva.