Externe API
Verbinden Sie eigene Systeme über die externe API mit einer TARGPatrol-Organisation. Diese Anleitung behandelt Zugriff, Authentifizierung und sichere Integration. Feldbeschreibungen und konkrete Endpunktbeispiele finden Sie in der API-Referenz.
Verfügbarkeit und API-Schlüssel
Die externe API ist mit Base und Enterprise verfügbar, nicht mit Free. Der Organisationseigentümer erstellt und verwaltet API-Token im Web. Ein Schlüssel identifiziert genau eine Organisation und ist kein persönliches Passwort oder mobile Benutzer-ID/PIN.
Melden Sie sich im Web an und öffnen Sie die richtige Organisation als Eigentümer.
Öffnen Sie Verwaltung → Externe API und wählen Sie Token hinzufügen.
Vergeben Sie einen aussagekräftigen Integrationsnamen, speichern Sie das Token und kopieren Sie den Schlüssel.
Speichern Sie ihn serverseitig in einer Geheimnisverwaltung. Verwenden Sie möglichst getrennte Token pro Integration und widerrufen Sie nicht mehr benötigte Token.
Anfragen authentifizieren
Senden Sie HTTPS-Anfragen an den in der Referenz genannten API-Host mit dem Basispfad /api/v1. Übergeben Sie den Schlüssel im Request-Header x-api-key. Eine Web-Anmeldung authentifiziert keine externe Anfrage. Schlüssel gehören nicht in URLs, Browsercode, Screenshots, öffentliche Repositories oder Logs.
1x-api-key: <YOUR_API_KEY>Referenz nutzen und sicher testen
Öffnen Sie die API-Referenz und prüfen Sie Methode, Pfad, Pflichtfelder und Antwortschema der gewünschten Operation.
Beginnen Sie mit einer Leseanfrage und prüfen Sie die Organisation der Ergebnisse. Interaktive Referenzanfragen können echte Daten betreffen.
Verwenden Sie die für den Endpunkt dokumentierte Seiteneinteilung, Filterung und Sortierung; Standardwerte können abweichen.
Prüfen Sie vor Änderungen POST-, PUT- oder PATCH-Semantik sowie ausgelassene, null- oder leere Werte. Testen Sie Schreibzugriffe zuerst in einer Testorganisation.
Behandeln Sie Netzwerk- und Serverfehler kontrolliert. Wiederholen Sie Erstellanfragen nicht blind und protokollieren Sie keine Schlüssel oder personenbezogenen Daten.
API-Referenz und interaktiver Explorer
Zugriffsprobleme beheben
Prüfen Sie bei 401 den Header x-api-key und die Gültigkeit des Tokens. Bei 403 prüfen Sie Tarif und Voraussetzungen der Operation. Bei 404 prüfen Sie URL, Kennung und Organisation; bei 400 Anfrageformat und Validierungsdetails. Ersetzen Sie offengelegte Schlüssel und aktualisieren Sie alle betroffenen Integrationen.
Neuerungen in der API-Referenz
1.1
Referenz 1.1 machte lastName beim Erstellen von Benutzern zum Pflichtfeld und korrigierte den Feldnamen für Standortzuweisungen zu locationIds. Prüfen Sie beim Vorbereiten von Anfragen das aktuelle Benutzerschema.
1.2
Referenz 1.2 ergänzte temporäre signierte Download-URLs für Anhänge älterer Issues sowie, falls verfügbar, URLs für Vorschaubilder. Die Download-Links müssen vor ihrem Ablauf verwendet werden.
1.3
Referenz 1.3 ergänzte das Auflisten und Erstellen von Kommentaren für Aufgaben, Incidents und ältere Issues sowie das Bearbeiten und Löschen von über die API erstellten Kommentaren. Vorhandene Kommentar-Anhänge lassen sich lesen und herunterladen; das Hochladen von Anhängen und das Bearbeiten von Kommentaren aus der Anwendung werden über diese API nicht unterstützt.
1.4
Referenz 1.4 führte strukturierte internationale Telefonmetadaten und Validierung für Benutzerdaten ein. Die genauen Anfrage- und Aktualisierungsregeln stehen in den aktuellen Schemas.
1.5
Referenz 1.5 ergänzte schreibgeschützten Änderungsverlauf pro Datensatz. Spätere Ergänzungen dokumentieren Benutzer-, Standort- und Punktverlauf sowie Punkt-Anzeigereihenfolge und eigene Operationen zum Neuordnen/Verschieben. Prüfen Sie die aktuelle Referenz für unterstützte Operationen und Kompatibilität.
1.6
Referenz 1.6 beschreibt kalenderbasierte Aufgabenwiederholungen mit expliziter Zeitzone und gespeicherter lokaler Start-/Endvorlage. Prüfen Sie vor dem Erstellen oder Bearbeiten einer Serie das aktuelle Wiederholungsschema.
1.7
Referenz 1.7 ergänzt schreibgeschützte Geofence-Ereignisse und zugehörige Standort-/Benutzerfelder sowie abgestimmte Tag-Operationen. Authentifizierung und /api/v1 bleiben unverändert. Maßgeblich für Schemas, Rechte und Validierung ist die aktuelle API-Referenz; Geofence-Webhooks sind nicht Teil dieser Änderung.
Dies sind Referenz-/Schemaversionen, keine neuen URL-Präfixe: Der Basispfad bleibt /api/v1. Diese Übersicht ersetzt kein vollständiges Änderungsprotokoll. Für ereignisbasierte Aktualisierungen werden Webhooks separat konfiguriert.