API-Schnittstelle nutzen

API-Schluessel

Erstellen und verwalten Sie API-Schluessel im Benutzerprofil (erfordert Business plan). Schluessel werden nur einmal bei Erstellung vollstaendig angezeigt; uebergeben Sie den Schluessel bei jeder Anfrage im X-API-Key-Header.

Verfuegbare Endpunkte

API-Schluessel steuern dieselben Endpunkte an wie die Weboberflaeche. Dieser Leitfaden beschreibt zwei Kernablaeufe: Koordinatentransformation unter /api/v1/axis und Qualitaetsanalyse unter /api/v1/quality-analysis. Tarifgrenzen gelten identisch zur Weboberflaeche.

Koordinatentransformation per API

Senden Sie einen POST-Request an /api/v1/axis/transform mit Quell- und Ziel-CRS, Koordinatendaten und dem X-API-Key-Header. Die Antwort entspricht der Struktur in Axis einschliesslich des Transformationspfads.

Ablauf einer Qualitaetsanalyse

1. Dateien hochladen: POST an /api/v1/quality-analysis/upload als multipart/form-data (Feldname files, bis zu 20 Dateien pro Request) mit dem X-API-Key-Header. Die Rueckgabe enthaelt die Dateieintraege.
2. Analyseauftrag starten: POST an /api/v1/quality-analysis/tasks mit JSON {"config": {"tool": "<mode id>"}, "files": [<Dateieintraege aus Schritt 1>]}. Moduskennungen: "fast" fuer Fast Mode, "flash" fuer Flash Mode, "full" fuer Full Mode, "teqc" fuer TEQC Mode.
3. Status abfragen: Wiederholen Sie GET an /api/v1/quality-analysis/tasks/{taskId}, bis der Status completed meldet; die Antwort enthaelt dann das vollstaendige Ergebnisobjekt.
4. Bericht abrufen: Den PDF-Pruefbericht erhalten Sie ueber GET an /api/v1/quality-analysis/tasks/{taskId}/report.pdf.

Webhooks fuer asynchrone Ereignisse

Statt Statusabfragen in Schleifen durchzufuehren, koennen Sie Webhooks registrieren, ueber die PosFlow nach Abschluss eines Auftrags aktiv benachrichtigt. Verwaltung unter /api/v1/webhooks: POST zum Anlegen (JSON mit url, events und optional secret/description), GET fuer Listen, DELETE /api/v1/webhooks/{id} zum Entfernen und POST /api/v1/webhooks/{id}/test fuer Testaufrufe. Ziel-URLs muessen oeffentlich ueber https erreichbar sein; private IP-Adressen werden abgelehnt.

Ereignistypen und Payload

Derzeit werden drei Ereignisse unterstuetzt: "analysis.completed" bei erfolgreichem Abschluss einer Qualitaetspruefung oder Auswertung sowie "processing.completed" / "processing.failed" beim Erreichen des Endstatus einer Konvertierung. Jede Benachrichtigung ist ein JSON-POST mit event, timestamp, eindeutiger id und data-Objekt. Der Ereignisname wird zusaetzlich im X-Webhook-Event-Header uebergeben.

Signaturpruefung und Zuverlaessigkeit

Ist ein Secret hinterlegt, traegt jeder Aufruf die HMAC-SHA256-Signatur des Rohinhalts im Header X-POSFLOW-Signature ("sha256=<hex>"; X-Webhook-Signature traegt den reinen Hexwert). Berechnen Sie den Hashwert zur Verifikation. Fehlgeschlagene Zustellungen werden bis zu dreimal wiederholt; nach zehn aufeinanderfolgenden Fehlern wird der Webhook automatisch deaktiviert. Stellen Sie sicher, dass Empfaengerserver zeitnah mit 2xx antworten.

Nutzungsrichtlinien

Anfragen unterliegen planbasierten Ratenbegrenzungen. Nutzen Sie Batch-Abfragen und implementieren Sie Wiederholungsstrategien bei Fehlern; fuer dauerhaft hohe Durchsaetze stimmen Sie Kapazitaeten bitte vorab mit dem Support ab.