Spécification d'intégration API
Intégration : Commandes de la boutique vers la comptabilité
Version : 1.0
Rédigé par : Hamza Idrissi
Date : 5 avril 2029
1. Objectif
Envoyer chaque commande payée de la boutique en ligne au système comptable sous forme de facture de vente, afin que le service financier ne la saisisse pas à nouveau.
2. Systèmes
- Envoie les données : Boutique en ligne (API v2)
- Reçoit les données : Système comptable (API REST)
3. Flux de données
1. Un client paie une commande.
2. La boutique envoie un webhook au service d'intégration.
3. Le service transforme la commande en facture et appelle l'API comptable.
4. Le système comptable renvoie un numéro de facture, que le service enregistre sur la commande.
4. Points de terminaison et messages
| Méthode et chemin | Ce qu'il fait | Champs principaux | Ce qu'il renvoie |
|---|---|---|---|
| POST /invoices | Créer une facture | Corps : client, lignes, taxe, total | Renvoie : identifiant et numéro de facture |
| GET /customers?email= | Rechercher un client | Renvoie : identifiant du client ou vide | |
| POST /customers | Créer un client | Corps : nom, e-mail, adresse |
5. Correspondance des champs
order.total_paid → invoice.total
order.billing_email → customer.email
order.items[].sku → line.product_code
6. Authentification et sécurité
OAuth 2.0 avec identifiants client. Les jetons durent une heure. Les secrets sont conservés dans le coffre-fort, jamais dans le code. Tous les appels utilisent HTTPS. Les webhooks sont signés et la signature est vérifiée.
Les données personnelles ne sont envoyées que lorsque cela est nécessaire, ne sont pas écrites dans les journaux et sont couvertes par les conditions de confidentialité des deux systèmes.
7. Erreurs et nouvelles tentatives
Réessayez sur les erreurs 429 et 5xx jusqu'à 5 fois avec des délais croissants. Ne réessayez pas les erreurs 4xx ; journalisez-les et alertez le service financier. Chaque facture possède une clé unique afin qu'une nouvelle tentative ne crée pas de doublon.
8. Limites et volumes
L'API comptable autorise 60 appels par minute. Prévision de 400 commandes par jour, jusqu'à 2 000 les jours de soldes.
9. Tests
Utilisez l'environnement de test comptable. Testez une commande normale, une commande avec remise, un remboursement, un client déjà existant et une panne de l'API.
10. Responsables et support
Responsable : équipe e-commerce. Support : Hamza Idrissi. Escalade : le support du fournisseur comptable.
11. Modifications et gestion des versions
Chaque partie prévient 30 jours à l'avance en cas de changement incompatible.