Connecter un ERP à un e-commerce et à une passerelle de paiement demande plus qu’« un endpoint ». Il faut des contrats clairs, une authentification robuste, une gestion d’erreurs prévisible et des webhooks idempotents. Sinon, chaque nouvelle intégration devient de la dette technique.
Cet article décrit la conception d’APIs REST pour des intégrations serveur à serveur entre ERP, boutiques en ligne et passerelles comme Yappy, BAC ou Paguelo Fácil.
Principes de conception
- Contrats explicites : chaque endpoint documente request, response et codes d’erreur.
- Idempotence : réessayer un POST ne duplique ni commandes ni paiements.
- Versionnement : les breaking changes vont vers
/v2/, pas de patch silencieux. - Authentification minimale : scopes par ressource, jamais de credentials dans les query strings.
- Observabilité : correlation ID sur chaque requête pour tracer les flux cross-system.
Structure des ressources
Modèle recommandé pour e-commerce + ERP :
| Ressource | Méthodes | Objectif |
|---|---|---|
/v1/orders | POST, GET | Créer et consulter les commandes |
/v1/orders/{id}/status | PATCH | Mettre à jour le statut (avec validation) |
/v1/products/sync | POST | Synchroniser le catalogue depuis l’ERP |
/v1/webhooks/payment | POST | Recevoir la confirmation de la passerelle |
/v1/inventory/{sku} | GET | Consulter le stock en temps réel |
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 des keys documentée ; jamais dans les repos ni les images Docker.
Webhooks vs polling
Webhooks pour les événements métier : paiement confirmé, stock mis à jour, expédition envoyée. L’émetteur notifie ; le récepteur valide la signature, persiste et répond 200.
Polling uniquement en secours ou quand le système externe ne supporte pas les callbacks. Toujours avec backoff exponentiel et limite de tentatives.
Gestion des erreurs
Des réponses cohérentes facilitent l’intégration :
{
"error": {
"code": "ORDER_NOT_FOUND",
"message": "Order 12345 does not exist",
"correlation_id": "abc-123"
}
}
- Codes HTTP sémantiques : 400 (input invalide), 401 (auth), 404 (inexistant), 409 (conflit/idempotence), 429 (rate limit), 500 (erreur interne).
- Ne jamais exposer stack traces ni requêtes SQL en production.
correlation_iddans header et body pour le support cross-system.
Résilience quand l’ERP est en panne
- L’e-commerce crée la commande localement avec le statut
pending_sync. - Un job en file tente la synchro ERP avec tentatives et backoff.
- Après N échecs, passage en dead-letter queue et alerte à l’équipe.
- Le client voit la confirmation ; la synchro se réconcilie ensuite.
Versionnement sans casser les clients
/v1/dans l’URL ou headerAccept-Version: 1.- OpenAPI/Swagger publié et mis à jour à chaque release.
- Politique de dépréciation : préavis 90 jours avant retrait d’un endpoint.
- Tests de contrat (Pact ou similaire) entre consommateur et fournisseur.
Checklist d’intégration
- Contrat documenté (OpenAPI) avec exemples request/response.
- Authentification avec scopes minimaux et rotation des keys.
- Idempotence sur POST de création (header
Idempotency-Key). - Webhooks avec validation HMAC et tentatives de l’émetteur.
- Files pour synchro async avec dead-letter.
- Logs avec correlation ID, sans PII ni secrets.
- Rate limiting sur les endpoints publics.
- Environnements séparés (sandbox/prod) avec credentials distincts.
Voir aussi intégrations, paiements au Panama et protection des APIs .