Version: 1.0
Erklärung für Nicht-Entwickler: Als Inhaber einer Tanz- oder Ballettschule betreiben Sie mit Sicherheit eine eigene Website. Mit der StudioIntern API ist es möglich, Daten aus StudioIntern direkt von oder zu dieser Website zu übertragen. Zum Beispiel können Sie auf diese Weise eine individuelle Lösung für die Einbindung des Kursplans auf Ihrer Website programmieren lassen (wenn Sie SI Web nicht verwenden wollen). Oder Sie übergeben die Angaben aus dem Kontaktformular, welches potentielle Kunden ausfüllen, an StudioIntern – dann müssen Sie es nicht selbst noch einmal eintippen.
Wenn Ihnen das alles zu kompliziert klingt, ignorieren Sie diese Seite einfach (sie ist ohnehin nur für Software-Entwickler von Interesse). Sie können StudioIntern selbstverständlich auch ohne API verwenden.
SI API DokDer Servername für die Endpoints ist immer https://api.studiointern.de/
.
https://api.studiointern.de/tanzhausXY
/v1/pub/courses.
Nach dem Studio-Hostnamen und vor dem eigentlichen Endpoint steht die Versionsnummer (aktuell immer v1
).
Studio-Hostname und Versionsnummer werden in dieser Dokumentation nicht immer mit aufgeführt.
Die API kennt 3 Bereiche:
Für den Bereich /pub
muss ein Header wie folgt gesetzt werden:
Authorization: [API-Key]
Der API-Key ist im Kundenprofil von StudioIntern.de einsehbar, sofern man mit der Rolle »Geschäftsleitung« eingeloggt ist.
Für alle Endpoints des Bereichs cust
ist anstelle des API-Keys eine Basic-Authentifizierung erforderlich:
Authorization: Basic [User-Auth]
Dabei folgt [User-Auth]
dem bekannten Schema der Basic-Authentifizierung:
base64_encode('[Kundennummer]:[Passwort]')
Die [Kundennummer] ist die vom Studiobetreiber vergebene offizielle Kundennummer, nicht die interne Datenbank-ID.
Das [Passwort] wird ebenfalls vom Studiobetreiber initial erzeugt und dem Kunden mitgeteilt.
Für den POST-Endpoint /cust/user ist zusätzlich die E-Mail-Adresse als Parameter erforderlich.
Alle Daten, die von den Endpoints zurückgegeben werden, sind immer in ein Response-Objekt eingebettet. Dieses hat die folgende Struktur:
class ApiPlainObject { public $message = "OK"; public $code = 0; }
Die angeforderten »Nutzdaten« befinden sich dann in zusätzlichen Properties (z.B. »courses«), die diesem Basisobjekt hinzugefügt werden.
Die Property message
enthält einen String »OK« oder eine kurze Fehlerbeschreibung; die Property code
den Rückgabe-Code des
Endpoints. Der Rückgabecode 0 bedeutet: kein Fehler.
Path | Operation | Description |
---|---|---|
/cust/courses | GET |
Liste der von diesem Benutzer (bzw. dessen Schüler) belegten Kurse. Liefert ein Array mit den IDs der Kurse. Falls als Parameter die ID eines Schülers übergeben wird, enthält die Antwort die Kurse nur dieses Schülers, sonst aller Schüler des Benutzers. |
/cust/user | GET |
Verschiedene Informationen über den Benutzer (Kundennummer, Vorname, Nachname, E-Mail, Status, zugeordnete Schüler) |
POST
Sollte PUT (Update) sein, aber aus bestimmten Gründen wird POST verwendet. |
Passwort des Benutzers ändern. Bei leerem neuen Passwort wird das Login gelöscht! |
|
/pub/courses | GET |
Liste aller Kurse, die vom Studio angeboten werden. Deaktivierte Kurse (die nicht stattfinden) werden nicht mit geliefert. |
/pub/studio | GET |
Informationen über das Studio. |
/pub/schedule | GET |
Den öffentlichen Kursplan erhalten |
/pub/user | POST |
Einen neuen Kunden anlegen |
Liefert alle Kursbelegungen für alle Schüler eines Benutzers oder – wenn eine Schüler-ID als Parameter übergeben wurde – für einen bestimmten Schüler eines Benutzers.
Authorization |
Basic User-Auth |
header | object | |
sid | Schüler-ID | Query | integer |
Anfrage wurde fehlerfrei bearbeitet
Kein Fehler, aber die Anfrage lieferte kein Ergebnis
Fehlender Authorisierungs-Header oder Username/Passwort falsch
Endpoint existiert nicht / falsche Anfrage-URL
oder angefragtes Objekt nicht gefunden (Benutzer, Schüler, Kurs...)
Die Anfrage-Methode (GET, POST) ist für diesen Endpoint nicht zulässig.
Übergebene Parameter sind ungültig, vom falschen Typ oder außerhalb des gültigen Wertebereichs.
Internal Server Error
Alle Response-Bodies haben immer das allgemeine Response-Objekt als Wrapper. Die nachfolgende Tabelle beschreibt nur die für diesen Endpoint spezifischen Properties dieses Response-Objekts.
Property | Beschreibung | Schema | Beispiel |
---|---|---|---|
classes | Array von Kurs-IDs | Array[int] |
"classes": ["2","5","45"] |
UserAuth |
Einige Infos über den User, der anhand der Basic-Authentifizierung (im Header) erkannt wurde.
Authorization |
Basic User-Auth |
header | string |
Anfrage wurde fehlerfrei bearbeitet
Kein Fehler, aber die Anfrage lieferte kein Ergebnis
Fehlender Authorisierungs-Header oder Username/Passwort falsch
Endpoint existiert nicht / falsche Anfrage-URL
oder angefragtes Objekt nicht gefunden (Benutzer, Schüler, Kurs...)
Die Anfrage-Methode (GET, POST) ist für diesen Endpoint nicht zulässig.
Internal Server Error
Alle Response-Bodies haben immer das allgemeine Response-Objekt als Wrapper. Die nachfolgende Tabelle beschreibt nur die für diesen Endpoint spezifischen Properties dieses Response-Objekts.
Property | Beschreibung | Schema | Beispiel |
---|---|---|---|
user | Objekt | { id:integer, firstName:string, lastname:string, email:string, active:boolean, students:Array[object] } |
"user": { "id": "12345", "firstName": "Monika", "lastName": "Muster", "email": "moni@muster.de", "active": true, "students": [ { "id": 43, "firstName": "Monika", "lastName": "Muster", "dayOfBirth": "1974-02-27", "email": "" }, { "id": 44, "firstName": "Lisa", "lastName": "Muster", "dayOfBirth": "2016-10-17", "email": "lisa16@web.de" } ] } |
UserAuth |
Passwort des Benutzers ändern. Vorsicht: Ein leeres neues Passwort löscht das Login komplett!
Nach erfolgreichem Update muss der User-Auth-String geändert werden.
Authorization |
Basic User-Auth |
header | string | |
new_password |
neues Passwort |
query | string | erforderlich |
new_password2 |
neues Passwort, Kontrolleingabe |
query | string | erforderlich |
E-Mail-Adresse des Benutzers |
query | string | erforderlich (als zusätzliche Sicherheitsstufe) |
Anfrage wurde fehlerfrei bearbeitet
Kein Fehler, aber die Anfrage lieferte kein Ergebnis
Fehlender Authorisierungs-Header oder Username/Passwort falsch
Endpoint existiert nicht / falsche Anfrage-URL
oder angefragtes Objekt nicht gefunden (Benutzer, Schüler, Kurs...)
Die Anfrage-Methode ist für diesen Endpoint nicht zulässig.
Wird zurückgegeben, wenn neues Passwort nicht mit der Kontrolleingabe übereinstimmt.
Zu wenige oder ungültige Parameter.
Internal Server Error
Keiner.
UserAuth |
Alle derzeit aktiven Kurse des Studios als Liste von Objekten erhalten. Authentifizierung über API-Key im Header.
Im Unterschied zu /pub/schedule werden nur die Kurse selbst geliefert, aber keine Information, wann diese stattfinden.
Authorization |
Api-Key |
header | string |
Anfrage wurde fehlerfrei bearbeitet
Kein Fehler, aber die Anfrage lieferte kein Ergebnis
Fehlender Authorisierungs-Header
Endpoint existiert nicht / falsche Anfrage-URL
Die Anfrage-Methode ist für diesen Endpoint nicht zulässig.
Internal Server Error
Alle Response-Bodies haben immer das allgemeine Response-Objekt als Wrapper. Die nachfolgende Tabelle beschreibt nur die für diesen Endpoint spezifischen Properties dieses Response-Objekts.
Property | Beschreibung | Schema | Beispiel |
---|---|---|---|
courses | Array von Objekten | Array[Object] |
"courses": [ { "id": "1", "kurzwort": "Ballett 1", "bezeichnung": "Ballett Anfänger Erwachsene", "stunden": "1" }, { "id": "2", "kurzwort": "Modern 2", "bezeichnung": "Moderner Tanz Mittelstufe", "stunden": "1.5" }, { "id": "3", "kurzwort": "Kindertanz", "bezeichnung": "Kreativer Kindertanz ab 4 Jahre", "stunden": "0.75" }, ... ] |
Informationen über das Studio erhalten. Authentifizierung über API-Key im Header.
Authorization |
Api-Key |
header | string |
Anfrage wurde fehlerfrei bearbeitet
Kein Fehler, aber die Anfrage lieferte kein Ergebnis
Fehlender Authorisierungs-Header
Endpoint existiert nicht / falsche Anfrage-URL
Die Anfrage-Methode ist für diesen Endpoint nicht zulässig.
Internal Server Error
Alle Response-Bodies haben immer das allgemeine Response-Objekt als Wrapper. Die nachfolgende Tabelle beschreibt nur die für diesen Endpoint spezifischen Properties dieses Response-Objekts.
Property | Beschreibung | Schema | Beispiel |
---|---|---|---|
signature | Signatur des Studios für die Verwendung in E-Mails. | String |
StudioIntern – Die clevere Lösung für Ballett- und Tanzschulen Software-Entwicklung Andreas Vent-Schmidt,Kieselbach 7c, 04746 Hartha St.Nr. 232/284/14778 | +49 34321 63 59 62 www.studiointern.de |
Den Stunden- bzw. Kursplan für einen bestimmten Zeitraum erhalten. Authentifizierung über API-Key im Header.
Authorization |
Api-Key |
header | string | |
period |
Zeitraum, für den der Plan ausgegeben werden soll: "today", "week" oder "weekofdate" week: der Plan für die aktuelle Woche weekofdate: der Plan für die Woche, in die das übergebene Datum fällt today: der Plan für den aktuellen Tag |
query | string | default: today |
date |
Datum im SQL-Format, für dessen Woche der Plan ausgegeben werden soll. |
query | string | nur bei period=weekofdate erforderlich |
Für die meisten Installationen von StudioIntern liefern week und weekofdate dasselbe Ergebnis. Genauer gesagt, ist bei den meisten Schulen der Kursplan für jede Woche identisch, aber nicht für alle. Das Verhalten hängt davon ab, ob das Studio die SI-Version mit fortlaufendem Kalender gebucht hat oder nicht (Standard: nein). |
Anfrage wurde fehlerfrei bearbeitet
Kein Fehler, aber die Anfrage lieferte kein Ergebnis
Fehlender Authorisierungs-Header
Endpoint existiert nicht / falsche Anfrage-URL
Die Anfrage-Methode ist für diesen Endpoint nicht zulässig.
Zu wenige oder ungültige Parameter. Z.B. fehlender date
-Parameter, wenn für period
der
Wert »weekofdate« angegeben wurde. Fehlercode erscheint auch bei falsch formatiertem date
-Parameter.
Internal Server Error
Alle Response-Bodies haben immer das allgemeine Response-Objekt als Wrapper. Die nachfolgende Tabelle beschreibt nur die für diesen Endpoint spezifischen Properties dieses Response-Objekts.
Property | Beschreibung | Schema | Beispiel |
---|---|---|---|
events | Array von Objekten | Array[Object] |
"events": [ { "id": "23", "dow": "Montag", "dow_short": "Mo", "date": "2021-07-12", "start_time": "15:00:00", "end_time": "15:55:00", "title": "KiBall 2", "description": "Kinderballett Grade 2", "teacher": "Susanne", "extra": "mit Vorkenntnissen", "raum": "Studio 2", "more_info": "", "hours": "1.5", "color": "#33ff66" }, { "id": "12", "dow": "Montag", "dow_short": "Mo", "date": "2021-07-12", "start_time": "16:00:00", "end_time": "16:45:00", "title": "KiTanz 1", "description": "Kreativer Kindertanz", "teacher": "Linda", "extra": "ab 4 Jahre", "raum": "Studio 2", "more_info": "", "hours": "0.75", "color": "#ff3366" }, { "id": "76", "dow": "Montag", "dow_short": "Mo", "date": "2021-07-12", "start_time": "17:00:00", "end_time": "18:30:00", "title": "Modern E3", "description": "Modern Erwachsene, Level 3", "teacher": "Heidi", "extra": "ab 4 Jahre", "raum": "Saal 1", "more_info": "NEU!", "hours": "1.5", "color": "#FCCCDD" }, ... ] |
Der genaue Inhalt der Felder »title«, »description« und »extra« hängt von einer individuelle Voreinstellung ab (»Beschreibungs-Feld der Kurse im Kursplan anzeigen?«). | |||
Das Feldes »more_info« enthält das, was im Planungstool im Feld »Bemerkungen« für den Kurs eingegeben wurde. |
Einen neuen Kunden anlegen
Authorization |
Api-Key required |
header | string | |
anrede |
Anrede |
query | string [Frau|Herr] | |
titel |
Akademischer Titel (z.B. »Dr.«) des Kunden |
query | string | optional |
vorname |
Vorname des Kunden |
query | string | |
nachname |
Nachname des Kunden |
query | string | |
adresse |
Adresse (Straße, Nr.) des Kunden |
query | string | optional |
adresszusatz |
Adresszusatz (z.B. »Seitenflügel«) des Kunden |
query | string | optional |
plz |
Adresse (PLZ) des Kunden |
query | string | optional |
ort |
Adresse (Ort) des Kunden |
query | string | optional |
telefon |
Telefonnummer (Festnetz) des Kunden |
query | string | optional |
mobil |
Telefonnummer (Mobil) des Kunden |
query | string | optional |
E-Mail-Adresse des Kunden |
query | string | ||
bemerkungen |
Bemerkungen zum Kunden |
query | string | optional, seit Version 0.9 |
sch_vorname |
Vorname des Schülers |
query | string | optional |
sch_nachname |
Nachname des Schülers |
query | string | optional |
sch_geb_tag |
Geburtsdatum des Schülers, Tag |
query | string | optional |
sch_geb_monat |
Geburtsdatum des Schülers, Monat |
query | string | optional |
sch_geb_jahr |
Geburtsdatum des Schülers, Jahr |
query | string | optional |
Statt der 3 Einzelfelder für Tag, Monat und Jahr kann seit Version 0.9 auch das Geburtsdatum
in einem Wert übertragen werden. Es muss dabei der kontinentaleuropäischen Schreibweise tt.mm.yyyy
folgen. Anderenfalls wird das Datum ignoriert.
| ||||
sch_geb |
Geburtsdatum des Schülers als Komplett-String |
query | string | optional, alternativ zu sch_geb_tag, sch_geb_monat und sch_geb_jahr |
Um mehrere Schüler für einen Kunden anzulegen, rufen Sie entweder
den Endpoint mit denselben
Kundendaten, aber verschiedenen Schülerdaten mehrfach auf, oder Sie übertragen
mehrere Schüler, indem Sie alle sch_* Felder mit Array-Notation [] übertragen:...&sch_vorname[]=Peter&sch_vorname[]=Susi&sch_vorname[]=Leni...
Existierende Kundendaten werden niemals überschrieben. |
Der neue Benutzer wurde angelegt.
Anfrage kann mit diesen Parameter-Werten nicht ausgeführt werden. Die Ursache ist meist ein bereits existierender Benutzer
mit denselben primary oder unique keys. Prüfen Sie die message
-Property im Response-Objekt für weitere Informationen.
Fehlender Authorisierungs-Header
Die Anfrage-Methode ist für diesen Endpoint nicht zulässig.
Zu wenige oder ungültige Parameter.
Internal Server Error
Es wird nur das allgemeine Response-Objekt mit den Properties code
und message
zurückgegeben.