Dieser Artikel ist sehr technisch. Er wendet sich an Informatiker und Entwickler. Das Ziel dieses Artikels ist es nicht, dir die Funktionsweisen einer API zu erklären. Wenn du diesen Artikel liest, gehen wir davon aus, dass du weisst, was APIs sind und wie man mit ihnen arbeitet. Das Ziel des Artikels ist es, Software-Entwicklern aufzuzeigen, welche Daten über die API abgefragt werden können.

Die API findest du in der Administration unter Organisation --> Integrations API's.

Bevor du die API brauchen kannst, musst du einen API Key erstellen.

ACHTUNG: der API Key wird dir NUR unmittelbar nach dem Erstellen angezeigt. Speichere ihn an einem sicheren Ort. Der API Key erlaubt Zugriff auf die persönlichen Daten deiner Helfenden und muss daher vertraulich behandelt werden!

Den API Key musst du bei deinen Abfragen als X-API-KEY im Anfrage Header mitgeben. Für das Testen deiner API empfehlen wir dir ein Tool. Zum Beispiel: Postman

Helpers: Helfende

Mit dem ersten Service kannst du alle Helfende abfragen:

https://api.helfereinsatz.ch/v1/[dein-organisations-pfad]/helpers/[seiten-nr]

Du bekommst ein JSON File zurück. Dies enthält auf oberster Ebene drei Einträge:

• pageNo: aktuelle Seite (vgl. seiten-nr
• pagesNum: totale Anzahl Seiten --> Das musst du wissen, um alle Helfenden über die API abzufragen
• entries: ein Array mit allen Helfenden

entries (Helfer) Eigenschaften

Das Array der Helfenden hat folgende Werte:

• id: Unique Identifier des Helfers
• firstName: Vorname
• lastName: Nachname
• email: E-Mail
• phone: Telefon
• additionalEmail1: zusätzliche E-Mail 1
• additionalEmail2: zusätzliche E-Mail 2
• adminRemarks: Bemerkungen zum Helfenden
• birthDate: Gebrutstag (im Format YYYY-MM-DD)
• infoFill: Array für jedes deiner Spezialfelder, die du erfasst hast
• groups: Array mit allen Gruppen
• stateCache: Array mit den Werten des Helfenden

infoFill Eigenschaften

Jedes infoFill Item hat folgende Werte:

• label: Name des Feldes
• value: Variable oder Array der Werte des Helfenden für dieses Feld

groups Eigenschaften1

Jedes groups Item hat folgende Werte:

• id: Unique Identifier der Gruppe
• name: Name der Gruppe

stateCache Eigenschaften

Der stateCache Array hat folgende Werte

• okAssignmentsNum: Anzahl erfolgreich geleisteter Einsätze
• nokAssignmentsNum: Anzahl verpasster Einsätze (zugesagt, aber nicht erschienen)
• confirmedAssignmentsNum: zugesagter Einstäze (der Einsatz liegt also noch in der Zukunft)
• reservedAssignmentsNum: bei Double-Opt-in in werden hier die Einsätze gezählt, welche er reserviert aber noch nicht bestätigt hat
• requestedValue: Zielwert
• plannedValue: okAssignmentsNum + confirmedAssignemntsNum 
• unconfirmedAssignmentsNum: bei Double-Opt-in Anzahl Einsätze, welche er mal reserviert hat, die Zeitfrist aber verpasst hat, um den Einsatz zu bestätigen

Achtung: Wo Num steht, handel es sich um die Anzahl. Wo Value steht, um den Wert des Einsatzes. Wenn Helfer A einen Helfereinsatz für Helfer B leistet, dann sind Helfer A Anzahlen ersichtlich und die Werte des Einsatzes werden bei Helfer B gutgeschrieben.

Events

Mit diesem Service kannst du die Events un ihre Schichten abfragen. Auf diesem Service sind die Einsätze nicht drauf, weil dies zu umfangreich würde. 

https://api.helfereinsatz.ch/v1/[pfad-deiner-organisation]/events/[seiten-nr]

Dieser Service liefert ein JSON zurück. Auf oberster Ebene kriegst du folgende Eigenschaften:

• id: unique Identifier des Events (brauchst du für den Helfereinsatz Service.)
• name: Name des Events
• date: Datum des Events im Format YYYY-MM-DD HH-MM-SS --> ist nicht mehr relevant (deprecated)
• timeStart: Startdatum des Events im Format YYYY-MM-DD HH-MM-SS
• timeEnd: Enddatum des Events im Format YYYY-MM-DD HH-MM-SS
• remarks: Event-Bemerkungen
• online: Online Status des Events
• done: zeigt an, ob das Event verarbeitet wurde. Bei der Verarbeitung werden alle Helfereinsätze auf Status OK gesetzt.
• stateCache: zwischengespeicherte Werte des Events (siehe unten)
• category: Bereich des Events (wenn vorhanden)
• shifts: Schichten des Events

stateCache Eigenschaften Event

• confirmedHelperAssignmentsNum: Anzahl bestätigte Einsätze (bei zukünftigen Events)
• okHelperAssignmentsNum: Anzahl erfolgreich geleistete Einsätze (bei Events in der Vergangenheit)
• totalHelperAssignmentsNum: Anzahl aller Einsätze

category (Bereiche) Eigenschaften

• id: unique Identifier des Bereiches
• name: Name des Bereiches

shifts (Schichten) Eigenschaften

• id: unique Identifier der Schicht
• name: Name der Schicht
• startDateTime: Startzeitpunkt der Schicht im Format YYYY-MM-DD HH-MM-SS
• endDateTime: Endzeitpunkt der Schicht im Format YYYY-MM-DD HH-MM-SS
• remarks: Schicht-Bemerkungen
• stateCache: zwischengespeicherte Werte der Schicht

stateCache Eigenschaften Schicht

• confirmedHelperAssignmentsNum: Anzahl bestätigte Einsätze der Schicht (bei zukünftigen Events)
• okHelperAssignmentsNum: Anzahl erfolgreich geleistete Einsätze der Schicht (bei Events in der Vergangenheit)
• totalHelperAssignmentsNum: Anzahl aller Einsätze
• misfit: true wenn es Helfer gibt, welche Einsätze übernommen haben, die nicht zu ihren Gruppen passten

•  

HelperAssignements: Helfereinsätze eines Events

Mit diesem Service kannst du die Helferiensätze auf einem Event abfragen. Für diesen Event brauchst du die ID des Events, den du abfragen willst. Die ID kriegst du über den Events Endpoint.

https://api.helfereinsatz.ch/v1/[pfad-deiner-organisation]/helperassignments/[id-des-events]/[seiten-nr]

Mit diesem Service bekommst du ein JSON zurück mit folgenden Eigenschaften:

• pageNo: Aktuelle Seite
• pagesNum: Totale Anzahl Seiten dieses Services
• entries: Helfereinsätze

entries (Helfereinsätze)

• id: unique Identifier des Einsatzes
• responsible: true, wenn dieser Helfer für den Einsatz verantwortlich ist
• remarks: Bemerkungen für den Helfenden, der diesen Einsatz übernimmt
• value: Einsatzwert
• plannedValue: wird von value übernommen, wenn der Einsatz Status confirmed, reserved oder ok hat
• status: Status des Einsatzes --> Die möglichen Werte werden nachfolgend aufgelistet
• startDateTime: Startzeit des Einsatzes
• endDateTime: Endzeit des Einsatzes
• hours: Anzahl Stunden des Einsatzes
• role: Aufgabe des Einsatzes
• shift: Eigenschften der Schicht
• helper: Wenn ein Helfer die Schicht schon übernommen hat, findest du hier die Eigenschaften des Helfers eingetragen.
• helpAsHelper: wenn der Helfer, der die Schicht übernommen hat, diesen Einsatz für einen anderen Helfer übernimmt, wird hier der Helfer eingetragen, der den Einsatz gutgeschrieben bekommt.
• stateCache: Zwischengespeicherte Werte auf dem Einsatz

status Werte

Der Status eines Einsatzes kann folgende Werte haben:

• open: offener Einsatz
• confirmed: ein Helfer hat den Einsatz übernommen
• reserved: bei Double-Opt-in gilt der Einsatz als reserved, sobald ihn ein Helfer übernommen, aber noch nicht bestätigt hat
• unconfirmed: bei Double-Opt-in gilt ein Einsatz als unconfirmed, wenn die Reservationszeit (24h) abgelaufen ist
• ok: der Einsatz wurde geleistet
• nok: der Einsatz wurde nicht geleistet

role Eigenschaften

• id: unique Identifier der Aufgabe
• name: name der Aufgabe

shift Eigenschaften

Die Schichteigenschaften sind die gleichen, wie beim Event-Service! Sie werden darum hier nicht wiederholt. Du findest sie oben beschrieben.

ACHTUNG: die Schichteigenschaften liegen auf jedem Einsatz. Wenn du ein Event mit 30 Einsätzen verteilt auf 3 Schichten à 10 Einsätze hast, haben alle 10 Einsätze der gleichen Schicht, die gleichen Eigenschaften auf shift!

helper resp. helpAsHelper Eigenschaften

• id: unique Identifier des Helfers
• firstName: Vorname des Helfers
• lastName: Nachname des Helfers
• email: E-Mail des Helfers
• phone: Telefon des Helfers

Achtung: wenn du mehr Informationen zum Helfer brauchst, musst du diese über den Helper Service abfragen!

stateCache Eigenschaften des Einsatzes

• misfit: true, wenn der Helfer einen Einsatz übernimmt, der NICHT zu seinen Gruppen passt.