Un partenaire peut-il accéder directement à notre base de données ?

Non, et c'est la première règle : un partenaire est un utilisateur avec un rôle, qui passe par les mêmes services que votre application, derrière une passerelle qui vérifie sa clé, ses droits par ressource, son quota, le schéma et l'idempotence, et qui journalise chaque appel. Un accès à la base donne tout, à tous, sans trace, et ne se révoque pas sans tout casser.

Que se passe-t-il si un partenaire appelle trop souvent ?

Il a un quota par minute et par jour ; au-delà, il reçoit un 429 avec un en-tête Retry-After qui dit combien de temps attendre, et il ne perd rien en réessayant. Si le dépassement se répète, le quota se relève par écrit, avec une date. Vos propres clients ne sont jamais ralentis par le script d'un partenaire.

Comment un partenaire est-il prévenu quand quelque chose change chez nous ?

Par des webhooks : un événement signé en HMAC-SHA256 avec un horodatage, envoyé à son adresse, réessayé avec un écart croissant jusqu'à trois jours s'il ne répond pas 2xx, identifié de façon unique pour qu'un doublon ne change rien, et rejouable depuis son portail. Il peut toujours relire l'état par l'API : un webhook est une tentative, pas une vérité.

Que se passe-t-il quand nous changeons notre API ?

La version 1 ne change que par ajout : de nouveaux champs ou de nouvelles routes, jamais un retrait. Si un changement incompatible est nécessaire, une version 2 est annoncée avec une date, la version 1 reste supportée douze mois, et un partenaire en retard reçoit une réponse plutôt qu'une erreur. C'est la politique que suivent les grandes plateformes de commerce, écrite dans votre contrat d'API.

Combien de temps pour ouvrir une API à un premier partenaire ?

Dix semaines : une pour le contrat d'API, deux pour la passerelle devant les services existants, une pour le bac à sable et la documentation, deux pour les webhooks, deux pour le premier partenaire en bac à sable puis en production, deux pour geler la version 1. Le partenaire travaille seul pendant la plus grande partie de ce temps, avec la documentation et son journal.

Ouvrir une API à vos partenaires en Algérie en 2027 : clés, droits, quotas, webhooks, versions et documentation, sans exposer votre système

Réponse courte. Un partenaire est un utilisateur avec un rôle, pas une exception : il passe par les mêmes services que votre application, et il n'y a aucune route spéciale. Entre lui et ces services, une passerelle applique six portes, identiques pour tous : connexion chiffrée, clé ou jeton par partenaire et révocable, droits de lecture et d'écriture par ressource, quota par minute et par jour avec un 429 et un délai de réessai, schéma typé et versionné, clé d'idempotence sur chaque écriture ; et chaque passage ou refus laisse une ligne de journal. Ce qui change chez vous part vers lui par des webhooks signés, réessayés à écart croissant pendant trois jours, rejouables depuis un portail. La version 1 est gelée et ne change que par ajout, avec douze mois de support écrits. Dix semaines, dont deux avant qu'un partenaire voie quoi que ce soit.

Ce guide s'adresse au gérant à qui un transporteur, un gros client ou un cabinet demande « un accès », au fondateur installé en France dont la plateforme doit se brancher à des logiciels qu'il ne connaît pas, et au responsable informatique qui doit dire non à l'accès direct à la base sans bloquer l'entreprise. Il ne redit pas comment on se branche soi-même à un logiciel existant, décrit dans le guide sur l'intégration, ni comment les rôles sont construits à l'intérieur de l'application, décrit dans le guide sur les droits ; il décrit l'inverse, ce qui se construit quand ce sont les autres qui se branchent à vous, et il prolonge notre page sur l'ingénierie logicielle.

Ce que les grandes plateformes disent

Les plateformes qui ouvrent des API à des milliers de partenaires publient leurs règles, et elles se transposent. Sur les versions : une grande plateforme de commerce en ligne « publie une nouvelle version d'API tous les trois mois », nomme chaque version par sa date, la garantit « stable pour toute sa durée de support », la supporte « au minimum douze mois », et quand un partenaire appelle une version qui n'existe plus, « répond avec la plus ancienne version stable accessible » au lieu de le rejeter. Ce que cela impose : une version ne change que par ajout, la suivante a une date d'annonce et une date de fin de support écrites, et un partenaire en retard reçoit une réponse, pas une erreur.

Sur les webhooks, la documentation d'une grande plateforme de paiement dit que les événements sont réessayés « jusqu'à trois jours avec un écart croissant », qu'elle « ne garantit pas la livraison des événements dans l'ordre », que votre serveur doit « renvoyer rapidement un code 2xx avant toute logique complexe », et que les doublons se détectent par l'identifiant de l'événement, jamais par l'horodatage. La signature est un HMAC-SHA256 du corps brut précédé de l'horodatage, avec une tolérance par défaut de cinq minutes contre le rejeu, et le secret peut être changé avec jusqu'à 24 heures de recouvrement pendant lesquelles deux signatures sont émises. Ce que cela impose : un webhook est une tentative, le partenaire acquitte puis traite, ignore ce qu'il a déjà vu, et peut toujours relire l'état par l'API.

Sur les quotas, le protocole HTTP lui-même a la réponse : le code 429 « Too Many Requests », défini par la RFC 6585, accompagné d'un en-tête Retry-After qui dit combien de temps attendre ; et sur les clés, le flux « client credentials » d'OAuth 2.0 décrit l'échange d'un identifiant et d'un secret contre un jeton court, pour une machine qui parle à une machine. Ce que cela impose : un partenaire qui dépasse son quota ne perd rien, il attend le délai indiqué ; et une clé volée se révoque sans toucher aux autres. Ce que nous n'avons pas trouvé : une norme algérienne ou sectorielle sur les API entre entreprises ; ce que nous voyons, ce sont des accès à la base partagés par e-mail, et nous le disons comme une observation.

Brancher un partenaire, en six étapes

Avant l'architecture, le parcours d'un partenaire, de la demande à la clé de production.

Figure 1 · Six étapes, et la troisième est celle qu’on saute toujours : écrire ce que ce partenaire a le droit de faire, en lecture et en écriture, et combien de fois par minute, avant qu’il ait écrit une ligne. Tout le reste, clé, bac à sable, revue, est la mise en œuvre de cette feuille.

Demande et contrat : le partenaire dit ce qu'il veut lire et écrire, à quelle fréquence, et les deux parties signent une feuille de droits ; c'est elle qui tranchera les discussions. Compte et clé de test : un compte partenaire, une clé de bac à sable, des données fictives qui ressemblent aux vraies, pour qu'il développe sans toucher à rien. Droits et quotas écrits : lecture ou écriture par ressource, appels par minute et par jour ; c'est l'étape qu'on saute toujours, et celle qui évite le PATCH sur un prix à trois heures du matin.

Intégration en bac à sable : le partenaire développe seul avec la documentation, et ses erreurs sont dans son journal, qu'il lit sans vous appeler. Revue : le journal relu ensemble, les erreurs expliquées, l'idempotence vérifiée en renvoyant deux fois la même écriture, les webhooks acquittés. Clé de production : activée à une date, avec un quota de départ qu'on relève sur demande, une surveillance la première semaine, et une rotation prévue dans le contrat. Six étapes, dont quatre où le partenaire travaille seul : c'est la mesure d'une API bien faite.

Trois appels, une seule chaîne de portes

La sécurité d'une API ouverte ne se voit pas sur un schéma mais sur trois appels réels, et sur la porte où chacun s'arrête.

Figure 2 · Trois partenaires, une seule chaîne de portes, et la même ligne de journal pour chaque passage et chaque refus. Le transporteur passe ; le gros client qui tente de modifier un prix est arrêté à la porte des droits ; l’application de caisse qui dépasse ses six cents appels par minute reçoit un 429 avec le délai avant de réessayer, et ne perd rien. Les chiffres sont un exemple construit.

Le transporteur lit les commandes à expédier avec sa clé de production : connexion chiffrée, clé reconnue, droit de lecture sur les commandes, quota respecté, schéma de la version 1, pas d'écriture donc pas de clé d'idempotence requise ; il reçoit quarante-huit commandes et l'appel est journalisé avec son nom, la route et le temps de réponse. Le gros client tente de modifier un prix : sa clé est valide, mais son rôle ne lui donne que la création de commandes et la lecture de ses factures ; il est arrêté à la porte des droits, reçoit un 403, la tentative est écrite et son interlocuteur est prévenu. Aucune route n'a été « oubliée » : la règle est appliquée par le serveur sur chaque ressource, comme le guide sur les droits le décrit pour les utilisateurs internes.

L'application de caisse envoie son six cent unième appel de la minute : arrêtée à la porte du quota, elle reçoit un 429 et un Retry-After de douze secondes ; rien n'est perdu, elle réessaie, et si cela se reproduit chaque jour, le quota se relève par écrit. La chaîne est identique pour tous, elle est la seule chose que le partenaire voit de vous, et c'est la même porte que celle qu'on met devant un agent IA : un partenaire et un agent sont deux acteurs qui proposent des actions, et le serveur dispose.

«Le partenaire ne voit jamais votre service ni votre base ; il voit six portes, les mêmes pour tous, et chaque passage ou refus laisse une ligne.»

Une API ouverte aux partenaires, en cinq couches

Derrière ces trois appels, cinq couches, et une règle dans la troisième qui tient toutes les autres.

Figure 3 · La passerelle est la couche accentuée, mais la règle qui tient tout est dans la troisième : il n’y a pas de route spéciale pour les partenaires. Un partenaire est un utilisateur avec un rôle, qui passe par les mêmes services et les mêmes règles ; la passerelle ajoute la clé, le quota, la version et le journal.

Le partenaire : son ERP, son application, son script ; vous ne contrôlez pas son code, vous contrôlez ce qu'il peut demander et ce qu'il reçoit. La passerelle : connexion chiffrée, clés et jetons, droits par ressource, quotas, schéma par version, idempotence, journal ; la couche qui protège, identique pour tous, et la seule qu'ils voient. Vos services : les mêmes que ceux de votre application, commandes, livraisons, factures, catalogue ; il n'y a pas de route « spéciale partenaire », et ce qu'un partenaire peut faire, un utilisateur avec le même rôle le peut aussi, rien de plus ; c'est ce qui évite que l'API devienne une seconde application à maintenir.

Les données : jamais exposées en direct, filtrées par le rôle ; le gros client ne voit que ses commandes et ses factures, le transporteur ne voit pas les prix, et si votre plateforme sert plusieurs clients, c'est l'isolation décrite dans le guide sur le SaaS multi-tenant qui s'applique. Le portail et la supervision : documentation générée depuis le schéma, bac à sable, clés et secrets gérés par le partenaire lui-même, journal de ses appels et de ses webhooks, rejeu ; ce que le partenaire lit seul au lieu de vous appeler, et ce que vous lisez chaque semaine sur un écran bâti comme le tableau de bord du gérant.

Six partenaires, et ce que chacun a le droit de faire

La feuille de droits est le document le plus utile du projet, et elle tient en six lignes.

Figure 4 · Chaque ligne est une feuille de droits signée des deux côtés, et c’est le serveur qui l’applique, pas la documentation. Le transporteur ne voit pas les prix, le comptable n’écrit rien, le gros client ne voit que lui ; les quotas sont des points de départ qu’on relève sur demande, avec une date. Les valeurs sont un exemple.

Le transporteur lit les commandes à expédier, les adresses et les créneaux, jamais les prix ni les marges ; il écrit le statut de livraison, la preuve et les incidents ; il reçoit les événements d'expédition et d'annulation ; c'est la liaison décrite dans le guide sur la plateforme de livraison. Le gros client B2B lit son catalogue aux prix négociés, ses commandes et ses factures, rien des autres ; il crée une commande et l'annule avant préparation ; c'est le portail B2B vu depuis son ERP. Le cabinet comptable lit factures, avoirs et règlements par période, et n'écrit rien.

Le revendeur ou la marketplace lit le stock disponible et les prix revendeur, crée des commandes et réserve du stock trente minutes, et reçoit les changements de stock et de prix ; c'est le branchement décrit dans le guide sur la marketplace. L'application de caisse tierce lit le catalogue et écrit les ventes et les clôtures, comme le guide sur la caisse le prévoit. La banque ou l'agrégateur ne lit rien et n'écrit rien : il envoie ses webhooks signés et vous les vérifiez, selon le guide sur le paiement. Les quotas du tableau sont des points de départ ; ils se relèvent sur demande, avec une date, et jamais en silence.

Un événement livré au partenaire : signé, réessayé, acquitté, rejouable

Les webhooks sont la moitié de l'API que les devis oublient, et la moitié qui réveille la nuit.

Figure 5 · Un webhook est une tentative. Celui-ci a réussi à la troisième, dix minutes après l’événement, parce que le serveur du partenaire redémarrait ; l’en-tête signé était le même à chaque fois, le partenaire a vérifié la signature et aurait ignoré une livraison en double. Les grandes plateformes de paiement réessaient jusqu’à trois jours avec un écart croissant, ne garantissent pas l’ordre, et demandent une réponse 2xx rapide ; nous faisons de même.

L'événement commande.expediee est créé à 10 h 02 pour le transporteur. Première tentative : son serveur ne répond pas en dix secondes. Deuxième, une minute plus tard : il répond 500, il redémarrait. Troisième, à 10 h 12 : 200, acquitté. L'écart entre les tentatives croît, et il reste des tentatives jusqu'à trois jours ; au-delà, l'événement est marqué non livré et le partenaire le voit dans son portail, d'où il peut le rejouer. À chaque tentative, l'en-tête est le même : identifiant de l'événement, horodatage, signature HMAC-SHA256 calculée avec le secret du partenaire sur l'horodatage et le corps brut.

Côté partenaire, quatre gestes que la documentation lui explique et que la revue vérifie : vérifier la signature sur le corps brut et rejeter un horodatage de plus de cinq minutes ; répondre 200 tout de suite et traiter ensuite, dans une file ; ignorer un identifiant déjà vu, parce qu'une livraison en double ne doit rien changer ; et relire l'état par l'API quand il doute, parce qu'un webhook est une tentative, pas une vérité. Le secret tourne avec vingt-quatre heures de recouvrement, pendant lesquelles deux signatures sont émises, pour qu'aucun partenaire ne soit coupé un vendredi soir.

«Un webhook est une tentative, pas une vérité ; le partenaire acquitte, traite, ignore ce qu'il a déjà vu, et relit l'état quand il doute.»

Vu ailleurs : les plateformes qui ouvrent des API, et ce qui se transpose

Trois sources disent l'essentiel. La plateforme de commerce qui publie une version par trimestre et la supporte douze mois dit comment on change une API sans casser ses partenaires : par ajout, avec des dates, et en répondant à ceux qui sont en retard ; ce qui se transpose, c'est la version 1 gelée et la politique de dépréciation écrite dans le contrat. La plateforme de paiement qui réessaie trois jours, ne garantit pas l'ordre et demande un 2xx rapide dit comment on livre des événements à des serveurs qu'on ne contrôle pas ; ce qui se transpose, c'est la signature, les tentatives, l'identifiant d'événement et le rejeu. Le protocole HTTP et OAuth disent comment on refuse proprement et comment on authentifie une machine ; ce qui se transpose, c'est le 429 avec délai et la clé révocable.

Ce que ces sources ne disent pas : ce que vos partenaires ont le droit de voir chez vous, et combien d'appels par minute votre serveur supporte ; la feuille de droits répond à la première question, le test de charge du bac à sable à la seconde.

Les règles d'une API qu'on peut ouvrir sans crainte

Six règles, écrites la première semaine. Un partenaire est un utilisateur avec un rôle, qui passe par les mêmes services ; aucune route spéciale. Une clé par partenaire, révocable seule, avec rotation prévue. Les droits sont appliqués par le serveur sur chaque ressource, pas par la documentation. Un quota par partenaire, avec un 429 et un délai, relevé par écrit. Les webhooks sont signés, réessayés et rejouables, et le partenaire peut toujours relire l'état. La version est gelée : elle ne change que par ajout, et la suivante a des dates.

Une septième règle porte sur le devis : « API pour les partenaires » n'est pas une exigence, c'est une phrase ; l'exigence s'écrit « feuille de droits par type de partenaire, lecture et écriture par ressource ; clé ou jeton par partenaire, révocation, rotation ; quotas par minute et par jour avec 429 et Retry-After ; schéma versionné et documentation générée depuis le schéma ; clé d'idempotence sur chaque écriture ; journal de chaque appel avec partenaire, route, résultat ; webhooks signés HMAC avec horodatage, tentatives à écart croissant jusqu'à trois jours, identifiant d'événement, rejeu depuis le portail ; bac à sable avec données fictives ; politique de versions avec douze mois de support ; aucun accès direct à la base », et elle se vérifie comme le guide sur le cahier des charges le recommande. Un devis qui propose « un accès en lecture à la base pour le partenaire » a proposé la panne numéro un.

Six entreprises, et le premier partenaire qu'elles branchent

Six entreprises que nous équipons souvent, et pour chacune le premier partenaire qui a demandé « un accès ».

Le grossiste et son portail, décrit dans le guide dédié. Son plus gros détaillant commande depuis son propre logiciel ; il ne voit que ses prix, et le stock qu'il réserve est libéré au bout de trente minutes.
La plateforme de livraison, décrite dans le guide dédié. Trois boutiques en ligne lui envoient leurs commandes et reçoivent les statuts ; chacune a sa clé, et aucune ne voit les autres.
Le grossiste pharmaceutique, décrit dans le guide sur la chaîne du froid. Le laboratoire lit la traçabilité des lots qu'il a livrés, par lot, jamais par client.
La marketplace, décrite dans le guide dédié. Les vendeurs synchronisent stock et prix depuis leur caisse ; six cents appels par minute pour les plus gros, réservation de stock sur commande.
L'application mobile avec ses partenaires, décrite dans le guide sur les mises à jour. La même règle d'ajout sans retrait sert les anciennes versions de l'application et les partenaires : c'est une seule politique de versions.
L'entreprise pilotée depuis la France. Le cabinet comptable à Alger lit factures et règlements chaque soir par l'API ; le fondateur voit dans son tableau qui a appelé quoi, et le fichier mensuel par e-mail a disparu.

Le calendrier 2027

Le calendrier est celui d'une API ouverte en dix semaines, dont deux avant qu'un partenaire voie quoi que ce soit.

Figure 6 · Dix semaines, dont deux pour le contrat d’API et la passerelle avant qu’un partenaire voie quoi que ce soit, et deux pour le premier partenaire réel. La version 1 est gelée à la fin : elle ne change plus que par ajout, et elle est supportée douze mois après l’annonce de la suivante, comme le font les plateformes de commerce qui publient une version par trimestre.

La semaine 0 à 1 écrit le contrat d'API : ressources, droits par type de partenaire, quotas de départ, politique de versions et de dépréciation ; signé. Les semaines 1 à 3 construisent la passerelle devant les services existants : clés et jetons, droits par ressource, quotas, journal ; aucune route nouvelle. La semaine 3 à 4 ouvre le bac à sable et la documentation générée depuis le schéma, et le portail où le partenaire gère ses clés et lit son journal. Les semaines 4 à 6 construisent les webhooks : événements, signature, tentatives à écart croissant, rejeu.

Les semaines 6 à 8 branchent le premier partenaire réel, un transporteur ou un gros client, en bac à sable puis en production, avec le journal relu ensemble chaque semaine. Les semaines 8 à 10 gèlent la version 1 : elle ne change plus que par ajout, douze mois de support sont écrits, et la version 2 n'existera que si un changement l'exige. Chaque lot est démontré comme le guide sur la livraison le décrit, et la clé d'idempotence sur chaque écriture suit le principe de la synchronisation hors ligne : une écriture renvoyée deux fois ne compte qu'une fois.

Ce qui fait échouer une API ouverte aux partenaires

Les API que nous reprenons ont presque toujours échoué pour l'une de ces raisons.

L'accès direct à la base. Le partenaire lit tout, écrit parfois, et personne ne sait quoi.
Une clé pour tous. Elle fuit chez un partenaire, et on coupe tout le monde pour la changer.
Des droits dans la documentation, pas dans le serveur. « Merci de ne pas appeler cette route » n'est pas un contrôle.
Pas de quota. Un script mal écrit chez le partenaire appelle mille fois par seconde, et vos propres clients attendent.
Des webhooks sans signature ni réessai. N'importe qui peut en envoyer un, et le vrai se perd à la première coupure.
Un champ retiré sans date. Trois partenaires plantent le même matin, et aucun n'avait été prévenu.
Pas de bac à sable. Le partenaire teste en production, avec de vraies commandes, et on découvre ses erreurs chez les clients.

Questions fréquentes

Les questions que nous recevons de gérants, de fondateurs et de responsables informatiques.

Un partenaire peut-il accéder directement à notre base de données ?: Non, et c'est la première règle : un partenaire est un utilisateur avec un rôle, qui passe par les mêmes services que votre application, derrière une passerelle qui vérifie sa clé, ses droits par ressource, son quota, le schéma et l'idempotence, et qui journalise chaque appel. Un accès à la base donne tout, à tous, sans trace, et ne se révoque pas sans tout casser.
Comment limiter ce que chaque partenaire voit ?: Par une feuille de droits signée des deux côtés et appliquée par le serveur sur chaque ressource : le transporteur lit les commandes à expédier mais pas les prix, le gros client ne voit que ses commandes et ses factures, le comptable lit et n'écrit rien. La documentation décrit ces droits ; le serveur les applique, et une tentative hors droits reçoit un 403 et une ligne de journal.
Que se passe-t-il si un partenaire appelle trop souvent ?: Il a un quota par minute et par jour ; au-delà, il reçoit un 429 avec un en-tête Retry-After qui dit combien de temps attendre, et il ne perd rien en réessayant. Si le dépassement se répète, le quota se relève par écrit, avec une date. Vos propres clients ne sont jamais ralentis par le script d'un partenaire.
Comment un partenaire est-il prévenu quand quelque chose change chez nous ?: Par des webhooks : un événement signé en HMAC-SHA256 avec un horodatage, envoyé à son adresse, réessayé avec un écart croissant jusqu'à trois jours s'il ne répond pas 2xx, identifié de façon unique pour qu'un doublon ne change rien, et rejouable depuis son portail. Il peut toujours relire l'état par l'API : un webhook est une tentative, pas une vérité.
Que se passe-t-il quand nous changeons notre API ?: La version 1 ne change que par ajout : de nouveaux champs ou de nouvelles routes, jamais un retrait. Si un changement incompatible est nécessaire, une version 2 est annoncée avec une date, la version 1 reste supportée douze mois, et un partenaire en retard reçoit une réponse plutôt qu'une erreur. C'est la politique que suivent les grandes plateformes de commerce, écrite dans votre contrat d'API.
Combien de temps pour ouvrir une API à un premier partenaire ?: Dix semaines : une pour le contrat d'API, deux pour la passerelle devant les services existants, une pour le bac à sable et la documentation, deux pour les webhooks, deux pour le premier partenaire en bac à sable puis en production, deux pour geler la version 1. Le partenaire travaille seul pendant la plus grande partie de ce temps, avec la documentation et son journal.