Construisez sur vos données d'étalonnage.

L'API publique Axiospec est une interface REST vers votre programme d'étalonnage. Lisez et créez des instruments, inscrivez des étalonnages dans le registre à intégrité vérifiable, et lisez les sites de votre espace de travail ainsi que les normes de conformité que vous avez retenues.

C'est un contrat choisi et stable, distinct des points de terminaison internes qu'utilisent les applications web et mobile, pour que votre intégration continue de fonctionner à mesure que le produit évolue. Chaque réponse est en JSON.

Tous les points de terminaison vivent sous une seule URL de base. Chaque chemin de la référence ci-dessous lui est relatif.

Authentifiez chaque requête avec une clé API propre à l'espace de travail. Un administrateur de l'espace de travail en crée une dans l'application, sous Paramètres puis Clés API. Les clés ne sont affichées qu'une fois, à la création, et sont préfixées ctk_. Conservez la clé comme un secret et ne la livrez jamais dans du code côté client.

Envoyez la clé à chaque requête sous forme de jeton Bearer :

Un en-tête X-API-Key standard est également accepté si vous le préférez : X-API-Key: ctk_your_api_key. Une requête sans clé renvoie 401.

L'API est disponible à partir de l'offre Professional. Une clé qui appartient à un espace de travail sur l'offre gratuite ou Starter reçoit un 403 avec le code API_ACCESS_TIER_REQUIRED. Changez l'offre de l'espace de travail pour l'activer.

Chaque clé est émise avec une portée. Une clé de lecture peut lister et consulter. Une clé d'écriture peut en plus créer des instruments, les mettre à jour et enregistrer des étalonnages (l'écriture implique toujours la lecture).

Une clé en lecture seule qui tente une écriture reçoit un 403 avec le code INSUFFICIENT_SCOPE, qui nomme la portée requise. Émettez des clés en lecture seule pour vos intégrations de reporting, elles ne pourront jamais modifier un enregistrement.

Les requêtes sont limitées à 120 par minute, comptées par clé API plutôt que par adresse IP. Une intégration ne peut donc pas affamer une autre, et plusieurs clés derrière un même réseau d'entreprise ne sont pas bridées ensemble.

Chaque réponse de l'API porte la fenêtre en cours dans ses en-têtes, pour que vous puissiez vous cadencer sans deviner. X-RateLimit-Limit est le plafond (120), X-RateLimit-Remaining le nombre de requêtes qui restent dans la fenêtre en cours, et X-RateLimit-Reset le nombre de secondes avant la remise à zéro de la fenêtre et le retour de Remaining au plafond.

Dépasser la limite renvoie un 429 avec le code RATE_LIMITED. Sur ce 429, un en-tête Retry-After (en secondes) vous dit exactement combien de temps attendre. Respectez-le, puis réessayez. Lire ces en-têtes plutôt que coder un délai en dur vous garde rapide quand il y a de la marge et courtois quand il n'y en a pas.

Pour garder un système externe à jour sans tout relire, ne récupérez que ce qui a changé depuis votre dernier passage. Chaque collection accepte un paramètre updated_since (un horodatage ISO-8601 en UTC) qui ne renvoie que les enregistrements modifiés à partir de cet instant, plus un paramètre sort pour les parcourir du plus ancien au plus récent et faire avancer un repère au fur et à mesure.

Le flux d'étalonnages à l'échelle du client, GET /calibrations, est fait exactement pour cela : il renvoie tous les étalonnages de tous vos instruments dans un seul flux paginé, sans boucler instrument par instrument. Triez par updated_at croissant, parcourez les pages et retenez le created_at du dernier enregistrement vu. Le registre est en ajout seul, donc un enregistrement d'étalonnage ne change jamais après son écriture et son created_at est sa date de dernière modification ; sort=updated_at correspond à cet instant.

Au passage suivant, transmettez cette valeur enregistrée dans updated_since. Chevauchez la limite d'une seconde ou deux et dédoublonnez sur l'identifiant de l'enregistrement, par sécurité contre les décalages d'horloge. N'enregistrez le repère qu'une fois la page traitée de façon durable.

Les instruments acceptent les mêmes paramètres updated_since et sort (GET /instruments), qui filtrent sur la date de dernière modification de l'instrument. Les lignes de la liste ne comportent pas de champ d'horodatage : pour les instruments, prenez donc comme prochain updated_since l'heure relevée juste avant la requête. L'appel unitaire GET /instruments/{id} renvoie created_at et updated_at si vous en avez besoin.

GET /instruments accepte des filtres, pour récupérer une tranche précise au lieu de parcourir tout le parc. asset_tag et serial_number correspondent à une valeur exacte (pratique pour rapprocher un instrument d'une fiche ERP). status filtre sur l'état du cycle de vie, par exemple active ou retired. site_id restreint à un seul site.

Deux filtres sont dérivés de l'état d'étalonnage. compliance_status filtre sur le jeton calculé, parmi COMPLIANT, WARNING, NON_COMPLIANT ou NOT_CALIBRATED. next_due_before prend une date (YYYY-MM-DD) et renvoie les instruments dont le prochain étalonnage est dû avant elle, c'est la requête derrière une liste de travail des échéances proches ou dépassées. Les filtres se combinent : vous pouvez demander en un seul appel les instruments actifs et non conformes d'un site donné.

Enregistrer un étalonnage est la seule écriture qui ne doit jamais être dupliquée : le registre est en ajout seul, il n'y a donc aucun moyen d'annuler un double envoi. C'est pourquoi POST /instruments/{id}/calibrations exige un en-tête Idempotency-Key (n'importe quelle chaîne unique que vous générez, par exemple un UUID). Il est obligatoire, pas optionnel.

Si une requête est interrompue et que vous la relancez avec la même clé, l'API renvoie l'enregistrement déjà écrit au lieu d'en écrire un second. Une clé absente renvoie un 400 avec le code IDEMPOTENCY_KEY_REQUIRED. Générez une clé neuve pour chaque étalonnage que vous voulez enregistrer.

La création d'un instrument (POST /instruments) honore aussi un Idempotency-Key, mais il y est optionnel. Envoyez-en un et une nouvelle tentative avec la même clé renvoie l'instrument créé par le premier appel plutôt qu'un doublon, exactement comme pour le journal d'étalonnage. La seule différence, c'est que la clé n'est pas obligatoire. Si vous préférez ne pas gérer de clés pour les créations, dédoublonnez de votre côté sur l'asset_tag ou le serial_number de l'instrument, qui sont uniques dans un espace de travail, avant le POST.

Chaque étalonnage approuvé a un certificat PDF à vos couleurs. Récupérez-le avec GET /calibrations/{calibration_id}/certificate. La réponse est le PDF lui-même (Content-Type application/pdf) en pièce jointe, identique octet pour octet à celui que produit l'application, pour que vous puissiez l'archiver ou le joindre à un ordre de travail.

Un certificat n'existe que pour un étalonnage approuvé et courant. Si l'enregistrement est annulé, remplacé par une entrée plus récente, ou non certifiable pour une autre raison, la requête renvoie un 404 avec le code CERTIFICATE_UNAVAILABLE. Un identifiant d'étalonnage qui n'est pas le vôtre, ou qui n'existe pas, renvoie un 404 ordinaire qui ne révèle rien.

Quand un instrument quitte le service, sortez-le avec POST /instruments/{id}/retire (un appel en portée d'écriture). C'est une sortie logique : le status de l'instrument passe à retired et il disparaît de la liste active par défaut, mais rien n'est supprimé et son historique d'étalonnage reste intact dans le registre, pour l'audit. Il n'y a pas de suppression définitive dans l'API.

L'appel renvoie l'instrument mis à jour. Il est idempotent : sortir un instrument déjà hors service ne fait rien et renvoie le même enregistrement, une nouvelle tentative est donc toujours sans risque. Cette opération exige une clé de responsable ou d'administrateur ; une clé en lecture seule ou de technicien reçoit un 403.

Les points de terminaison de liste renvoient une enveloppe constante. Parcourez les résultats avec les paramètres de requête limit et offset ; total est le nombre total et has_more vous dit s'il existe une page suivante.

Chaque horodatage renvoyé par l'API est en ISO-8601 UTC, terminé par Z, par exemple 2026-07-09T15:30:00Z. Envoyez les horodatages de la même façon. Il n'y a ni décalage ni heure locale à normaliser.

Un champ est une date simple et non un horodatage : l'échéance d'étalonnage d'un instrument. Les échéances sont calculées dans le fuseau horaire configuré pour votre espace de travail, une échéance est donc le jour calendaire où elle tombe là-bas, et le filtre next_due_before prend une date (YYYY-MM-DD) plutôt qu'un horodatage. Si vos systèmes tournent dans un autre fuseau, comparez sur la date, pas sur un instant de minuit UTC.

Chaque erreur, sur chaque point de terminaison, a la même forme JSON : un code lisible par une machine, un message lisible par un humain et, pour certaines erreurs, un objet details avec les précisions. Branchez sur le code, jamais sur le texte du message, qui peut être reformulé. Le statut HTTP garde son sens (401 contre 403 contre 404), servez-vous-en aussi.

Enregistrer un étalonnage applique aussi les exigences de champs des normes retenues dans votre espace de travail. Si un champ requis est vide, la requête renvoie un 422 avec le code FIELD_REQUIREMENTS_UNMET et un tableau missing_fields, où chaque entrée nomme le champ et la norme qui l'exige, pour que vous puissiez demander exactement ce qui manque.

Plutôt que d'interroger l'API à intervalles réguliers pour découvrir ce qui a changé, abonnez une URL une seule fois et Axiospec lui livre chaque événement au moment où il se produit. La latence baisse et le trafic inutile disparaît, puisque vous ne relisez plus des collections déjà vues. Vous ne ratez plus non plus un changement survenu entre deux interrogations.

Abonnez-vous avec POST /webhooks, en passant une url et, si vous voulez, la liste des types d'événements à recevoir. Omettez le champ events pour tous les recevoir (le catalogue complet est plus bas). La réponse renvoie le secret de signature du point de terminaison une seule fois et jamais plus, copiez-le donc directement dans votre coffre à secrets. Gérer les webhooks demande une clé d'administrateur ou de responsable en portée d'écriture, car l'URL reçoit les données d'étalonnage et d'instruments de votre espace de travail.

Chaque événement est livré par une requête HTTP POST dont le corps JSON est une enveloppe fixe : { "id", "type", "created_at", "data" }. L'id est l'identifiant stable de l'événement, renvoyé aussi dans l'en-tête Axiospec-Event-Id, aux côtés de Axiospec-Event-Type, Axiospec-Webhook-Id et Axiospec-Delivery-Attempt. La livraison se fait au moins une fois, le même événement peut donc arriver plusieurs fois, après une nouvelle tentative par exemple ; dédoublonnez sur l'id de l'enveloppe.

Une livraison est comptée en échec pour toute réponse qui n'est pas un 2xx, y compris une redirection 3xx : une redirection pourrait pointer vers une adresse interne, elle n'est donc jamais suivie. Les erreurs de transport et les délais dépassés comptent aussi comme des échecs. Les livraisons en échec sont réessayées selon une temporisation exponentielle qui s'étale sur environ trois jours, après quoi la livraison est marquée épuisée. Un point de terminaison dont les livraisons récentes s'épuisent toutes est désactivé automatiquement, pour qu'une URL morte ou hostile cesse de consommer de la capacité. Les URL doivent être en HTTPS, et une URL qui résout vers une adresse privée ou interne est refusée au moment de l'abonnement.

Inspectez ce qui a été envoyé avec GET /webhooks/{id}/deliveries, qui pagine le journal de livraison d'un point de terminaison et accepte un filtre status (pending, failed, succeeded, exhausted). Pour rejouer une livraison, POST /webhooks/{id}/deliveries/{delivery_id}/retry : elle repasse en pending, due immédiatement, et le prochain envoi la renvoie avec un nouvel horizon de tentatives. Changez le secret d'un point de terminaison avec POST /webhooks/{id}/rotate-secret (l'ancien secret cesse aussitôt de valider), et arrêtez les livraisons avec DELETE /webhooks/{id}.

Voici les types d'événements auxquels un webhook peut s'abonner. Listez ceux que vous voulez au moment de l'abonnement, ou omettez le champ events pour tous les recevoir. Le même catalogue est disponible via GET /webhooks/events, pour une découverte par programme.

Chaque livraison porte un en-tête Axiospec-Signature de la forme t=<unix-seconds>,v1=<hex>. Vérifiez-le avant de faire confiance à un contenu : une signature valide prouve que la requête vient d'Axiospec et que le corps n'a pas été altéré en chemin.

Lisez l'en-tête Axiospec-Signature et coupez-le sur la virgule, en sa partie t= (un horodatage Unix en secondes) et sa partie v1= (un HMAC hexadécimal en minuscules). Recalculez un HMAC-SHA256, clé par le secret de signature de votre point de terminaison, sur la chaîne formée de l'horodatage, d'un point littéral et du corps brut exact de la requête, soit f"{t}.{raw_body}". Comparez votre empreinte hexadécimale à la valeur v1 avec une comparaison à temps constant, jamais avec un test d'égalité ordinaire.

Signez les octets bruts tels qu'ils arrivent, avant toute analyse JSON ou re-sérialisation, pour que votre entrée corresponde à ce qui a été signé. Rejetez la livraison si les empreintes ne correspondent pas, ou si t a plus d'environ cinq minutes, ce qui borne la durée pendant laquelle une requête capturée pourrait être rejouée contre vous.