Bâtissez sur vos données d'étalonnage.

L'API publique d'Axiospec est une interface REST vers votre programme d'étalonnage. Lisez et créez des instruments, inscrivez des étalonnages au registre à détection d'altération, et lisez les sites de votre espace de travail ainsi que les normes de conformité que vous avez sélectionnées.

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

Tous les points de terminaison se trouvent sous une seule URL de base. Chaque chemin de la référence ci-dessous est relatif à celle-ci.

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 portent le préfixe ctk_. Conservez la clé comme un secret et ne la publiez jamais dans du code côté client.

Envoyez la clé à chaque requête comme jeton porteur :

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

L'API est offerte à partir du forfait Professional. Une clé qui appartient à un espace de travail sur le forfait gratuit ou Starter reçoit un 403 avec le code API_ACCESS_TIER_REQUIRED. Montez l'espace de travail de forfait 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 modifier et inscrire 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 les intégrations de rapports, pour qu'elles ne puissent 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 les autres, et plusieurs clés derrière un même réseau de bureau ne sont pas bridées ensemble.

Chaque réponse de l'API porte la fenêtre courante dans ses en-têtes, pour que vous puissiez régler votre rythme sans deviner. X-RateLimit-Limit est le plafond (120), X-RateLimit-Remaining est le nombre de requêtes qu'il reste dans la fenêtre courante, et X-RateLimit-Reset est le nombre de secondes avant la réinitialisation de la fenêtre, quand Remaining revient au plafond.

Dépasser la limite retourne un 429 avec le code RATE_LIMITED. Sur le 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 de coder un délai en dur vous garde rapide quand il y a de la marge et poli quand il n'y en a pas.

Pour garder un système externe à jour sans tout relire, ne tirez que ce qui a changé depuis votre dernière exécution. Chaque collection accepte un paramètre updated_since (un horodatage ISO-8601 en UTC) qui ne retourne que les enregistrements modifiés à cet instant ou après, plus un paramètre sort pour les parcourir du plus ancien au plus récent et avancer un repère au fur et à mesure.

Le flux d'étalonnages de tout le compte, GET /calibrations, est fait exactement pour ça : il retourne tous les étalonnages de tous vos instruments dans un seul flux paginé, alors vous n'avez pas à boucler instrument par instrument. Triez en ordre croissant par updated_at, parcourez les pages et retenez le created_at du dernier enregistrement vu. Le registre est en ajout seulement, alors un enregistrement d'étalonnage ne change jamais après son écriture et son created_at est son heure de dernière modification. sort=updated_at pointe vers cet instant.

À l'exécution suivante, passez cette valeur enregistrée comme updated_since. Chevauchez la frontière d'une seconde ou deux et dédoublonnez sur l'identifiant de l'enregistrement, par prudence contre les écarts 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), filtrés sur l'heure de dernière modification de l'instrument. Les lignes de la liste ne contiennent pas de champ d'horodatage. Pour les instruments, utilisez donc l'heure murale que vous avez notée juste avant la requête comme prochain updated_since. Le GET /instruments/{id} d'un seul instrument retourne created_at et updated_at si vous en avez besoin.

GET /instruments accepte des filtres pour aller chercher une tranche précise plutôt que de parcourir tout le parc. asset_tag et serial_number cherchent une valeur exacte, ce qui est pratique pour rapprocher un seul instrument d'un enregistrement ERP. status filtre selon l'état du cycle de vie, par exemple active ou retired. site_id limite à un seul site.

Deux filtres découlent de l'état d'étalonnage. compliance_status filtre selon le jeton calculé, parmi COMPLIANT, WARNING, NON_COMPLIANT ou NOT_CALIBRATED. next_due_before prend une date (YYYY-MM-DD) et retourne les instruments dont le prochain étalonnage est dû avant cette date, soit la requête derrière une liste de travail des échéances proches ou en retard. Les filtres se combinent, alors vous pouvez demander les instruments actifs et non conformes d'un seul site en un seul appel.

Inscrire un étalonnage est la seule écriture qui ne doit jamais être dupliquée : le registre est en ajout seulement, alors il n'y a 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 requis, pas facultatif.

Si une requête est interrompue et que vous la réessayez avec la même clé, l'API retourne l'enregistrement déjà écrit au lieu d'en écrire un deuxième. Une clé absente retourne un 400 avec le code IDEMPOTENCY_KEY_REQUIRED. Générez une nouvelle clé pour chaque étalonnage que vous comptez enregistrer.

La création d'un instrument (POST /instruments) accepte aussi une Idempotency-Key, mais elle est facultative ici. Envoyez-en une et une reprise avec la même clé retourne l'instrument créé au premier appel plutôt qu'un doublon, exactement comme pour l'inscription d'un étalonnage. La seule différence, c'est que la clé n'est pas exigée. Si vous préférez ne pas gérer de clés pour les créations, dédoublonnez de votre côté avec 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 à votre image. Allez le chercher 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 au certificat que produit l'application, pour que vous puissiez l'archiver ou le joindre à un bon 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 autrement non certifiable, la requête retourne un 404 avec le code CERTIFICATE_UNAVAILABLE. Un identifiant d'étalonnage qui n'est pas le vôtre, ou qui n'existe pas, retourne un simple 404 qui ne révèle rien.

Quand un instrument quitte le service, mettez-le hors service avec POST /instruments/{id}/retire (un appel en portée d'écriture). C'est une mise hors service sans suppression : le statut de l'instrument devient retired et il sort de la liste active par défaut, mais rien n'est supprimé et son historique d'étalonnage reste intact au registre pour l'audit. Il n'y a pas de suppression définitive dans l'API.

L'appel retourne l'instrument mis à jour. Il est idempotent : mettre hors service un instrument déjà hors service ne fait rien et retourne le même enregistrement, alors une reprise est toujours sûre. La mise hors service 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 retournent une enveloppe uniforme. Parcourez les résultats avec les paramètres de requête limit et offset. total est le compte complet et has_more vous dit s'il existe une autre page.

Chaque horodatage que retourne 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 aucune réponse en décalage ou en heure locale à normaliser.

Un champ est une date simple et non un horodatage : la date d'échéance d'étalonnage d'un instrument. Les dates d'échéance sont calculées dans le fuseau horaire configuré de votre espace de travail, alors une date d'échéance est le jour civil 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 à minuit UTC.

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

L'inscription d'un étalonnage applique aussi les champs exigés par les normes que votre espace de travail a sélectionnées. Si un champ requis est vide, la requête retourne 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 à intervalle régulier pour découvrir ce qui a changé, abonnez une adresse de webhook une seule fois et Axiospec livre chaque événement à votre URL au moment où il se produit. Vous obtenez une latence plus faible et beaucoup moins de trafic gaspillé qu'en relisant des collections déjà vues, et vous ne manquez jamais un changement entre deux interrogations.

Abonnez-vous avec POST /webhooks, en passant une url et une liste facultative de types d'événements à recevoir. Omettez le champ events pour recevoir tous les événements (le catalogue complet est plus bas). La réponse retourne le secret de signature de l'adresse une seule fois et jamais plus, alors copiez-le directement dans votre coffre à secrets. La gestion des webhooks exige une clé d'écriture d'administrateur ou de responsable, parce que l'adresse reçoit les données d'étalonnage et d'instruments de votre espace de travail.

Chaque événement est livré par un POST HTTP dont le corps JSON est une enveloppe fixe : { "id", "type", "created_at", "data" }. Le id est l'identifiant stable de l'événement, envoyé aussi dans l'en-tête Axiospec-Event-Id, à côté de Axiospec-Event-Type, Axiospec-Webhook-Id et Axiospec-Delivery-Attempt. La livraison est au moins une fois, alors le même événement peut arriver plus d'une fois (après une reprise, par exemple). Dédoublonnez sur l'identifiant de l'enveloppe.

Une livraison est en échec pour toute réponse qui n'est pas un 2xx, et cela comprend une redirection 3xx : une redirection pourrait pointer vers une adresse interne, alors elle n'est jamais suivie. Les erreurs de transport et les dépassements de délai comptent aussi comme des échecs. Les livraisons en échec sont reprises selon un délai exponentiel qui s'étale sur environ trois jours, après quoi la livraison est marquée épuisée. Une adresse dont toutes les livraisons récentes s'épuisent est désactivée automatiquement, pour qu'une URL morte ou hostile cesse de consommer de la capacité. Les adresses doivent être en HTTPS, et une URL qui se résout vers une adresse privée ou interne est refusée à l'abonnement.

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

Voici les types d'événements auxquels un webhook peut s'abonner. Nommez ceux que vous voulez au moment de l'abonnement, ou omettez le champ events pour tous les recevoir. Le même catalogue est offert à 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é modifié en chemin.

Lisez l'en-tête Axiospec-Signature et séparez-le à la virgule en sa partie t= (un horodatage Unix en secondes) et sa partie v1= (un HMAC en hexadécimal minuscule). Recalculez un HMAC-SHA256, avec le secret de signature de votre adresse comme clé, 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 une égalité ordinaire.

Signez les octets bruts exactement tels que reçus, 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 de cinq minutes environ, ce qui borne la durée pendant laquelle une requête capturée pourrait être rejouée contre vous.