Zum Hauptinhalt springen

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​

Wählen Sie Ihren Stil​

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:

  1. Legen Sie die Qualifikation HVAC maintenance mit createSkill und Jonas Leitner mit createUser an. Weisen Sie ihm die Qualifikation über updateUserSkills zu und erstellen Sie mit createArea das Servicegebiet Wien Nord.
  2. Definieren Sie die Objekte equipment und maintenance_request über createObject. Das Schema der Wartungsanfrage deklariert seine typisierte Relation zur Anlage und deren verwaltete Rückseite.
  3. Legen Sie RTU-17 und die Wartungsanfrage zur zu hohen Temperatur mit createRecord an. Die Wartungsanfrage verknüpft sich über ihren Relationswert mit RTU-17; siehe Relationsleitfaden für Objekte und Datensätze.
  4. Erstellen Sie mit createFolder den Ordner Equipment manuals und fordern Sie danach über initiateDocumentUpload den Upload für RTU-17 service manual.pdf an.
  5. Legen Sie mit createTag das Tag urgent an und erfassen Sie Jonas' Eintrag Replacement filter ordered mit createComment.
  6. Senden Sie Lebenszyklusereignisse an die Alpine-Integration, indem Sie https://maintenance.example.invalid/tourfold/events mit createWebhookEndpoint registrieren.

Ö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 } } } }"}'