Mit der Helfereinsatz API können andere Applikationen Informationen aus Helfereinsatz beziehen. So können Informationen über Helfende, Events, Schichten und Einsätze bezogen werden. Das Bearbeiten von Daten ist über die API nicht möglich.

Die Helfereinsatz-API's bieten Informatikern und Entwicklern die Möglichkeit, Daten aus Helfereinsatz abzufragen und gemäss eigenen Wünschen aufzubereiten. Die API findet ihr ab dem Pro-Abo in der Administration unter "Organisation" - "Intergrations API's". Sämtliche Inhalte der Seite sind für Fachpersonen aufbereitet und sollten von ebensolchen verarbeitet werden. Für fehlerhafte Datenauswertungen aufgrund falscher Anwendung kann Helfereinsatz keine Haftung übernehmen.

API-Key

Zuallererst muss der API-Key erstellt werden. Das geschieht via Klick auf den Button "API-Key" und anschliessend über "Hinzufügen". Hier gebt ihr nun den Namen ein und speichert. Anschliessend wird euch der Key angezeigt und ihr könnt ihn direkt kopieren.

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

Der API-Key muss bei Abfragen als X-API-KEY im Anfrageheader mitgegeben werden. Um die API zu testen empfehlen wir ein Tool, beispielsweise Postman.

 

Verfügbare API-Calls

Helpers: Helfende

Mit dem ersten Service könnt ihr alle Helfenden abfragen:

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

Ihr bekommt 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 müsst ihr 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 könnt ihr die Events und 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 kriegt ihr folgende Eigenschaften:

• id: unique Identifier des Events (braucht ihr 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 Helfende gibt, welche Einsätze übernommen haben, die nicht zu ihren Gruppen passten

HelperAssignements: Helfereinsätze eines Events

Mit diesem Service könnt ihr die Helferiensätze auf einem Event abfragen. Für diesen Event braucht ihr die ID des Events, den ihr abfragen wollt. Die ID kriegt ihr über den Events Endpoint.

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

Mit diesem Service bekommt ihr 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 diese/r Helfer/in für den Einsatz verantwortlich ist
• remarks: Bemerkungen für die Person, die 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 eine Person die Schicht schon übernommen hat, findest du hier die Eigenschaften dieser Person eingetragen.
• helpAsHelper: wenn die Person, die den Einsatz übernommen hat, diesen Einsatz für jemand anderes übernimmt, wird hier die Person eingetragen, die 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/e Helfer/in hat den Einsatz übernommen
• reserved: bei Double-Opt-in gilt der Einsatz als reserved, sobald ihn jemand ü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. Ihr findet sie oben beschrieben.

ACHTUNG: die Schichteigenschaften liegen auf jedem Einsatz. Wenn ihr einen Event mit 30 Einsätzen verteilt auf 3 Schichten à 10 Einsätze habt, 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 ihr mehr Informationen zum Helfer braucht, müsst ihr diese über den Helper Service abfragen!

stateCache Eigenschaften des Einsatzes

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