Tredict Partner API - Dokumentation - Tredict

Die Partner-API ist für Unternehmen gedacht, die ihre Nutzer bei Tredict registrieren möchten, um ihnen Trainingspläne und Tredict-Schreibrechte zuzuweisen. Unternehmen verwalten ihr eigenes Abrechnungssystem, integrieren aber Tredict für die Verteilung der Trainingspläne.

Kontakt

Bei Interesse an der Partner-API schreibe uns eine Email und wir werden alles Nötige in die Wege leiten und Dir einen Zugang zuweisen.

partner@tredict.com

Onboarding von Athleten

Das Athleten-Onboarding ermöglicht Dir, als Partner, Benutzer auf das Tredict-Benutzer-Registrierungsformular zu leiten und den Benutzer auf sichere und datenschutzkonforme Weise automatisch mit Deinem Tredict-Partner-Account zu verknüpfen. Alternativ können auch bestehende Benutzer-Accounts mit dem Partner-Account verknüpft werden.

Wenn der Benutzer mit dem Partner-Account verknüpft ist, hat dieser die Berechtigung zu den Trainingsplänen des Partners und bekommt automatisch monatlichen Tredict-Schreibzugriff zugewiesen, den Tredict über den Partner abrechnet.

Verfahren

Die Registrierung eines neuen Tredict-Benutzers durch den Partner-Account wird durch einen 2-Wege-Handshake durchgeführt.

Der Partner fordert, an der API für die Benutzerregistrierung, einen privaten und öffentlichen Code an, welche auf Partnerseite im Backend vorgehalten werden. Dann wird das Tredict-Benutzer-Registrierungsformular mit dem öffentlichen Code aufgerufen. Bei erfolgter Registrierung durch den Benutzer leitet Tredict dann auf eine Landingpage des Partner zurück und übergibt den privaten Code und die Identifikationsnummer des neu oder bereits registrierten Benutzers als Parameter. Der Partner kann nun den privaten Code abgleichen, seinem Athleten zuordnen und die Tredict-Benutzeridentifikationsnummer speichern.

Vorteile des 2-Wege-Handshake-Verfahrens:

Der Partner hat keine Kenntnis über die Zugangsdaten des Benutzers.

Die DSGVO-Konformität ist durch Tredict gewährleistet. Es braucht kein Vertrag zur Auftragsdatenverarbeitung zwischen dem Partner und Tredict geschlossen werden. Der Partner braucht keine zusätzlichen Sicherheitsvorkehrungen treffen.

Es wird das Registrierungsformular auf der Tredict-Webseite verwendet.

Alle Validierungsschritte wie Passwortsicherheit oder die Zustimmung zu den Tredict-Nutzungs- und Datenschutzbestimmung finden bei Tredict statt.

Schutz vor fehlerhaften oder absichtlich schadhaften Prozessen.

Bei Entwendung der Partner-API-Zugangsdaten wird es Angreifern erschwert schadhafte automatisierte Aktionen vorzunehmen, da durch den Handshake ein menschlicher Faktor eingebunden ist.

Ablauf

Generiere die Handshake-Codes mit dem Aufruf von init-register-handshake und speichere die Antwort auf Deinem Server.
Leite den Athleten auf das Tredict-Registrierungsformular und übergebe den empfangenen registerCode als Parameter.

https://staging.tredict.de/registrieren/?registerCode=vrQc4sFaJGbpoga4AjuanC

Wenn der Benutzer noch nicht registriert ist, dann wird ihm nun das Registrierungsformular angezeigt. Falls der Benutzer registriert und eingeloggt ist, wird dieser gefragt, ob er sich nun mit dem Partner-Account verknüpfen möchte.
Bei erfolgreicher Registrierung wird Deine Landingpage aufgerufen, die Du bei der Registrierung Deines Partner-Accounts angegeben hast. Dabei wird der authorizationCode als Parameter übermittelt, den Du bei der Initialisierung des Handshakes gespeichert hast. Vergleiche den Code nun, ob er übereinstimmt. Wenn nicht, dann handelt es sich nicht um eine autorisierte Antwort! Als zweiter Parameter wird die userId des Tredict-Benutzers übergeben. Speichere diese ab. Du brauchst diese, um die Verbindung zum Benutzer-Account zu aktivieren oder zu entfernen.

Bei einer erfolgreichen Verbindung wird Deine Landingpage mit diesen Parameter aufgerufen:
https://www.deinelandingpage.de/hallo-benutzer/?authorizationCode=9WXeX4kUBQrMrHHoTAKSAn&userId=aEen1VF4

Bei einem unvorhergesehen Fehler wird die Landingpage mit einem error-Parameter aufgerufen:
https://www.deinelandingpage.de/hallo-benutzer/?error=could_not_connect_athlete_to_partner&userId=aEen1VF4
Aktiviere den Benutzer mit activate-user, damit dieser automatisch Schreibzugriff zugewiesen bekommt und auf die Deine Trainingspläne zugreifen kann. Der monatlich automatisch zugewiesene Schreibzugriff wird dem Partner-Account unter den verhandelten Bedingungen in Rechnung gestellt.

Endpunkte

Bei jeder Anfrage an einen Endpunkt muss der Authorization-Header gesetzt sein, dem Du die Partner-Client-Credentials übergibts. Diese erhälst Du von uns.

Die Credentials setzten sich mit einem Doppelpunkt aus clientId und clientSecret zusammen und werden dann mit Base64 encodiert.

Beispiel-Request:

Node.js


const base64_partner_credentials = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");

const response = await fetch(`https://staging.tredict.de/user/partner/init-register-handshake`, {
  headers: {
    'Authorization': `Basic ${base64_partner_credentials}`,
  },
});

const handshake_codes = response.json();

PHP WordPress


$response = wp_remote_request(
  'https://staging.tredict.de/user/partner/init-register-handshake',
  array(
    'method'  => 'GET',
    'headers' => array(
      'Authorization' => 'Basic ' . base64_encode( $clientId . ':' . $clientSecret )
    ),
  )
);

echo wp_remote_retrieve_body( $response );

Benutzer registrieren - Handshake-Codes generieren

GET https://staging.tredict.de/user/partner/init-register-handshake

Request headers:

Authorization: Basic ${base64_partner_credentials}
Accept: application/json;charset=UTF-8

Response JSON object entries:

registerCode: Dieser Code muss als Parameter an das Tredict-Benutzerregistrierungsformular übergeben werden.
authorizationCode: Dieser Code wird als Parameter an die Partner-Landingpage zurückgegeben, nachdem sich der Benutzer erfolgreich registriert hat.
expiresAt: Ablauf des Codepaares als ISO-Datum-Zeichenkette. Das Codepaar hat eine Gültigkeit von einer Stunde.

Response JSON example:

{
  "registerCode": "vrQc4sFaJGbpoga4AjuanC",
  "authorizationCode": "9WXeX4kUBQrMrHHoTAKSAn",
  "expiresAt": "2023-12-29T15:30:39.008Z",
}

Status return codes:

200: Request could be processed successfully.
401: Invalid authorization header.
429: Too many requests.
500: Something went wrong on our side.
503: Sorry, we went to the pub.

Benutzer aktivieren

Durch das Aktivieren des Benutzer wird diesem automatisch monatlicher Schreibzugriff zugewiesen und hat Zugriff auf alle Trainingspläne des Partner-Accounts. Die Aktivierung muss nach einer Neuregistrierung und dem Abgleich des authorizationCode durchgeführt werden. Der zugewiesene Schreibzugriff wird unter den verhandelten Bedingungen in Rechnung gestellt.

GET https://staging.tredict.de/user/partner/activate-user/${userId}

Request headers:

Authorization: Basic ${base64_partner_credentials}

Request path parameter:

userId: Die Benutzeridentifikationsnummer des zu aktivierenden Benutzers. Diese wurde bei der Registrierung des Benutzers übergeben.

Status return codes:

200: Request could be processed successfully. User got activated.
400: Bad parameter given.
401: Invalid authorization header.
403: No handshake was executed.
404: User could not be found.
429: Too many requests.
500: Something went wrong on our side.
503: Sorry, we went to the pub.

Benutzer entfernen

Die Verbindung des Benutzer-Accounts zum Partner wird komplett entfernt. Es wird kein Schreibzugriff mehr über den Partner-Account abgerechnet und zugewiesen. Um den Benutzer erneut zu verbinden, muss das Onboarding erneut durchgeführt werden.

DELETE https://staging.tredict.de/user/partner/remove-user/${userId}

Request headers:

Authorization: Basic ${base64_partner_credentials}

Request path parameter:

userId: Die Benutzeridentifikationsnummer des zu entfernenden Benutzers. Diese wurde bei der Registrierung des Benutzers übergeben.

Status return codes:

200: Request could be processed successfully. User got disconnected.
400: Bad parameter given.
401: Invalid authorization header.
404: User could not be found or is already removed.
429: Too many requests.
500: Something went wrong on our side.
503: Sorry, we went to the pub.

Benutzer-Ereignisliste anzeigen

Liefert eine Objekt aller Benutzer zurück, die mit dem Partner-Account verbunden sind oder waren.

GET https://staging.tredict.de/user/partner/event-list

Request headers:

Authorization: Basic ${base64_partner_credentials}

Response JSON example:

{
  "j6rJEmsr8": {
    "activationDates": [ "2024-01-03T19:21:40.857Z" ],
    "assignments": [{
      "months": 1,
      "assignedAt": "2024-01-03T19:21:41.857Z"
    }]
  },
  "RVQmMnmi7": {
    "activationDates": [ "2024-01-03T19:21:45.393Z" ],
    "removalDates": [ "2024-01-06T20:21:45.480Z" ],
    "assignments": [{
      "months": 1,
      "assignedAt": "2024-01-03T19:21:41.857Z"
    }, {
      "months": 1,
      "assignedAt": "2024-01-04T19:21:41.857Z"
    }]
  }
}

Status return codes:

200: Request could be processed successfully.
401: Invalid authorization header.
429: Too many requests.
500: Something went wrong on our side.
503: Sorry, we went to the pub.