Klickarchive API
Zweck
der API
Der Zweck der API ist es, eine Möglichkeit zu
bieten, die aggregierten Klicks für (einen) Shop(s) für ein bestimmtes
Zeitintervall (Tag/Monat) zu exportieren und sie dem Benutzer für verschiedene
Zwecke zur Verfügung zu stellen.
Die Basis-URL lautet: https://partner.solute.de/
Einführung
Der FQDN (Full-Qualified
Domain Name) dieser API lautet: https://partner.solute.de/. Diese URL ist der
Grundbaustein für jeden API-Zugang.
Im Prinzip hat diese API 4 Endpunkte: Zur Authentifizierung und zum Abrufen
eines Tokens (/export/login).
- Authentifizierung und Abruf eines Tokens (/export/login).
- Abrufen eines Verzeichnisses mit Dateien eines Shops (/export/clickarchive/{shop_id})
- Zum Herunterladen von Clicklogs für ein bestimmtes Datum (/export/clickarchive/{shop_id}/{date}, wobei das Datum im Format JJJJ-mm-tt sein muss).
- und zum Herunterladen des Clicklogs für einen bestimmten Monat (/export/clickarchive_month/{shop_id}/{date}, Format des Datums: JJJJ-MM).
Authentifizierung
Grundsätzlich musst Du Dich zunächst authentifizieren
und ein Token generieren (dieses ist dann für ca. 1 Stunde gültig). Hierfür
wird der Endpunkt /export/login verwendet.
Hinweis: In den folgenden Beispielen werden die Abfragen über das Terminal und
curl durchgeführt.
curl -X POST https://partner.solute.de/export/login -H 'Content-Type: application/json' -d '{"username": "name", "password": "api_password"}'
Der obige Befehl setzt eine POST-Anfrage an die URL:
https://partner.solutre.de/export/login. Mit -H wird der
Anforderung ein Header hinzugefügt, in dem der erwartete Rückgabetyp angegeben
wird (Content-Type: application/json) und schließlich auch die Daten (-d),
anhand derer die Authentifizierung erfolgen soll.
Der Ergebniswert dieses Endpunkts ist ein Token und sollte wie folgt
aussehen:
{"token": "some cryptic chars", "shop_info": [{"shop_id": id_of_shop, "shop_name": "name_of_the_shop"}, ...]}Wiedererlangung von Clicklogs von anderen Endpunkten
Das im folgenden Schritt gezeigte Verfahren zum
Herunterladen von Daten ist generisch, d.h. es kann durch geringfügige
Anpassungen auch für die anderen Endpunkte verwendet werden.
Wenn Du diesen Token erhalten hast, hast Du den ersten Schritt erfolgreich
abgeschlossen.
Im Folgenden wird ein Clicklog für einen Beispielshop (mit der shop_id 1234) für ein bestimmtes Datum (22.01.2023)
heruntergeladen.
Dazu senden wir eine einfache GET-Anfrage an die folgende Adresse: https://partner.solute.de/export/clickarchive/1234/2023-01-22.
Der entsprechende curl-Befehl lautet:
curl -q -X GET https://partner.solute.de/export/clickarchive/1234/2023-01-22 -H 'Accept: application/json' -H 'Authorization: Bearer {token aus dem vorherigen schritt}' -o filename.json
Das gewünschte Format wird im Header (-H) angegeben (-H 'Accept: application/json') und auch das aus dem vorherigen Schritt generierte Token (-H 'Authorisation: Bearer {Token aus dem vorherigen Schritt}). Die Option -o gibt nur eine (zu erstellende) Datei an, in die die Daten geschrieben werden sollen. Es ist wichtig, dass das Format der Datei mit dem gewünschten Format (wie im Header definiert) übereinstimmt. In diesem Fall wollen wir die Daten in eine Datei vom Typ json schreiben.
Wenn alles gut gegangen ist, hast Du erfolgreich eine Datei von clickarchiveapi heruntergeladen.
Endpunkte
Derzeit verfügt die API über vier Endpunkte, einen zur Autorisierung, einen zum Extrahieren des Shop-Verzeichnisses und zwei zum Exportieren der Klick-Exporte für einen bestimmten Tag oder Monat. Die folgende Tabelle enthält eine kurze Beschreibung der jeweiligen Endpunkte.
| API-Methode | HTTP-Verb | url | Eingabe | Ergebnis | Fehlercodes |
|---|---|---|---|---|---|
| export_login | POST | /export/login | Benutzername und Passwort | Benutzername und Passwort | 400/401 |
| clickarchive | GET | /export/clickarchive/{shop_id} | Token (Shop-ID) | Token (Shop-id) | 400/401 |
| clickarchive_date | GET | /export/clickarchive/{shop_id} /{date} | Token/Format: csv oder json (ShopId/Datum im Format JJJJ-mmdd) | gzip-Datei mit CSV- oder json-Datei | 400/401/ 404/406/422 |
| get_clickarchive_for_month | GET | /export/clickarchive_month/ {shop_id}/{date} | Token/Format/Datum des Formats JJJJ-mm | gzip-Datei mit CSV- oder json-Datei | 400/401/ 404/406/422 |