---
title: "Utilisation"
weight: 30
description: "Les sept verbes de l'API, le webhook de règlement et le journal des notifications."
---

# 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é.

![Journal des notifications de règlement, avec les statuts et le bouton de rejeu](screenshots/journal-notifications.webp)