En este artículo recorrerá los primeros pasos para trabajar con la API PSB: desde la solicitud de una cuenta hasta la realización de su primera llamada a la API. Al finalizar, dispondrá de una conexión funcional con el entorno de prueba y sabrá cómo está estructurada la API.

Para utilizar la API PSB necesita credentials. Puede solicitarlos a través del formulario de contacto en la página de producto PSB en econnect.eu. Tras el registro, recibirá tres datos:

Consejo: solicite directamente credentials tanto para el entorno de aceptación como para el de producción. Así podrá realizar pruebas de forma segura sin riesgo de enviar facturas reales por accidente.

Dependiendo del flujo OAuth2 elegido, también puede recibir un username y un password para el flujo Resource Owner Password Credentials. Para integraciones servidor-a-servidor, se recomienda el flujo Client Credentials y solo necesitará el clientId y el clientSecret.

El PSB cuenta con dos entornos. Utilice el entorno de aceptación para desarrollo y pruebas, y el entorno de producción para transacciones reales.

El entorno de aceptación funciona de manera idéntica a producción: las solicitudes de tokens, las llamadas API y los webhooks se comportan de la misma forma. La diferencia es que los documentos no se envían a la red Peppol real.

Atención: utilice credentials separados para aceptación y producción. De este modo evita que credentials de prueba terminen accidentalmente en un entorno de producción.

Cada solicitud API al PSB requiere un Bearer token. Este token se solicita al Identity Server mediante una petición POST a /connect/token.

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

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

En caso de éxito, recibirá una respuesta JSON con el access token:

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

El token es válido durante 3600 segundos (1 hora). Después de expirar, simplemente solicite un nuevo token. El proceso completo de autenticación, incluyendo el flujo Resource Owner Password Credentials y la renovación de tokens, se describe en el artículo sobre autenticación.

Con un token válido puede llamar a la API. Un buen punto de partida es el endpoint GET /api/v1/me, que devuelve información sobre su cuenta y las organizaciones (parties) asociadas a ella.

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

Una respuesta exitosa contiene la información de su cuenta y una lista de parties para las que está autorizado. Cada party tiene un PartyId (por ejemplo, un número KvK u OIN) y permisos que determinan lo que puede hacer: enviar documentos, recibirlos, eliminarlos o gestionar hooks.

Puede entregar documentos en cualquier formato soportado por el PSB: UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X, FatturaPA y más de 20 estándares adicionales. El PSB detecta el formato automáticamente y lo transforma al formato esperado por el destinatario. Por lo tanto, no necesita saber qué formato utiliza el destinatario.

La API PSB devuelve todas las respuestas en formato JSON. Los documentos en sí (facturas, pedidos) se envían y reciben en XML.

Los códigos de estado HTTP siguen las convenciones REST estándar:

En caso de un error 4xx, la respuesta contiene un mensaje de error indicando el problema. En caso de errores 5xx, es aconsejable reintentar la solicitud con exponential backoff.

El PSB tiene dos roles que determinan lo que un usuario puede hacer.

ApUser es el rol estándar. Con este rol puede enviar y recibir documentos, y gestionar webhooks para las parties a las que está asociado.

ApManager cuenta además con derechos de administración: crear y eliminar usuarios, registrar organizaciones en el registro Peppol SMP/SML, y utilizar la Enrollment API para configurar nuevas parties.

Por party, los permisos se configuran individualmente: canSendDocument, canReceiveDocument, canRemoveDocument y canManageHook. Cada party registrada debe estar asociada al menos a una cuenta ApUser.

La referencia API completa está disponible como Swagger UI en psb.econnect.eu. Allí puede explorar los endpoints, consultar los formatos de solicitud y respuesta, y probar llamadas API con su propio token. El archivo swagger.json también se puede descargar para generar código cliente en el lenguaje de su elección con herramientas como OpenAPI Generator.