Comment fonctionne l'API Optifora
Cette page décrit la forme de l'API: comment l'identité est prouvée, comment les versions évoluent, dans quelles limites une requête doit rester, à quoi ressemble une erreur et comment les données sont échangées avec l'extérieur.
Le produit est en cours de développement et la surface de l'API est encore en cours d'achèvement. Un document de référence des points d'accès sera publié séparément; cette page ne contient ni adresse ni exemple d'appel, seulement les mécanismes.
Authentification
Chaque requête appartient soit à une personne, soit à une application enregistrée. Une requête sans identité qui atteint un point d'accès protégé revient non authentifiée.
- Jeton BearerLe jeton d'accès voyage dans l'en-tête d'autorisation de la requête. Il est signé et indique uniquement à qui la requête appartient.
- Durée de vie courteUn jeton d'accès expire après une durée exprimée en minutes; cette durée est un paramètre de déploiement et vaut trente minutes par défaut.
- Renouvellement et rotationUne session est prolongée à l'aide d'un jeton de renouvellement, et chaque prolongation délivre un nouveau couple. Si un jeton de renouvellement déjà consommé est présenté une seconde fois, toutes les sessions de la personne concernée sont révoquées.
- Les droits ne sont pas figés dans le jetonLe jeton ne porte que l'identité; ce qu'une personne a le droit de voir est demandé à la base de données à chaque requête. Une autorisation retirée cesse donc d'agir avant même que le jeton en main n'expire.
- Clé d'intégrateurUne application enregistrée se connecte avec sa propre clé. La valeur en clair n'est affichée qu'une seule fois, à la création; ce qui est conservé, c'est son empreinte et le préfixe non secret qui permet de reconnaître une clé.
- L'organisation accorde l'accèsAussi répandue qu'elle soit, une application ne voit pas une seule ligne sans une autorisation enregistrée par l'organisation. Cette autorisation est datée, délimitée et révocable.
Versionnement
- La version figure dans le cheminLes points d'accès sont publiés derrière un préfixe de version; la surface d'aujourd'hui est la version un.
- Une rupture ouvre un nouveau cheminLe contrat d'un point d'accès existant n'est pas rompu sur place. Une évolution incompatible est publiée sur un nouveau chemin de version tandis que l'ancien continue de fonctionner.
- Le document indique sa propre versionLa référence porte le numéro de version à partir duquel elle a été générée; la version que vous lisez est indiquée par le document lui-même.
Environnements et limites
La référence déclare deux environnements: production et développement local. L'adresse racine est remise à l'intégrateur en même temps que sa clé; elle n'est pas publiée sur cette page.
- Vivacité et disponibilité sont mesurées séparémentUn point d'accès indique que le processus est en vie; le second envoie une vraie requête à la base de données et confirme qu'elle est joignable. Seul le second décide si le trafic doit être envoyé.
- Les origines navigateur sont limitées à une listeLes requêtes d'origine croisée ne sont acceptées que depuis des origines déclarées à l'avance; tant que la liste est vide, une requête de navigateur d'origine croisée est refusée.
- Limite de taille du corpsLe corps d'une requête ne peut pas dépasser cinq mégaoctets. Les gros volumes circulent sous forme de tâche de transfert en masse, avec son propre enregistrement d'état, et non en une seule requête.
- Les secrets ne sont pas écrits dans le journalLe journal du serveur ne conserve ni en-tête d'autorisation, ni cookie, ni mot de passe, ni numéro d'identité nationale.
Limite de débit
La limite s'applique par adresse et par minute. La valeur par défaut est de 120 requêtes par minute et se règle au déploiement. Ce qu'il reste est indiqué dans les en-têtes de chaque réponse.
| En-tête de réponse | Ce qu'il indique |
|---|---|
| x-ratelimit-limit | Le quota total à l'intérieur de la fenêtre. |
| x-ratelimit-remaining | Ce qu'il reste dans cette fenêtre. |
| x-ratelimit-reset | Secondes restantes avant le renouvellement du quota. |
| retry-after | Nombre de secondes avant une nouvelle tentative. Présent uniquement sur la réponse qui a refusé la requête. |
Une fois la limite dépassée, la requête est refusée et la réponse indique, en secondes, le temps d'attente. La nouvelle tentative se fait après ce délai, pas immédiatement.
Format des erreurs
Toute erreur revient dans la même enveloppe: un champ code court sur lequel la machine s'aiguille, et un champ explication qu'une personne peut lire.
- errorLe code court sur lequel le client décide.
- messageL'explication de ce qui s'est passé.
| Statut | Champ code | Signification |
|---|---|---|
| 400 | Bad Request | La requête ne correspond pas au schéma. L'explication nomme le champ manquant ou invalide. |
| 401 | unauthenticated | Aucune identité valide: aucun jeton n'a été envoyé, il a expiré, ou il n'a pas pu être vérifié. |
| 404 | Not Found | Ce point d'accès n'existe pas, ou cet enregistrement n'existe pas. |
| 429 | Too Many Requests | La limite de débit a été dépassée; la réponse indique combien de temps attendre. |
| 5xx | internal_error | Une défaillance inattendue. Le détail n'est pas transmis au client; il est écrit dans le journal du serveur. |
Pagination
Les points d'accès qui renvoient des listes acceptent les deux mêmes paramètres et renvoient les mêmes compteurs: un client de pagination n'est donc pas réécrit pour chaque point d'accès.
- limitCombien d'enregistrements une page doit contenir. Au moins un, au plus deux cents; cinquante si rien n'est précisé.
- offsetCombien d'enregistrements sauter. Commence à zéro.
- totalCombien d'enregistrements correspondent au total aux filtres.
- countCombien d'enregistrements cette réponse contient réellement.
La réponse renvoie également le limit et l'offset utilisés; le client lit sa position dans la réponse au lieu de la deviner.
Échange de données et webhooks
Le mode d'échange est un réglage, pas un produit à part: chaque application enregistrée porte sur sa propre fiche le mode dans lequel elle travaille.
| Mode | Signification |
|---|---|
| Unidirectionnel — sortant | Optifora publie les données; l'autre côté les lit ou s'abonne aux événements. |
| Unidirectionnel — entrant | L'autre côté pousse les données; Optifora les valide et les enregistre. |
| Bidirectionnel | Les deux côtés écrivent; la règle de conflit est définie à l'avance. |
| Poignée de main | Chaque transfert ouvre une session: offre, vérification, approbation, transfert et accusé de réception. L'accusé reste chez les deux parties. |
- Les événements sont poussés vers l'extérieurUn webhook envoie l'événement à l'adresse de rappel déclarée par l'application enregistrée. Un événement qui ne peut pas être livré reste en file d'attente et est réessayé; il n'est jamais abandonné en silence.
- La même requête n'écrit pas deux foisUne requête d'écriture porte une clé d'idempotence. Une seconde requête portant la même clé ne crée pas de second enregistrement.
- Chaque appel est mesuréQui a appelé, quand, avec quelle portée et avec quel résultat: tout est enregistré. Le même enregistrement répond au diagnostic comme à la question de savoir qui a extrait ces données.
- Nos propres applications passent par la même porteIl n'existe aucun second chemin privilégié. Notre propre intégration est la preuve de la surface que rencontre un développeur extérieur.
Le modèle de données de la couche d'échange est en place; ses points d'accès ne sont pas encore publiés. Lorsqu'ils le seront, cette section renverra à leurs entrées dans la référence.
Documents de référence
La référence n'est pas rédigée à la main; elle est générée à partir des schémas des points d'accès. À mesure que chaque point d'accès livre son schéma, le document se remplit de lui-même: le document et le comportement ne peuvent donc pas diverger.
- Aujourd'hui: en préparationLes schémas avancent module par module. Avant la publication du document, la requête et la réponse de chaque point d'accès y seront visibles.
- Deux formats seront publiésUn document OpenAPI lisible par la machine, et une page de référence issue de ce même document, consultable dans un navigateur.
- L'accès est à plusieurs niveauxLa vue d'ensemble est ouverte à tous. La référence complète peut se trouver derrière un jeton de documentation remis à un intégrateur enregistré; les clés de production et les adresses de rappel ne relèvent pas du tout de la documentation — elles appartiennent à la fiche de l'application.
- Convention d'adressesDeux références sont publiées et leurs adresses sont fixes: client-api.optifora.com/docs est ouverte, admin-api.optifora.com/docs exige une autorisation et reste fermée à l'extérieur. Aucune des deux n'est en ligne aujourd'hui; les liens seront ajoutés à cette section dès qu'elles le seront.
Si votre projet d'intégration est déjà clair, écrivez-nous depuis la page de contact: vous serez parmi les premiers informés de l'ouverture de la surface.
Vous avez une demande particulière?
Ces pages expliquent le fonctionnement du processus d'assistance. Si vous avez une demande ou une question, écrivez-nous depuis la page de contact.
Aller à la page de contact