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
• GraphQL-Referenz: Siehe GraphQL-Überblick.

Wählen Sie Ihren Stil

• REST: Stabile, versionierte Ressourcen für CRUD, Paginierung und Webhooks. Starten Sie mit dem REST-Leitfaden und der Authentifizierung.
• GraphQL: Flexible Abfragen und weniger Roundtrips. Starten Sie mit dem GraphQL-Überblick und der Auth.

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 Custom-Object-Konzepte 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 Custom Objects equipment und maintenance_request über createDefinition. Legen Sie anschließend RTU-17 und die Wartungsanfrage zur zu hohen Temperatur mit createInstances an.
3. Verknüpfen Sie die Wartungsanfrage über createRelations mit RTU-17.
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

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