Tourfold-API – Überblick
Nutzen Sie die Tourfold-APIs, um Arbeitsabläufe zu automatisieren, Ihre Systeme zu integrieren und Erlebnisse direkt im Produkt bereitzustellen. Wir unterstützen sowohl REST als auch GraphQL.
Endpoints
REST
- Produktion:
https://api.tourfold.com/api/v2/
GraphQL
- Query-Endpoint (
POST):https://api.tourfold.com/api/v2/graphql - Schema-Endpoint (
GET):https://api.tourfold.com/api/v2/graphql/schema
Referenzen
- OpenAPI-Referenz (REST): /openapi — YAML-Spezifikation herunterladen
- API-Spezifikationen für Plugins: Unter Einstellungen → Allgemein → Funktionen & Plugins herunterladen. Siehe Plugin-Downloads.
- GraphQL-Referenz: Siehe
GraphQL-Überblick. - Leitfaden für Objekte und Datensätze:
Objekte und Datensätzebeschreibt das gemeinsame Datenmodell von REST und GraphQL.
Wählen Sie Ihren Stil
- REST: Stabile, versionierte Ressourcen für CRUD, Paginierung und Webhooks. Starten Sie mit dem
REST-Leitfaden, derAuthentifizierungundObjekte und Datensätze. - GraphQL: Flexible Abfragen und weniger Roundtrips. Starten Sie mit dem
GraphQL-Überblickund derAuth.
Beispielszenario
Die Beispiele in der API-Referenz folgen der Alpine Facility Services GmbH, einem fiktiven Wartungsunternehmen in Wien. Disponentin Mara Berger koordiniert den Techniker Jonas Leitner und das Servicegebiet Wien Nord, verwaltet Anlagen wie die Rooftop HVAC Unit RTU-17 und deren Wartungsanfragen, legt Wartungshandbücher ab, erfasst Kommentare und Tags und leitet Lebenszyklusereignisse an einen Webhook weiter.
Das Unternehmen, die Personen, IDs und Datensätze dienen ausschließlich dazu, die Beispiele
konsistent zu halten. Tourfold legt diese Daten nicht automatisch in Ihrem Arbeitsbereich an.
REST-Beispiele zeigen Schreibvorgänge und stabile Ressourcendarstellungen; die
GraphQL-Beispiele zeigen Filterung, Sortierung, Paginierung und Navigation für
dieselben Objekte equipment und maintenance_request.
Ablauf des Szenarios
Die Beispiele auf Operationsebene in der OpenAPI-Referenz bilden einen kurzen Ablauf:
- Legen Sie die Qualifikation
HVAC maintenancemitcreateSkillund Jonas Leitner mitcreateUseran. Weisen Sie ihm die Qualifikation überupdateUserSkillszu und erstellen Sie mitcreateAreadas Servicegebiet Wien Nord. - Definieren Sie die Objekte
equipmentundmaintenance_requestübercreateObject. Das Schema der Wartungsanfrage deklariert seine typisierte Relation zur Anlage und deren verwaltete Rückseite. - Legen Sie RTU-17 und die Wartungsanfrage zur zu hohen Temperatur mit
createRecordan. Die Wartungsanfrage verknüpft sich über ihren Relationswert mit RTU-17; sieheRelationsleitfaden für Objekte und Datensätze. - Erstellen Sie mit
createFolderden Ordner Equipment manuals und fordern Sie danach überinitiateDocumentUploadden Upload für RTU-17 service manual.pdf an. - Legen Sie mit
createTagdas Tagurgentan und erfassen Sie Jonas' Eintrag Replacement filter ordered mitcreateComment. - Senden Sie Lebenszyklusereignisse an die Alpine-Integration, indem Sie
https://maintenance.example.invalid/tourfold/eventsmitcreateWebhookEndpointregistrieren.
Öffnen Sie die jeweils verlinkte Operation, um zwischen ihren benannten Request- und Success-Response-Beispielen zu wechseln. Der Ablauf hier erklärt die Zusammenhänge; für Payload-Felder und Schemas bleibt die OpenAPI-Referenz maßgeblich.
Fehler
REST verwendet RFC 9457 Problem-Details. GraphQL liefert Fehler im GraphQL-errors-Array (üblicherweise mit HTTP 200 OK). Siehe Fehler.
Schnellstart
Eine vollständige erste Integration – vom Token und der Objektdefinition über REST und GraphQL bis zum signierten Webhook – finden Sie unter Ihr erster Tourfold-Datenfluss. Der Ablauf ist für einen Entwicklungs-Workspace gedacht und erklärt, welche Teile Sie für eine produktive Synchronisierung beibehalten sollten.
REST
curl -X GET "https://api.tourfold.com/api/v2/areas" \
-H "Authorization: Bearer YOUR_TOKEN"
GraphQL
curl -X POST "https://api.tourfold.com/api/v2/graphql" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query":"query { equipment(first: 5, order_by: [{ name: asc }]) { edges { node { id name asset_tag } } } }"}'