Dans cet article, vous parcourez les premières étapes pour travailler avec l'API PSB : de la demande d'un compte à la réalisation de votre premier appel API. À la fin, vous disposerez d'une connexion fonctionnelle à l'environnement de test et saurez comment l'API est structurée.

Pour utiliser l'API PSB, vous avez besoin de credentials. Vous les demandez via l'assistant sandbox. Après inscription, vous recevez trois informations :

Conseil : demandez directement des credentials pour l'environnement d'acceptation et de production. Ainsi, vous pouvez tester en toute sécurité sans risquer d'envoyer de vraies factures par accident.

Selon le flux OAuth2 choisi, vous recevrez éventuellement aussi un username et un password pour le flux Resource Owner Password Credentials. Pour les intégrations serveur-à-serveur, le flux Client Credentials est recommandé et vous n'avez besoin que du clientId et du clientSecret.

Le PSB dispose de deux environnements. Utilisez l'environnement d'acceptation pour le développement et les tests, et l'environnement de production pour les transactions réelles.

L'environnement d'acceptation fonctionne de manière identique à la production : les demandes de tokens, les appels API et les webhooks se comportent de la même façon. La différence est que les documents ne sont pas envoyés au véritable réseau Peppol.

Attention : utilisez des credentials distincts pour l'acceptation et la production. Vous évitez ainsi que des credentials de test se retrouvent accidentellement dans un environnement de production.

Chaque requête API au PSB nécessite un Bearer token. Vous demandez ce token auprès de l'Identity Server via une requête POST vers /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 cas de succès, vous recevez une réponse JSON contenant le access token :

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

Le token est valide pendant 3600 secondes (1 heure). Après expiration, vous demandez simplement un nouveau token. Le processus d'authentification complet, y compris le flux Resource Owner Password Credentials et le renouvellement de tokens, est décrit dans l'article sur l'authentification.

Avec un token valide, vous pouvez appeler l'API. Un bon point de départ est l'endpoint GET /api/v1/me, qui renvoie des informations sur votre compte et les organisations (parties) qui y sont associées.

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

Une réponse réussie contient vos informations de compte et une liste des parties pour lesquelles vous êtes autorisé. Chaque partie possède un PartyId (par exemple un numéro KvK ou OIN) et des permissions qui déterminent ce que vous pouvez faire : envoyer des documents, en recevoir, les supprimer ou gérer les hooks.

Vous pouvez livrer des documents dans tout format supporté par le PSB : UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X, FatturaPA et plus de 20 autres standards. Le PSB détecte le format automatiquement et le transforme vers le format attendu par le destinataire. Vous n'avez donc pas besoin de savoir quel format le destinataire utilise.

L'API PSB retourne toutes les réponses au format JSON. Les documents eux-mêmes (factures, commandes) sont envoyés et reçus en XML.

Les codes de statut HTTP suivent les conventions REST standard :

En cas d'erreur 4xx, la réponse contient un message d'erreur indiquant le problème. En cas d'erreur 5xx, il est conseillé de réessayer la requête avec un exponential backoff.

Le PSB dispose de deux rôles qui déterminent ce qu'un utilisateur peut faire.

ApUser est le rôle standard. Il permet d'envoyer et de recevoir des documents, et de gérer les webhooks pour les parties auxquelles vous êtes associé.

ApManager dispose en plus de droits d'administration : créer et supprimer des utilisateurs, enregistrer des organisations dans le registre Peppol SMP/SML, et utiliser l'Enrollment API pour configurer de nouvelles parties.

Par partie, les permissions sont configurées individuellement : canSendDocument, canReceiveDocument, canRemoveDocument et canManageHook. Chaque partie enregistrée doit être associée à au moins un compte ApUser.

La référence API complète est disponible sous forme de Swagger UI sur psb.econnect.eu. Vous pouvez y explorer les endpoints, consulter les formats de requête et de réponse, et tester des appels API avec votre propre token. Le fichier swagger.json est également téléchargeable, ce qui vous permet de générer du code client dans le langage de votre choix avec des outils comme OpenAPI Generator.