Die ganze Kraft des Yoplanning-Ökosystems!
Einführung
Die Yoplanning API ist REST-basiert organisiert.
Unsere API hat vorhersagbare, ressourcenorientierte URLs und verwendet HTTP-Response-Codes, um API-Fehler und -Erfolge anzuzeigen.
Wir verwenden eingebaute HTTP-Features wie HTTP-Authentifizierung und HTTP-Verben, die von off-the-shelf HTTP-Clients verstanden werden.
JSON wird von allen API-Methoden zurückgegeben.
Authentifizierung
Zunächst einmal müssen Sie ein API-Token beantragen, um die Yoplanning API abfragen zu können. Um dies zu tun, kontaktieren Sie unsbitte
Sobald Sie Ihr Token in den Händen halten, können Sie mit der Arbeit mit der API beginnen. Alle API-Methoden erfordern eine Authentifizierung.
Wir verwenden ein standardmäßiges tokenbasiertes Authentifizierungssystem. Zur Authentifizierung geben Sie einfach Ihr API-Token im Header jeder Anfrage wie folgt an:
Authorization: Token 4804c2cb4d87a13146d4de029f407c82149f2ada
Be carefull: Der Abstand zwischen "Token" und dem Token ist wichtig.
Hier ist ein vollständiges Beispiel unter Verwendung von curl
1
2
3
4
5
6
curl -H "Content-Type: application/json " https://
yoplanning.pro/api/v3.1/teams/
5a90332e-568f-4980-9859-88a984844a4d/clients/8d23503e-041e-4180-98d1-641183bc5ead
-H 'Authorization: Token 4804c2cb4d87a13146d4de029f407c82149f2ada''.
Erlaubnisse
Wenn Sie Ihr API-Token beantragt haben, wurden Ihnen bestimmte Berechtigungen für einen bestimmten Satz von Teams eingeräumt.
Das bedeutet, dass Sie wahrscheinlich nicht alle unten aufgelisteten API-Methoden verwenden können.
Wenn Sie die Yoplanning API ohne Berechtigungen aufrufen (z. B. haben Sie nicht die Berechtigung, Sitzungsgruppen im Team zu erstellen), antwortet die API mit einem 403 HTTP-Code (Forbidden) mit den folgenden Details.
1
2
{« detail »: »You do not have permission to perform this action. »}
Throttling
Aus Sicherheitsgründen ist die Anzahl der Anfragen, die Sie durchführen können, begrenzt
Sie können bis zu 5 Anfragen/Sekunde und 1000 Anfragen/Tag senden.
Wenn Sie diese Rate überschreiten, antwortet der Server mit einem 429 HTTP-Code (Too Many Requests) mit den folgenden Details:
1
2
{« detail »: »Request was throttled. Expected available in 86368 seconds. »}
Übersicht
TEAM
The team is the most fondamental concept in yoplanning (which is a collaborative tool).
Almost all methods takes a teamId parameter in the url.
That means all the actions are relative to a team.
UUID
Lots of methods requires a “pk“ parameter in the url.
This is the unique identifier for the resource you are trying to retrieve / create / update / delete.
Yoplanning uses UUID (version 4) as unique identifier for all resources.
ENDPOINTS AND HTTP VERBS
For many ressources, 2 endpoints are available :
- one to access a specific instance.
The url basically ends with <pk>.
You can call these endpoints with the following http verbs :
● /api/v3.1/teams/<teamId>/clients/<pk>
GET : Retrieve the ressource
PUT : Update the ressource.
For many endpoints, this will also create the ressource if it does not exist
DELETE : Delete the ressource
- eine, um auf den Instanzenmanager zuzugreifen :
Sie rufen diese Endpunkte mit den folloing http-Verben auf :
● /api/v3.1/teams/<teamId>/clients
GET : get a list of all ressources (see Pagination)
POST : create a new ressource (The id will be generate by the server)
Nicht alle diese Aktionen sind für alle Endpunkte verfügbar.
Bitte informieren Sie sich in der Dokumentation des jeweiligen Endpunkts darüber, welche Methoden zulässig sind.
USING PUT PROPERLY
Wenn Sie eine Ressource aktualisieren wollen, sollten Sie immer den folgenden Workflow verwenden
1. Rufen Sie die Ressource mit einem GET-Antrag ab
2. Bearbeiten Sie die JSON-Daten
3. Senden Sie einen PUT-Request mit dem aktualisierten JSON.
Wenn Sie das nicht tun, kann es sein, dass die API Sie ablehnt, weil eine bestimmte nested ressource eine ID erfordert, die Sie nicht angeben.
Außerdem können Sie einige Daten verlieren.
ONLINE SELLING
Für den Zweck des Online-Verkaufs (Produktsuche und verfügbare Sitzungsgruppen) sollten nur 2 Endpunkte verwendet werden:
● /api/v3.1/teams/<teamId>/online-products/
● /api/v3.1/teams/<teamId>/online-products/<productId>/session-groups/
STORING YOUR ID
Es kann sinnvoll sein, auf jeder von Ihnen verwalteten Ressource eine eigene ID zu speichern, vor allem, wenn Sie Ihr System mit Yoplanning synchronisieren möchten.
Wenn es beispielsweise auf Ihrer Seite Probleme bei der Synchronisation gibt, können Sie mit diesen IDs Ressourcen auch dann wiederherstellen, wenn Sie die Yoplanning-ID verloren haben.
Daher können Sie Ihre ID in den externen_Referenzfeldern in vielen Ressourcen speichern (Kunde, Auftrag, Session_Gruppe, Session, Zahlung, ...)
Dies ist überhaupt nicht zwingend erforderlich.
Paginierung
Für alle API-Methoden, die eine große Liste von Ressourcen bereitstellen, wird Paginierung verwendet.
Das bedeutet, dass nicht alle Ergebnisse in einer einzigen Anfrage geliefert werden. Sie müssen mehrere Abfragen durchführen, um die vollständige Liste der Ressourcen zu erhalten
Sie können sich das wie "Seiten in einem Buch"vorstellen.
Für jede Anfrage können Sie in der Url Query-Parameter (Query-String) verwenden, um durch das Ergebnis zu navigieren.
Es können zwei Query-Parameter bereitgestellt werden: "offset" und "limit".
offset => der Startpunkt, von dem aus Sie Daten abrufen möchten (Sie können dies als Cursor sehen). Default: 0
limit => die Anzahl der Ergebnisse, die Sie pro Anfrage abrufen möchten. Standard: 100 (das ist auch der Höchstwert)
Hier ist ein vollständiges Beispiel unter Verwendung von curl
1
2
3
4
5
curl -H "Content-Type: application/json"
-L "https://yoplanning.pro/api/v3.1/teams/
5a90332e-568f-4980-9859-88a984844a4d/clients?
offset=20&limit=2" -H "Authorization: Token
4804c2cb4d87a13146d4de029f407c82149f2ada''.
Hier ist ein Beispiel einer Antwort für Methoden, die Paging verwenden:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
« count »:53,
« next »: »https://yoplanning.pro/api/v3.1/teams/
5a90332e-568f-4980-9859-88a984844a4d/clients?limit=2&offset=22 »,
« previous »: »https://yoplanning.pro/api/v3.1/
teams/5a90332e-568f-4980-9859-88a984844a4d/clients?
limit=2&offset=18 »,
« results »:[
{
« first_name » : « Jack »,
« last_name » : « Ichan »,
« email » : « jack.ichan@gmail.com »,
« phone_number » : « +32684952685 »,
« birth_date » : « 1975-05-22 »,
« language » : « fr »,
« note » : « Pretty cool client :) »,
« street » : « rue du phare »,
« city » : « Brest »,
« postal_code » : « 29200 »,
« state » : null,
« country » : « FR »
« id »: »7db70b5c-5175-4ba8-
b471-78006940b79c »
},
{
« first_name »: »Loic »,
« last_name »: »Lepoivre »,
« email »:null,
« phone_number »:null,
« birth_date »:null,
« language »:null,
« note »:null,
"street":null,
"city":null,
"postal_code":null,
"state":null,
"country":null,
"id":"669763dd-3bad-47a9-ac37-02d915a90bbe"
}
]
}
count => the total number of resources
next => the url to use to retrieve the next page. If
there is no next page, the value will be null.
previous => the url to use to retrieve the previous
page. If there is no previous page, the value will be
null.
results => the list of resources
Filter
Bei manchen Endpunkten können Sie die Ergebnisse filtern, indem Sie der Abfrage Query-Parameter hinzufügen.
Die folgende Abfrage liefert Ihnen nur die Kunden mit dem Erstnamen "Norbert".
https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/clients?offset=20&limit=2&first_name=Norbert
Für Datums- und Zahlenfelder können Sie mit __lt (lowet than), __gt (greater than), __lte (lowet than equal), __gte (greater than equal) filtern.
Die folgende Abfrage liefert Ihnen nur die Kunden mit einem Geburtsdatum größer als 1995-01-25.
https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/clients?offset=20&limit=2&birh_date__gt=1995-01-25
Welche Felder als Filter verwendet werden können, entnehmen Sie bitte der Endpunktdokumentation (filters allowed).
Expand Felder
Bei manchen Endpunkten enthält das Ressourcenobjekt geschachtelte Ressourcen.
Beispielsweise enthält eine Sitzung Mitarbeiter.
Whenyou retrieve this resource (using a GET request), you will only retrieve the nested resource ids (here, staffs ids).To avoid sending more requests, you can use the expand mechanism of the API to retrieve the full nested object
To do so, just append a query parameter in the url: " expand=" with the name of the nested resource you want to expand.
Die folgende Abfrage liefert Ihnen nur die Kunden mit einem Geburtsdatum, das größer als 1995-01-25 ist.
api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/payments/c21010f4-0e68-435b-b076-480087a49db1?expand=operator
Sie können eine Punktnotation verwenden, um tiefer in das Objekt einzudringen.
/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/orders?expand=items.voucher.product
Sie können auch mehrere geschachtelte Objekte mit Hilfe einer Koma-Notation expandieren
/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/orders?expand=items.voucher.product,payments.operator
Bitte beziehen Sie sich auf die jeweilige Endpunktdokumentation, um zu erfahren, welches Feld expendierbar ist.
Hinweis: Wenn Sie eine Instanz mit einer GET-Anfrage an einem Instanzendpunkt abrufen, kann es sein, dass einige geschachtelte Objekte standardmäßig expandiert werden. Diese Zwangsexpansion ist manchmal notwendig, damit Sie diese JSON in einer PUT-Anfrage bereitstellen können.
Wichtig: Wenn Sie eine Ressource abrufen möchten, um sie mit einer PUT-Anfrage zu aktualisieren, dürfen Sie den Expand-Mechanismus NICHT verwenden.
WebHook
Webhooks werden auch als "web callback" oder "HTTP push API" bezeichnet.
Es handelt sich um ein Benachrichtigungssystem
Sie können sich für Webhooks anmelden, um benachrichtigt zu werden, wenn ein bestimmtes Ereignis eintritt (z. B. jedes Mal, wenn ein Mandant angelegt wird).
Um sich anzumelden, setzen Sie sich bitte mit uns in Verbindung.
Wenn Sie sich für Wochenschauen anmelden, geben Sie uns eine Callback-URL und teilen Sie uns mit, bei welchem Ereignis und für welches Team Sie benachrichtigt werden möchten.
Wie funktioniert das?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
« resource »:
{ « id »: « 8d23503e-041e-4180-98d1-641183bc5ead »,
« type »: « client »
},
« link »: « https://yoplanning.pro/api/v3.1/teams/
5a90332e-568f-4980-9859-88a984844a4d/clients/
8d23503e-041e-4180-98d1-641183bc5ead »,
« event »: « updated »
}
resource.id => the resource that have been created /
modified / deleted
resource.type => the type of resource (client / session /
member, etc…)
link => the url to use to retrieve the resource.
event => the event fired
Wenn Sie eine POST-Anfrage auf der Callback-Url erhalten, können Sie eine GET-Anfrage an die Yoplanning API senden, indem Sie das Feld "link" verwenden, um die entsprechende Ressource abzurufen.
Vergessen Sie nicht, Authentifizierungsinformationen hinzuzufügen, wenn Sie die API aufrufen!
Wichtig: Wenn Sie einen Webhook erhalten, können Sie eine GET-Anfrage an die API senden, um die Änderungen abzurufen und Ihr System zu aktualisieren.
Senden Sie dann niemals eine PUT-Anfrage, da dies zu einer Endlosschleife führen könnte.
Errors
Yoplanning verwendet HTTP-Response-Statuscodes, um den Erfolg oder Misserfolg Ihrer API-Anfragen anzuzeigen.
Im Allgemeinen gibt es drei Statuscode-Bereiche, die Sie erwarten können:
●2xx success status codes confirm that your request worked as expected
● 4xx error status codes indicate an error because of the information provided (e.g., a required parameter was omitted)
● 5xx error status codes are rare and indicate an error with Yoplanning's servers. Sie können diesen Fehler in einigen seltenen Fällen immer noch erhalten, wenn die von Ihnen gelieferten Daten ungültig sind.
4xx Fehler enthalten einige Daten, die Ihnen helfen zu erkennen, was das Problem war.
Hier ist ein Beispiel:
1
{« price »:[« This field is required. »]}
Keys: Der Name der Felder, die einen ungültigen Wert haben
Value: Eine Liste von Strings, die die Fehler beschreiben, die diesem Feld entsprechen.
API-Referenzen
/api/v3.1/teams/
/api/v3.1/teams/
POST GET
Die Ressourcenbeschreibung und JSON finden Sie unter :
● /api/v3.1/teams/<teamId>/clients/<pk>
GET : Return all teams for which you have permissions.
See « Pagination » for more information about object list.
POST : Create a new team.
/api/v3.1/teams/<teamId>/online-products/
GET
Dieser Endpunkt wird verwendet, um alle Produkte zu erfassen, die online verkauft werden können.
Diese Ressource ist an die Bedürfnisse von Buchführungsmaschinen angepasst.
Wenn das von Ihnen angefragte Team ein Händler (Reseller) für andere Teams ist, erhalten Sie auch die Produkte dieser anderen Teams. In diesem Fall möchten Sie vielleicht filtern, um nur die Produkte eines bestimmten Teams abzurufen.
Query-Parameter :
Alle transalatablen Felder (wie Titel, Beschreibung usw.) werden in der Antwort übersetzt
Default: en
Erlaubte Filter :
Bsp: 302, team_id, last_modified__lt, last_modified__gt
Wenn Sie den last_modified-Filter verwenden möchten, geben Sie bitte eine UTC-Datumsangabe an.
Wenn Sie Zeitangaben machen, verwenden Sie bitte das folgende Format in der url:
"2019-05-23+10:53:00" (das + ist das Standard-Leerzeichen für Query-Strings).
● /api/v3.1/teams/<teamId>/online-products/
GET : retrieve all the products which can be sold online
Online Product object
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
{
« id »: »a47f7563-df65-4ced-b18a-14d79d004b0b »,
« title »: »Voile 3 jours »,
« last_modified »: »2018-06-03T18:30:00 »,
« description »: »Une super sortie voile »,
« private_session »: false,
« description_image »: »https://yoplanning.pro/
media/uploads/product/description/hd_Jpt8Wyv.jpg »,
« location »:{
« meeting_point »: »sur le quai »,
« address »: »44 route du moulin »
},
« participants »:{
« target »: »ALL », #Possible values :
« ALL », « CHILDREN », « ADULTS »
« expected_data »:[ #These are the data
that are expected for each participants (in addition to
their first_name and last_name) when creating a booking
{
« type »: »email », #possible value :
number, text, textarea, email, date, select
« label »: »Email », #The label to
display on the web page
« required »:false, #true if required,
false if optional
« field »: »email » #The name of the
field to send back to Yoplanning when creating a
booking
« options » : [« id » : « Weight »,
« name » : « Poids »] #only present for the
« select » type. « name » is translated and should ONLY
be use for display.
}
],
« level »: »ALL », #Possible values :
« ALL », « BEGINNER », « INTERMEDIATE », « ADVANCED »
"maximum":10 #The standard maximum
participant for a session of this product
},
"category":{
"id":304,
"name":"Bodyboard"
},
"sessions":{
"other_prices":[ #These are the special
prices like member
{
"label":"Child",
"price":{
"tax_excluded":"5.50",
"tax_included":"6.00"
}
}
],
"standard_price":{ #This is the
standard price of the product. Be carefull : this is
just an indication ! The real price is only accessible
in online-availabilities endpoint
"tax_excluded":"12.00",
"tax_included":"13.00"
}
},
"vouchers":{ #A voucher is a
ticket without date. You can sell at the following
price
"expiration":12,
"other_prices":[
{
"label":"Child",
"price":{
"tax_excluded":"40.50",
"tax_included":"49.00"
}
}
],
"standard_price":90.20
}
}
Tutorials
Hier sind einige Tutorials , die Ihnen bei Ihren Integrationen helfen:
Booking engine worflow: Wie man Ativities auf der Grundlage von Yoplanning API verkauft
