Parallèlement à l’échange de fichiers via SFTP, Payreq Delivery propose une API JSON-REST pour gérer les Contacts, soumettre et suivre les tâches de traitement et vérifier les résultats de livraison par programme. Voir Spécification de l’interface Payreq pour savoir comment cela s’intègre à la méthode d’intégration SFTP.
À qui s’adresse-t-il
Ce document de référence technique s’adresse à l’équipe de développement d’un Mailhouse ou au contact technique d’un expéditeur qui met en place une intégration automatisée. Pour l’envoi manuel de documents, consultez Téléverser du Courrier. Pour l’échange de fichiers par lots, consultez Téléverser du Courrier via SFTP.
Ce que vous pouvez faire avec l’API
À un niveau élevé, l’API couvre :
- Gérer les Contacts : ajoutez ou remplacez votre liste de Contacts, soit directement, soit en arrière-plan pour des listes plus grandes.
- Soumettre et suivre les tâches : indiquez à Payreq qu’un fichier Bill est prêt à être traité, puis vérifiez son statut. Voir Que sont les tâches? et Comprendre les statuts et les erreurs des tâches pour savoir ce que signifie l’état d’une tâche, que vous l’ayez soumise via la console, SFTP ou l’API.
- Vérifiez les résultats de livraison : voyez où les documents d’une tâche ont été livrés par canal et recherchez les documents qui n’ont pas pu être livrés.
- Vérifier l’état de l’enregistrement : confirmez si un compte spécifique est activement enregistré avant de supposer qu’un échec de livraison est un problème d’enregistrement.
- Liste des comptes accessibles : découvrez à quels comptes de livraison vos informations d’identification API peuvent accéder.
Authentification
L’API utilise des jetons d’authentification. Obtenez un jeton avec un nom d’utilisateur et un mot de passe, puis incluez-le dans chaque appel suivant. Sa durée de validité est configurée par le service et n’est pas garantie à exactement 15 minutes. Demandez un nouveau jeton lorsque le jeton actuel expire plutôt que de programmer une durée fixe.
Obtenir l’accès à l’API
L’accès à l’API est configuré via un compte utilisateur API dans votre compte Payreq Delivery, géré de la même manière que tout autre utilisateur sous Autorisations de compte. Voir Gestion des utilisateurs dans Payreq Delivery pour savoir comment fonctionne généralement l’accès des utilisateurs, y compris une note sur les utilisateurs de l’API mailhouse/partenaire.
Inviter un utilisateur de l’API
Lorsque vous invitez un utilisateur à votre compte, sélectionnez Utilisateur API dans la liste déroulante des types d’utilisateurs, plutôt qu’un utilisateur de console standard.
Une bizarrerie à laquelle s’attendre lorsqu’ils définissent leur mot de passe
L’utilisateur de l’API invité reçoit un courriel de configuration pour créer son mot de passe. Une fois cela fait, ils sont redirigés vers la console Payreq Delivery et une erreur s’affiche, car les utilisateurs de l’API ne sont pas autorisés à accéder à la console elle-même.
Il semble que la configuration du mot de passe ait échoué, mais ce n’est probablement pas le cas. Voir cette erreur est attendu pour un utilisateur API uniquement et ne signifie pas que quelque chose s’est mal passé. Plutôt que de réinitialiser à nouveau le mot de passe, confirmez-le en récupérant un jeton avec les nouvelles informations d’identification.
Les préférences de notification nécessitent également un utilisateur de console
Étant donné qu’un utilisateur de l’API ne peut pas se connecter à la console, il ne peut pas non plus définir ses propres préférences de notification utilisateur, celles-ci sont configurées par utilisateur depuis la console. Si votre seul identifiant auprès d’une organisation est un utilisateur d’API, personne n’est averti lorsque quelque chose nécessite votre attention.
Nous recommandons fortement à chaque organisation utilisant un utilisateur d’API de maintenir également au moins un utilisateur de console standard, avec des notifications configurées pour couvrir les échecs de tâche, Courrier non livrable et le Courrier placé en état d’erreur, et avec une personne capable de se connecter pour afficher les statuts, consulter les messages d’erreur et accéder aux paramètres lorsqu’une intervention est nécessaire. Voir Notifications de l’utilisateur.
Points à vérifier pendant l’intégration
Nom exact de l’en-tête. Utilisez Authorization, et non Authorisation.
Adresse de production. L’adresse de base est https://go.payreq.com/api/v2. N’utilisez pas go.payreq.localhost s’il apparaît dans une ancienne copie de la console.
Corps de la réponse. Un jeton absent ou expiré peut produire une réponse HTTP 200 contenant une erreur. Ne considérez pas le statut HTTP seul comme une confirmation de réussite.
Documentation complète de l’API
La section Payreq API des Paramètres donne accès à la documentation et à un schéma OpenAPI (.yaml). Utilisez la référence externe actuelle fournie par Payreq. Si la copie de la console diffère de cette référence, affiche une adresse localhost ou contient des opérations qui n’ont pas été fournies pour votre intégration, communiquez avec Payreq avant de l’utiliser.
Seul un utilisateur de console peut accéder à cette zone, un utilisateur d’API ne peut pas la visualiser lui-même, ce qui est une autre raison pour garder au moins un utilisateur de console actif sur le compte (voir ci-dessus).
Obtenir la référence technique complète
Si la documentation ou le schéma semble incohérent ou peu clair, communiquez avec votre gestionnaire de compte ou le soutien technique Payreq pour confirmer les renseignements requis par votre intégration.
Articles connexes
Cet article a-t-il été utile ?
C'est super !
Merci pour votre commentaire
Désolé ! Nous n'avons pas pu vous être utile
Merci pour votre commentaire
Commentaires envoyés
Nous apprécions vos efforts et nous allons corriger l'article