Bauen Sie auf Ihren Kalibrierdaten auf.

Die öffentliche API von Axiospec ist eine REST-Schnittstelle zu Ihrem Kalibrierprogramm. Lesen und erstellen Sie Messmittel, schreiben Sie Kalibrierungen in das manipulationserkennbare Journal und lesen Sie die Standorte Ihres Arbeitsbereichs sowie die von Ihnen gewählten Normen.

Sie ist ein kuratierter, stabiler Vertrag, getrennt von den internen Endpunkten der Web- und Mobil-Apps. So funktioniert Ihre Integration weiter, während sich das Produkt entwickelt. Jede Antwort ist JSON.

Alle Endpunkte liegen unter einer einzigen Basis-URL. Jeder Pfad in der Referenz unten ist relativ dazu.

Authentifizieren Sie jede Anfrage mit einem API-Schlüssel je Arbeitsbereich. Eine Administration des Arbeitsbereichs legt ihn in der App unter Einstellungen und dann API-Schlüssel an. Schlüssel werden nur einmal bei der Erstellung angezeigt und beginnen mit ctk_. Speichern Sie den Schlüssel als Geheimnis und liefern Sie ihn nie in Code aus, der im Browser läuft.

Senden Sie den Schlüssel bei jeder Anfrage als Bearer-Token:

Ein übliches Kopffeld X-API-Key wird ebenfalls akzeptiert, wenn Sie das bevorzugen: X-API-Key: ctk_your_api_key. Eine Anfrage ohne Schlüssel liefert 401.

Die API steht ab dem Tarif Professional zur Verfügung. Ein Schlüssel aus einem Arbeitsbereich im Free- oder Starter-Tarif erhält 403 mit dem Code API_ACCESS_TIER_REQUIRED. Wechseln Sie den Tarif des Arbeitsbereichs, um sie freizuschalten.

Jeder Schlüssel wird mit einem Berechtigungsbereich ausgegeben. Ein Lese-Schlüssel kann auflisten und abrufen. Ein Schreib-Schlüssel kann zusätzlich Messmittel anlegen, ändern und Kalibrierungen schreiben. Schreiben schließt Lesen immer ein.

Ein reiner Lese-Schlüssel, der zu schreiben versucht, erhält 403 mit dem Code INSUFFICIENT_SCOPE und der Angabe des nötigen Bereichs. Geben Sie für Auswertungsintegrationen reine Lese-Schlüssel aus, damit sie nie einen Datensatz ändern können.

Anfragen sind auf 120 pro Minute begrenzt, gezählt je API-Schlüssel statt je IP-Adresse. So kann eine Integration keine andere aushungern, und viele Schlüssel hinter einem Büronetz werden nicht gemeinsam gedrosselt.

Jede Antwort der API trägt das aktuelle Zeitfenster als Kopffelder, damit Sie sich ohne Raten einteilen können. X-RateLimit-Limit ist die Obergrenze (120), X-RateLimit-Remaining sagt, wie viele Anfragen im aktuellen Fenster übrig sind, und X-RateLimit-Reset nennt die Sekunden, bis das Fenster zurückgesetzt wird und Remaining wieder auf der vollen Grenze steht.

Wird die Grenze überschritten, kommt 429 mit dem Code RATE_LIMITED. Bei der 429 nennt ein Kopffeld Retry-After (in Sekunden) genau die Wartezeit. Halten Sie sich daran und wiederholen Sie dann. Diese Kopffelder zu lesen statt eine feste Wartezeit einzubauen, hält Sie schnell, wenn Luft ist, und höflich, wenn nicht.

Damit ein externes System im Takt bleibt, ohne alles neu zu lesen, holen Sie nur das, was sich seit dem letzten Lauf geändert hat. Jede Sammlung nimmt einen Parameter updated_since (ein ISO-8601-Zeitstempel in UTC) und liefert nur Datensätze, die zu diesem Zeitpunkt oder danach geändert wurden. Dazu gibt es einen Parameter sort, mit dem Sie sie von alt nach neu durchgehen und dabei eine Marke vorrücken.

Der arbeitsbereichsweite Kalibrierstrom GET /calibrations ist genau dafür gebaut. Er liefert alle Kalibrierungen über alle Messmittel in einem seitenweisen Strom, Sie müssen also nicht Messmittel für Messmittel schleifen. Sortieren Sie aufsteigend nach updated_at, blättern Sie durch und merken Sie sich created_at des zuletzt gesehenen Datensatzes. Das Journal wird nur angehängt, ein Kalibrierdatensatz ändert sich nach dem Schreiben also nie und sein created_at ist zugleich seine letzte Änderung. sort=updated_at zeigt auf denselben Zeitpunkt.

Übergeben Sie diesen gespeicherten Wert im nächsten Lauf als updated_since. Überlappen Sie die Grenze um ein oder zwei Sekunden und entdoppeln Sie über die Datensatz-ID, damit eine abweichende Uhr nichts kostet. Speichern Sie die Marke erst, wenn Sie die Seite dauerhaft verarbeitet haben.

Messmittel unterstützen dieselben Parameter updated_since und sort (GET /instruments) und filtern über die letzte Änderung des Messmittels. Die Listenzeilen enthalten kein Zeitstempelfeld. Nehmen Sie für Messmittel deshalb die Uhrzeit, die Sie unmittelbar vor der Anfrage festgehalten haben, als nächstes updated_since. Das einzelne GET /instruments/{id} liefert created_at und updated_at, falls Sie sie brauchen.

GET /instruments nimmt Filter, damit Sie einen genauen Ausschnitt holen statt die ganze Liste zu blättern. asset_tag und serial_number treffen einen exakten Wert, praktisch für den Abgleich eines einzelnen Messmittels gegen einen ERP-Datensatz. status filtert nach dem Zustand im Lebenszyklus, zum Beispiel active oder retired. site_id grenzt auf einen Standort ein.

Zwei Filter leiten sich aus dem Kalibrierzustand ab. compliance_status filtert nach dem berechneten Kennwert, einem von COMPLIANT, WARNING, NON_COMPLIANT oder NOT_CALIBRATED. next_due_before nimmt ein Datum (YYYY-MM-DD) und liefert Messmittel, deren nächste Kalibrierung davor fällig ist. Das ist die Abfrage hinter einer Liste für bald fällige oder überfällige Arbeit. Filter lassen sich kombinieren, Sie können also aktive, nicht konforme Messmittel an einem Standort in einem einzigen Aufruf abfragen.

Eine Kalibrierung zu schreiben ist der eine Schreibvorgang, der sich nie verdoppeln darf. Das Journal wird nur angehängt, eine doppelte Buchung lässt sich also nicht rückgängig machen. Deshalb verlangt POST /instruments/{id}/calibrations ein Kopffeld Idempotency-Key (eine beliebige eindeutige Zeichenkette, die Sie erzeugen, zum Beispiel eine UUID). Es ist Pflicht, nicht optional.

Wird eine Anfrage unterbrochen und Sie wiederholen sie mit demselben Schlüssel, liefert die API den bereits geschriebenen Datensatz zurück, statt einen zweiten zu schreiben. Ein fehlender Schlüssel liefert 400 mit dem Code IDEMPOTENCY_KEY_REQUIRED. Erzeugen Sie je Kalibrierung, die Sie erfassen wollen, einen frischen Schlüssel.

Auch das Anlegen eines Messmittels (POST /instruments) beachtet einen Idempotency-Key, hier ist er aber optional. Senden Sie einen, dann liefert eine Wiederholung mit demselben Schlüssel das Messmittel aus dem ersten Aufruf statt eines Duplikats, genau wie beim Schreiben einer Kalibrierung. Der einzige Unterschied ist, dass der Schlüssel nicht verlangt wird. Wenn Sie beim Anlegen lieber keine Schlüssel verwalten, entdoppeln Sie vor dem POST auf Ihrer Seite über asset_tag oder serial_number des Messmittels, die innerhalb eines Arbeitsbereichs eindeutig sind.

Zu jeder freigegebenen Kalibrierung gehört ein gestalteter PDF-Kalibrierschein. Holen Sie ihn mit GET /calibrations/{calibration_id}/certificate. Die Antwort ist das PDF selbst (Content-Type application/pdf) als Anhang, Byte für Byte identisch mit dem Schein aus der App. So können Sie ihn archivieren oder an einen Auftrag hängen.

Ein Kalibrierschein besteht nur zu einer freigegebenen, aktuellen Kalibrierung. Ist der Datensatz für ungültig erklärt, durch einen späteren Eintrag ersetzt oder sonst nicht bescheinigungsfähig, liefert die Anfrage 404 mit dem Code CERTIFICATE_UNAVAILABLE. Eine Kalibrier-ID, die nicht Ihnen gehört oder nicht existiert, liefert eine schlichte 404, die nichts darüber verrät.

Verlässt ein Messmittel den Betrieb, mustern Sie es mit POST /instruments/{id}/retire aus, ein Aufruf mit Schreibrecht. Das ist eine weiche Außerbetriebnahme: Der Status des Messmittels wird retired und es fällt aus der Standardliste der aktiven Messmittel. Gelöscht wird nichts, und seine Kalibrierhistorie im Journal bleibt für das Audit vollständig erhalten. Ein hartes Löschen gibt es in der API nicht.

Der Aufruf liefert das aktualisierte Messmittel zurück. Er ist idempotent: Ein bereits ausgemustertes Messmittel auszumustern bleibt folgenlos und liefert denselben ausgemusterten Datensatz, eine Wiederholung ist also immer sicher. Ausmustern verlangt einen Schlüssel mit Manager- oder Administratorrolle. Ein reiner Lese-Schlüssel oder ein Technikerschlüssel erhält 403.

Listen-Endpunkte liefern einen einheitlichen Umschlag. Blättern Sie mit den Abfrageparametern limit und offset durch die Ergebnisse. total ist die vollständige Anzahl und has_more sagt Ihnen, ob es eine weitere Seite gibt.

Jeder Zeitstempel, den die API liefert, ist ISO-8601 in UTC und endet auf Z, zum Beispiel 2026-07-09T15:30:00Z. Senden Sie Zeitstempel genauso. Es gibt keine Antworten mit Zeitverschiebung oder Ortszeit, die Sie normalisieren müssten.

Ein Feld ist ein reines Datum, kein Zeitstempel: das Fälligkeitsdatum der Kalibrierung eines Messmittels. Fälligkeiten werden in der eingestellten Zeitzone Ihres Arbeitsbereichs berechnet, ein Fälligkeitsdatum ist also der dortige Kalendertag, und der Filter next_due_before nimmt ein Datum (YYYY-MM-DD) statt eines Zeitstempels. Laufen Ihre Systeme in einer anderen Zone, vergleichen Sie auf das Datum, nicht auf einen Zeitpunkt um Mitternacht UTC.

Jeder Fehler hat an jedem Endpunkt dieselbe JSON-Form: einen maschinenlesbaren code, eine menschenlesbare message und bei manchen Fehlern ein Objekt details mit den Einzelheiten. Verzweigen Sie auf code, nie auf den Text der message, der umformuliert werden kann. Der HTTP-Status trägt weiterhin Bedeutung (401 gegenüber 403 gegenüber 404), nutzen Sie ihn also ebenfalls.

Beim Schreiben einer Kalibrierung werden auch die Feldanforderungen der von Ihrem Arbeitsbereich gewählten Normen durchgesetzt. Fehlt ein Pflichtfeld, liefert die Anfrage 422 mit dem Code FIELD_REQUIREMENTS_UNMET und einem Feld missing_fields, in dem jeder Eintrag das Feld und die fordernde Norm nennt. So können Sie genau danach fragen, was fehlt.

Statt die API im Takt abzufragen, um Änderungen zu finden, melden Sie einmal einen Webhook-Endpunkt an. Axiospec liefert dann jedes Ereignis an Ihre URL, sobald es passiert. Das ist schneller und spart viel unnötigen Verkehr gegenüber dem erneuten Lesen von Sammlungen, die Sie schon kennen. Und keine Änderung geht zwischen zwei Abfragen verloren.

Melden Sie sich mit POST /webhooks an und übergeben Sie eine url sowie optional eine Liste der gewünschten Ereignistypen. Lassen Sie das Feld events weg, um jedes Ereignis zu erhalten. Der vollständige Katalog steht unten. Die Antwort liefert das Signaturgeheimnis des Endpunkts genau einmal und nie wieder, kopieren Sie es also direkt in Ihren Geheimnisspeicher. Die Verwaltung von Webhooks braucht einen Schreib-Schlüssel mit Administrator- oder Managerrolle, denn der Endpunkt empfängt die Kalibrier- und Messmitteldaten Ihres Arbeitsbereichs.

Jedes Ereignis wird als HTTP-POST geliefert, dessen JSON-Rumpf ein fester Umschlag ist: { "id", "type", "created_at", "data" }. Die id ist die stabile Ereignis-ID und wird zusätzlich als Kopffeld Axiospec-Event-Id gesendet, neben Axiospec-Event-Type, Axiospec-Webhook-Id und Axiospec-Delivery-Attempt. Zugestellt wird mindestens einmal, dasselbe Ereignis kann also mehrfach ankommen, etwa nach einer Wiederholung. Entdoppeln Sie über die id im Umschlag.

Eine Zustellung gilt bei jeder Antwort als fehlgeschlagen, die keine 2xx ist, und dazu zählt eine 3xx-Weiterleitung: Eine Weiterleitung könnte auf eine interne Adresse zeigen, deshalb wird ihr nie gefolgt. Transportfehler und Zeitüberschreitungen zählen ebenfalls als Fehlschlag. Fehlgeschlagene Zustellungen werden mit wachsendem Abstand über etwa drei Tage wiederholt, danach gilt die Zustellung als erschöpft. Ein Endpunkt, dessen jüngste Zustellungen alle erschöpfen, wird automatisch abgeschaltet, damit eine tote oder feindliche URL keine Kapazität mehr verbraucht. Endpunkte müssen HTTPS sein, und eine URL, die auf eine private oder interne Adresse auflöst, wird bei der Anmeldung abgelehnt.

Sehen Sie mit GET /webhooks/{id}/deliveries nach, was gesendet wurde. Der Aufruf blättert durch das Zustellprotokoll eines Endpunkts und nimmt einen Filter status (pending, failed, succeeded, exhausted). Um eine Zustellung zu wiederholen, rufen Sie POST /webhooks/{id}/deliveries/{delivery_id}/retry auf: Damit steht sie wieder auf pending und ist sofort fällig, der nächste Versand schickt sie also erneut, mit frischem Wiederholungszeitraum. Tauschen Sie das Geheimnis eines Endpunkts mit POST /webhooks/{id}/rotate-secret, das alte Geheimnis verifiziert sofort nicht mehr. Zustellungen stoppen Sie mit DELETE /webhooks/{id}.

Das sind die Ereignistypen, die ein Webhook abonnieren kann. Nennen Sie bei der Anmeldung die gewünschten, oder lassen Sie das Feld events weg, um alle zu erhalten. Derselbe Katalog steht unter GET /webhooks/events für den programmatischen Abruf bereit.

Jede Zustellung trägt ein Kopffeld Axiospec-Signature in der Form t=<unix-seconds>,v1=<hex>. Prüfen Sie es, bevor Sie einer Nutzlast vertrauen. Eine gültige Signatur belegt, dass die Anfrage von Axiospec stammt und der Rumpf unterwegs nicht verändert wurde.

Lesen Sie das Kopffeld Axiospec-Signature und trennen Sie es am Komma in den Teil t= (ein Unix-Zeitstempel in Sekunden) und den Teil v1= (ein HMAC in Kleinbuchstaben-Hex). Berechnen Sie HMAC-SHA256 neu, mit dem Signaturgeheimnis Ihres Endpunkts als Schlüssel, über die Zeichenkette aus Zeitstempel, einem Punkt und dem exakten rohen Anfragerumpf, also f"{t}.{raw_body}". Vergleichen Sie Ihren Hex-Wert mit dem Wert aus v1 in konstanter Zeit, nie mit einem gewöhnlichen Gleichheitstest.

Signieren Sie die rohen Bytes genau so, wie sie ankommen, vor jedem Auswerten oder erneuten Serialisieren von JSON, damit Ihre Eingabe dem entspricht, was signiert wurde. Weisen Sie die Zustellung zurück, wenn die Werte nicht übereinstimmen oder wenn t älter als etwa fünf Minuten ist. Das begrenzt, wie lange eine abgefangene Anfrage gegen Sie wiedereingespielt werden könnte.