Comment connecter ERP, e-commerce et paiements avec des APIs REST solides

Quand la boutique en ligne, l’ERP et la passerelle de paiement ne parlent pas le même langage, le métier le ressent : commandes en double, stock obsolète ou encaissements que personne ne peut expliquer. Le problème n’est pas « il manque un endpoint » ; c’est l’absence d’un contrat clair entre systèmes.

Cet article explique comment concevoir des APIs REST pour des intégrations serveur à serveur — avec des analogies simples, des étapes concrètes et le détail technique dont une équipe a besoin pour construire sans accumuler de dette. Cela s’applique aux ERP, à l’e-commerce et aux passerelles comme Yappy, BAC ou Paguelo Fácil.

Pourquoi c’est important pour le métier

Une intégration fragile se comporte comme un téléphone avec une mauvaise couverture : parfois le message arrive, parfois il se duplique, parfois il disparaît. Chaque échec coûte du support, de la compta manuelle et de la confiance client.

• Commandes : le client a payé, mais l’ERP ne le voit pas → retards d’expédition.
• Stock : on vend ce qui n’existe plus → annulations et mauvaise réputation.
• Paiements : deux prélèvements pour une tentative → réclamations et chargebacks.
• Support : sans ID partagé entre systèmes, personne ne sait ce qui a échoué.

Concepts clés (en clair et en technique)

Imaginez l’API comme un guichet de banque : il y a un formulaire (request), une réponse signée (response) et des règles pour ne jamais encaisser deux fois le même document (idempotence).

• Contrat : ce qui est envoyé, reçu, et quelles erreurs existent. En technique : OpenAPI avec exemples.
• Idempotence : réessayer ne duplique pas. En technique : header Idempotency-Key sur les POST de création.
• Versionnement : les gros changements ne cassent pas les anciens clients. En technique : /v1/ vs /v2/.
• Auth minimale : chaque système ne fait que le nécessaire. En technique : API keys avec scopes.
• Correlation ID : un numéro de suivi qui traverse tous les systèmes. Facilite support et logs.

Structure de ressources recommandée

Modèle courant pour e-commerce + ERP + paiements :

Guide pratique : de zéro à une intégration stable

1. Authentification serveur à serveur

• API keys avec scopes minimaux (lecture stock seule, écriture commandes seule).
• HMAC sur les webhooks : le récepteur valide la signature avec un secret partagé.
• OAuth2 client credentials quand le fournisseur l’exige (SAP, certains ERP cloud).
• Rotation documentée ; jamais de keys dans les repos, query strings ou images Docker.

2. Webhooks vs polling

Un webhook est un avis : « paiement confirmé ». L’émetteur appelle ; le récepteur valide la signature, enregistre l’événement et répond 200. C’est le canal préféré pour les événements métier.

Le polling, c’est demander à intervalle régulier : « des nouvelles ? ». À utiliser seulement en secours ou si le système externe ne supporte pas les callbacks. Toujours avec backoff exponentiel et limite de tentatives.

3. Erreurs prévisibles

Une réponse cohérente permet à l’autre système de décider : réessayer, alerter ou abandonner ?

            {
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order 12345 does not exist",
    "correlation_id": "abc-123"
  }
}
          

• Codes HTTP clairs : 400 (input invalide), 401 (auth), 404 (inexistant), 409 (conflit/idempotence), 429 (rate limit), 500 (erreur interne).
• Ne jamais exposer stack traces ni SQL en production.
• Inclure correlation_id dans header et body pour le support cross-system.

4. Quand l’ERP est en panne

1. L’e-commerce crée la commande locale avec le statut pending_sync.
2. Un job en file tente la synchro avec tentatives et backoff.
3. Après N échecs, passage en dead-letter queue et alerte à l’équipe.
4. Le client a déjà vu la confirmation ; la synchro se réconcilie ensuite.

Erreurs fréquentes

• Concevoir « un endpoint par écran » sans modèle de ressources stable.
• Marquer les commandes comme payées uniquement parce que l’utilisateur a atteint une URL de succès.
• Réessayer un POST sans idempotence et dupliquer paiements ou commandes.
• Changer le contrat /v1/ sans préavis (breaking change silencieux).
• Logs sans correlation ID : support à l’aveugle entre systèmes.
• Credentials partagés « pour tout » au lieu de scopes minimaux.

Checklist d’intégration

1. Contrat OpenAPI avec exemples request/response et erreurs.
2. Authentification avec scopes minimaux et rotation des keys.
3. Idempotence sur les POST de création (Idempotency-Key).
4. Webhooks avec validation HMAC et tentatives de l’émetteur.
5. Files pour synchro async avec dead-letter.
6. Logs avec correlation ID, sans PII ni secrets.
7. Rate limiting sur les endpoints publics.
8. Sandbox et production séparés, avec credentials distincts.
9. Politique de dépréciation (ex. 90 jours) avant de retirer un endpoint.
10. Tests de contrat entre consommateur et fournisseur quand plusieurs équipes sont impliquées.

Voir aussi intégrations, paiements au Panama et protection des APIs .