Utilisation
Le point d'entrée
Tous les appels passent par le contrôleur frontal pwa/api.php du module, avec
un jeton OAuth client_credentials obtenu auprès de smartauth. Le webservice
appelant conserve ce jeton en cache pendant sa durée de vie, diminuée d'une
marge, et ne le consigne jamais dans ses journaux.
Les verbes sortants
Chaque opération de l'API porte ici le nom de verbe. Le module en expose sept.
| Verbe | Chemin | Rôle |
|---|---|---|
GET catalogue |
catalogue |
Renvoie les fiches produit du préfixe de l'appelant, ainsi que MAIN_MAX_DECIMALS_UNIT |
POST tiers |
tiers |
Crée le tiers d'un client, ou retrouve le sien ; idempotent sur le SIREN |
POST commandes |
commandes |
Crée une commande et ses lignes ; idempotent sur la référence d'acte |
POST validation |
commandes/{ref}/validation |
Valide la commande et renvoie son lien de paiement |
GET règlement |
commandes/{ref}/reglement |
Renvoie l'état du règlement et rejoue la notification non acquittée |
POST annulation |
commandes/{ref}/annulation |
Annule une commande non réglée |
POST avoir |
commandes/{ref}/avoir |
Établit un avoir partiel sur un acte réglé |
Quatre règles valent pour l'ensemble des verbes :
- Hors de son périmètre, l'appelant reçoit un 404 uniforme : l'objet lui est déclaré inexistant.
- Le prix provient toujours de la fiche produit, et un service sans prix est refusé.
- Une ligne se lit "7 mois à 1,65833" : une quantité entière, multipliée par le prix de la fiche.
- Le lien de paiement est renvoyé par le verbe de validation, et n'est jamais reconstitué chez l'appelant.
Le webhook de règlement
Lorsqu'un règlement est accepté sur la facture d'une commande issue de l'API,
le module envoie au webservice une notification payment.accepted, signée en
HMAC-SHA256, à l'URL de webhook déclarée sur sa fiche. La signature voyage dans
l'en-tête X-Dolibarr-Signature et se calcule sur le corps brut du message,
avec le secret propre au client. La charge utile contient la référence d'acte,
le tiers, le montant et la date du règlement, mais jamais le lien de paiement.
Une notification perdue ne se rattrape pas par une simple lecture. Trois voies permettent de la renvoyer : le verbe d'état de règlement la rejoue à la demande de l'appelant, le bouton de l'onglet Journal des notifications de règlement la rejoue depuis Dolibarr, et le cron du module retente automatiquement celles qui ont échoué.
