Mise à jour des Contacts via l’API

Vous pouvez ajouter et mettre à jour des Contacts dans Payreq Delivery à l’aide de l’API Payreq. Cette méthode est généralement utilisée lorsque vous souhaitez conserver les enregistrements de Contacts directement à partir d’un autre système, tel qu’une plateforme de facturation, de paie ou CRM, que vous le fassiez vous-même ou via un mailhouse ou un partenaire technologique.

L’API convient aux mises à jour automatisées des Contacts, à la synchronisation récurrente et aux flux de travail opérationnels plus vastes pour lesquels les mises à jour manuelles de la console ou les fichiers SFTP ne sont pas préférés.

Plus de détails sont disponibles dans la Spécification de l’interface Payreq ou dans l’onglet API Payreq sous Paramètres.

À quoi sert l’API Contacts

L’API Contacts permet à un utilisateur autorisé de l’API d’envoyer des enregistrements de Contact à Payreq Delivery. Selon le point de terminaison utilisé, il peut :

• Ajouter de nouveaux Contacts
• Mettre à jour les Contacts existants
• Remplacer la liste complète des Contacts pour un Mailer
• Soumettre les mises à jour des Contacts en arrière-plan pour les fichiers ou volumes de données plus volumineux

Payreq utilise les données de Contact pour aider à identifier les clients, faire correspondre les demandes d’Abonnement et prendre en charge la livraison numérique.

Avant de commencer

Avant d’utiliser l’API Contacts, vérifiez que :

• Votre organisation a été configurée pour l’accès à l’API Payreq (voir Gestion des utilisateurs dans Payreq Delivery).
• Vous disposez d’un utilisateur API ayant accès au compte Payreq Delivery correspondant
• Vous connaissez le bon code de facturier
• La configuration de votre champ Contact a été confirmée
• Vous comprenez si votre mise à jour doit ajouter/mettre à jour les Contacts ou remplacer la liste complète des Contacts
• Vous avez testé le processus avant de l’utiliser pour mettre à jour les Contacts en production

Les valeurs requises par l’API doivent correspondre aux paramètres des champs de Contact configurés pour votre compte. Pour plus de détails, voir Comprendre les paramètres des champs de Contact.

Authentification

Pour utiliser l’API Payreq, authentifiez-vous d’abord et récupérez un jeton API. Incluez le jeton dans l’en-tête Authorization pour les demandes ultérieures :

Authorization: Token <token>

Les jetons API ont une durée de validité limitée, configurée par le service. Prévoyez de demander un nouveau jeton lorsque le jeton actuel expire, sans supposer une durée fixe.

Points de terminaison de l’API Contacts

L’API Contacts comprend quatre points de terminaison principaux pour l’ajout ou la mise à jour des Contacts.

Choisir le bon point de terminaison

Ajouter des Contacts. Utilisez le point de terminaison add pour ajouter de nouveaux Contacts ou mettre à jour les Contacts existants correspondants. Si un Contact existe déjà avec le même biller-account-number, ses détails sont remplacés par les valeurs de la demande. Utilisez-le pour des mises à jour incrémentielles, telles que l’ajout de nouveaux comptes, la mise à jour des détails modifiés, la correction des informations existantes ou la maintenance des données de Contact dans le cadre d’une synchronisation régulière.

Remplacer les Contacts. Utilisez le point de terminaison replace uniquement lorsque la demande contient la liste complète des Contacts qui doit rester dans Payreq Delivery. Utilisez-le avec précaution, car il actualise ou remplace le jeu de Contacts existant pour le Mailer. Avant d’utiliser un point de terminaison de remplacement, vérifiez que :

• La demande contient tous les Contacts requis
• Les identifiants de compte existants ont été conservés le cas échéant
• L’effet possible sur les Abonnements actifs a été pris en compte
• La mise à jour a été testée et revue
• La personne ou le système soumettant la demande est autorisé à effectuer un remplacement complet du Contact.

Points de terminaison de la tâche. Pour les volumes de Contacts plus importants, utilisez les points de terminaison de la tâche. Ceux-ci soumettent la mise à jour en tant que tâche en arrière-plan et renvoient un ID de tâche. Après la soumission, surveillez le traitement avec le point de terminaison du statut de la tâche :

GET /biller/{biller-code}/jobs/{job-id}

Les statuts actuels des tâches sont pending-file, in-progress, done et error. Une réponse peut aussi contenir des erreurs de vérification malgré un statut HTTP 200. Examinez donc le corps de la réponse avant d’accepter l’ID de tâche.

Données des Contacts

L’API Contacts accepte un objet JSON contenant les enregistrements dans un tableau contacts. Chaque Contact doit inclure :

• biller-account-number
• name

Le contrat externe actuel définit aussi contact-id-1, auth-item-1 à auth-item-4, business-identifier, les champs de nom et les champs d’adresse postale. Les champs à utiliser dépendent des paramètres des champs de Contact de votre organisation. Confirmez le mappage de votre compte avant d’envoyer des mises à jour.

Exemple de charge utile de Contact

Il s’agit uniquement d’un exemple simplifié.

{
  "contacts": [
    {
      "biller-account-number": "123456",
      "name": "Example Customer",
      "contact-id-1": "C123456",
      "auth-item-1": "A123456",
      "address-1": "1 Example Street",
      "municipality": "Melbourne",
      "province": "VIC",
      "postal-code": "3000"
    },
    {
      "biller-account-number": "789012",
      "name": "Second Example Customer",
      "contact-id-1": "C789012",
      "auth-item-1": "A789012"
    }
  ]
}

Dans cet exemple :

• biller-account-number identifie le Contact.
• name est le nom du client enregistré pour ce Contact.
• contact-id-1 et les champs auth-item contiennent les valeurs définies par les paramètres des champs de Contact du compte.

Les champs exacts utilisés par votre organisation peuvent être différents.

Processus recommandé

1. Récupérez un jeton API.
2. Préparez les enregistrements de Contact au format JSON requis.
3. Vérifiez que chaque Contact comprend les champs obligatoires.
4. Soumettez la demande au point de terminaison de Contact approprié.
5. Vérifiez la réponse de l’API.
6. Pour les points de terminaison de tâche, interrogez le point de terminaison de l’état de la tâche jusqu’à ce que le traitement soit terminé.
7. Recherchez toute erreur ou tout résultat inattendu.
8. Confirmez que les enregistrements de Contact attendus sont visibles dans Payreq Delivery.

Examen de la réponse

Pour les demandes ordinaires d’ajout ou de remplacement, une réponse réussie renvoie le nombre de Contacts traités et le code de facturier correspondant. Pour les demandes de tâche, examinez la réponse complète : elle peut contenir un ID de tâche, des erreurs de vérification, ou les deux. N’acceptez la tâche qu’après avoir confirmé la présence de l’ID attendu et l’absence d’erreurs.

Si une demande échoue, examinez la réponse d’erreur et corrigez le problème avant de la soumettre à nouveau.

Problèmes de validation courants

• Champs obligatoires manquants
• Format JSON invalide
• Valeurs en double pour biller-account-number dans la même requête
• Longueur biller-account-number incorrecte
• Valeurs des champs de Contact qui ne correspondent pas aux exigences du champ configuré
• Tentative de remplacement des Contacts par une liste de Contacts incomplète ou inattendue
• Utilisation d’un mauvais code de facturier
• Utilisation d’un jeton d’authentification expiré ou mal formaté