API-Dokumentation

Shifton Aufgaben erlaubt es Ihnen, die Arbeit mit der Plattform zu automatisieren und sie über eine offene API an externe Dienste anzubinden. Über die API sind alle wichtigen Entitäten verfügbar — Aufgaben, Kunden, Mitarbeiter, Checklisten, Bestand, Servicebereiche, Dokumente der Finanzdokumente und Berichte —, deshalb lässt sich Shifton mit Ihren Systemen für HR, Lohnabrechnung und Analytik sowie mit den internen Diensten des Unternehmens verbinden.

Die Dokumentation ist in zwei Versionen veröffentlicht:

🚀 Neue Dokumentation — die aktuelle Version des Handbuchs mit überarbeiteter Struktur und den neuesten Methoden: 👉 https://api2.shifton.com/openapi/
📄 Alte Dokumentation — die vorherige Version (wird für bestehende Integrationen weiterhin unterstützt): 👉 https://api2.shifton.com/docs/

Beide Versionen lassen sich direkt aus der Anwendung öffnen — im Bereich Developer, auf der Registerkarte Übersicht, über die Schaltflächen „Neue Dokumentation“ und „Alte Dokumentation“.

Die Dokumentation ist in zwei Sprachen verfügbar. Oben rechts in der Ecke der Seite der neuen Dokumentation gibt es einen Umschalter EN / RU — die gewählte Sprache wird gespeichert.

So erhalten Sie einen API-Schlüssel

Der API-Schlüssel wird in der Anwendung selbst erstellt:

Öffnen Sie den Bereich Developer.
Wechseln Sie zur Registerkarte API-Schlüssel („API-Schlüssel“).
Klicken Sie auf „API-Schlüssel erstellen“.

Was beim Erstellen des Schlüssels auszufüllen ist

Es öffnet sich das Seitenpanel API-Schlüssel erstellen mit den Feldern:

Titel — der Name des Schlüssels, ein Pflichtfeld. Benennen Sie ihn nach seinem Zweck, damit später klar ist, was abzuschalten ist: „Export nach 1C“, „Berichte für die Analytik“.
Läuft ab um — das Datum, nach dem der Schlüssel nicht mehr gilt. Bleibt das Feld leer, ist die Gültigkeit unbegrenzt.
Zugriff — der Umfang der Rechte des Schlüssels:
Full access (act as me) — der Schlüssel arbeitet in Ihrem Namen und mit Ihren Rechten.
Eingeschränkte Berechtigungen — ein eingeschränkter Satz von Berechtigungen, den Sie selbst auswählen.

Klicken Sie auf Hinzufügen, um den Schlüssel zu erstellen, oder auf Abbrechen, um das Panel zu schließen.

📷 *Screenshot des Panels zur Schlüsselerstellung — auf der Produktion aufnehmen*

Der Schlüssel wird für ein konkretes Unternehmen erstellt und arbeitet nur mit dessen Daten. Widerrufen lässt sich der Schlüssel jederzeit — der Widerruf wirkt sofort, und alle nachfolgenden Anfragen mit diesem Schlüssel geben den Fehler 401 zurück.

Wichtig: Der erstellte Schlüssel wird nur ein einziges Mal angezeigt. Kopieren Sie ihn sofort und bewahren Sie ihn an einem sicheren Ort auf — ein erneuter Abruf ist nicht möglich. Ist der Schlüssel verloren, erstellen Sie einen neuen und widerrufen Sie den alten.

Autorisierung

Alle Anfragen an die API werden mit dem Schlüssel im Header signiert:

Authorization: Bearer {your_API_key}

Die Basisadresse der API:

https://api2.shifton.com/work/1.0.0

Eine Anfrage ohne gültigen Schlüssel gibt 401 und den Body {"message":"Unauthenticated."} zurück.

Häufig gestellte Fragen

Um zum Beispiel die Liste der Mitarbeiter des Unternehmens zu erhalten (setzen Sie Ihre Unternehmens-ID anstelle von {companyId} ein):

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

Dasselbe über curl:

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

Die Unternehmens-ID ist in der Adresszeile der Anwendung zu sehen: app.shifton.com/c/8397/... — die Zahl nach /c/.

Was über die API verfügbar ist

Das Handbuch umfasst mehr als 360 Methoden. Die wichtigsten Bereiche für den Außendienst:

Aufgaben — /companies/{companyId}/tasks: Erstellen, Ändern, Status, Dateien der Aufgaben.
Aufgabenliste (To Do) — /companies/{companyId}/todo.
Kunden — /companies/{companyId}/clients sowie Adressen und benutzerdefinierte Felder der Kunden.
Checklisten — /companies/{companyId}/checklists.
Servicebereiche — /companies/{companyId}/tasks/service-areas.
Fertigkeiten — /companies/{companyId}/skills.
Mitarbeiter — /companies/{companyId}/employees: Hinzufügen, Bearbeiten, Entlassen und Wiederherstellen.
Bestand — Gegenstände, Kategorien, Sets und Bestände in den Lagern.
Finanzdokumente — Kostenvoranschläge, Arbeitsaufträge, Rechnungen, Quittungen, Dokumentenzähler und Logo.
Berichte — Export von Daten über Arbeit und Anwesenheit.

Darüber hinaus sind Dienstpläne und Schichten, Urlaube und Anträge auf Freistellung, Anwesenheit, Abrechnung und SMS-Abrechnung, Benachrichtigungen und Module verfügbar.

Webhooks

Wenn Sie statt regelmäßiger Anfragen an die API Ereignisse im Moment ihres Auftretens erhalten möchten, nutzen Sie Webhooks — die Registerkarte Webhooks im Bereich Developer. Shifton sendet selbst eine Anfrage an Ihre Adresse, wenn das gewünschte Ereignis eintritt; die Liste der unterstützten Ereignisse gibt eine separate Methode zurück.

Fehlercodes

Die API von Shifton verwendet die standardmäßigen HTTP-Statuscodes:

200 — die Anfrage wurde erfolgreich ausgeführt.
201 — das Objekt wurde erfolgreich erstellt.
400 — fehlerhafte Parameter der Anfrage.
401 — Autorisierungsfehler: der Schlüssel wurde nicht übergeben, ist ungültig oder widerrufen.
403 — der Zugriff ist verboten.
404 — die Ressource wurde nicht gefunden (meist ein Tippfehler in der Adresse der Methode).
500 — Serverfehler.

Tipps zur Nutzung

Nutzen Sie für neue Integrationen die neue Dokumentation — die alte ist für bereits laufende Integrationen erhalten geblieben.
Zum Prüfen der Anfragen eignen sich Postman oder curl — damit sehen Sie die Antwort, ohne eine einzige Zeile Code zu schreiben.
Speichern Sie den Schlüssel nicht im Klartext im Code und geben Sie ihn nicht an Dritte weiter: der Schlüssel gibt Zugriff auf die Daten des Unternehmens.
Halten Sie die Beschränkungen der Anfragehäufigkeit (rate limits) ein — ihre Überschreitung kann zu einer vorübergehenden Sperrung des Zugriffs auf die API führen.

Häufig gestellte Fragen

Frage: Wo bekommt man einen API-Schlüssel? Antwort: In der Anwendung: Bereich Developer → Registerkarte API-Schlüssel → Schaltfläche „API-Schlüssel erstellen“. Der Schlüssel wird für das aktuelle Unternehmen ausgegeben.

Frage: Ich habe den Schlüssel nicht kopiert. Wo sehe ich ihn? Antwort: Nirgends — der Schlüssel wird nur ein einziges Mal angezeigt und nicht erneut ausgegeben. Erstellen Sie einen neuen Schlüssel und widerrufen Sie den alten.

Frage: Wie widerruft man einen Schlüssel, der in falsche Hände geriet? Antwort: Löschen Sie ihn auf der Registerkarte API-Schlüssel. Der Widerruf wirkt sofort: alle Anfragen mit diesem Schlüssel geben ab da 401 zurück.

Frage: Was unterscheidet „Full access“ und „Restricted permissions“? Antwort: Full access (act as me) gibt dem Schlüssel dieselben Rechte, die Sie haben. Eingeschränkte Berechtigungen erlaubt es, dem Schlüssel nur den ausgewählten Satz von Berechtigungen zu geben — das ist sicherer für eine Integration, die nur Zugriff auf einen Teil der Daten braucht.

Frage: Lässt sich die Gültigkeitsdauer des Schlüssels begrenzen? Antwort: Ja, über das Feld Läuft ab um beim Erstellen. Wird es nicht ausgefüllt, gilt der Schlüssel unbefristet.

Frage: Funktioniert ein Schlüssel für mehrere Unternehmen? Antwort: Nein. Der Schlüssel ist an das Unternehmen gebunden, in dem er erstellt wurde, und arbeitet nur mit dessen Daten. Für ein anderes Unternehmen erstellen Sie einen eigenen Schlüssel.

Frage: Welche Basisadresse hat die API? Antwort: https://api2.shifton.com/work/1.0.0. Danach folgt der Pfad der Methode, zum Beispiel /companies/{companyId}/tasks.

Frage: Wo bekommt man die Unternehmens-ID für die Anfragen? Antwort: Sie steht in der Adresszeile der Anwendung direkt nach /c/ — zum Beispiel ist in app.shifton.com/c/8397/tasks die Unternehmens-ID gleich 8397.

Frage: Welche Version der Dokumentation soll man nutzen? Antwort: Für neue Integrationen die neue (api2.shifton.com/openapi). Die alte (api2.shifton.com/docs) wird für bestehende Integrationen unterstützt.

Frage: Gibt es die Dokumentation auf Russisch? Antwort: Ja. Auf der Seite der neuen Dokumentation gibt es oben rechts in der Ecke den Umschalter EN / RU.

Frage: Womit testet man Anfragen an die API? Antwort: Am bequemsten sind Postman oder curl — damit lassen sich Anfragen senden und Antworten ansehen, ohne Code zu schreiben.

Frage: Warum kommt 401, obwohl ich den Schlüssel kopiert habe? Antwort: Prüfen Sie, ob der Schlüssel im Header Authorization mit dem Wort Bearer davor übergeben wird, ob der Schlüssel nicht widerrufen ist und seine Gültigkeit nicht abgelaufen ist.

Frage: Warum kommt 404? Antwort: Meist ist die Adresse vertauscht: der Basisteil muss https://api2.shifton.com/work/1.0.0 lauten, und im Pfad der Methode muss die richtige {companyId} stehen.

Frage: Was lässt sich über die API automatisieren? Antwort: Das Erstellen und Ändern von Aufgaben, die Arbeit mit Kunden und ihren Adressen, Checklisten, Servicebereiche, Fertigkeiten, Mitarbeiter, Bestand, die Dokumente der Finanzdokumente und den Export von Berichten sowie Dienstpläne, Schichten und Urlaube.

Frage: Kann man Ereignisse aus Shifton erhalten, statt die API abzufragen? Antwort: Ja, dafür gibt es Webhooks — die Registerkarte Webhooks im Bereich Developer.

Frage: Wirkt sich ein Passwortwechsel auf die Integration aus? Antwort: Nein. Integrationen arbeiten über den API-Schlüssel, nicht über das Passwort des Kontos.