Kunden-Registrierung

Anleitung zum Entwickeln eines Kundenbereichs auf der Webseite

Die API von Propstack kann dabei helfen, einen Kundenbereich für Interessenten oder Eigentümer auf der eigenen Homepage zu entwickeln. Propstack bietet dafür mehrere API-Endpoints an um einen Registrierungsprozess abzubilden.

Da Propstack keine E-Mails verschickt oder Landing Pages für die Registrierung anbietet, ist immer noch viel Entwicklungsaufwand seitens der Homepage nötig.

Registrierungsprozess

Registrierungsformular

Zum Erstellen eines neuen Kundenkontos würde es ein Formular auf der Homepage geben, in der man mindestens eine E-Mailadresse und Passwort eingibt, meistens aber noch einen Vor- und Nachnamen.

Beispiel-Registrierungsformular

Beim Registrieren wird ein neuer Kontakt in Propstack angelegt, bzw. ein vorhandener Kontakt (anhand der angegebenen E-Mail-Adresse) gefunden und ein Kundenkonto angelegt.

Wenn dieses Formular abgeschickt wird, werden die Daten an Propstack übertragen, an folgenden API-Endpoint:

POST /v1/contacts/register

{
  "client": {
    "email": "[e-mail]",
    "password": "12345678",
    "password_confirmation": "12345678",
    "first_name": "Foo",
    "last_name": "Bar",
    "salutation": "mr"
  }
}

Als Antwort von propstack wird ein Token geliefert, welcher für den Double Opt-In verwendet wird:

{
  "confirmation_token": "abc"
}

Bestätigen des Kundenkontos

Das Kundenkonto wurde angelegt, muss aber noch bestätigt werden (Double Opt-In). Dafür schickt man dem Kunden eine E-Mail, zum Bestätigen des angelegten Kundenkontos.

In der E-Mail muss sich ein Link/Button befinden, den der Kunde anklicken muss, damit die Bestätigung ausgelöst wird. Die URL hinter dem Link muss den Token aus dem letzten Schritt beinhalten. Die URL könnte in etwa so aussehen:

https://www.meine-immobilien.de/confirm/abc

Wenn der Kunde diese URL aufgerufen hat, würde die Homepage den Token (abc) aus der URL auslesen und damit einen API-Request an Propstack machen:

POST /v1/contacts/confirm

{
  "confirmation_token": "abc"
}

Propstack bestätigt dann bei sich das Kundenkonto für den Kontakt, damit er sich zukünftig anmelden kann. Als Antwort erhält man von Propstack die ID und den Namen des Kontaktes:

{
  "client": {
    "id": 123,
    "name": "Foo Bar"
  }
}

Einloggen in den Kundenbereich

Das eigentliche Einloggen muss die Webseite mit Hilfe von z.B. Cookies lösen. In einem Cookie würde man mindestens die Propstack-ID des Kontaktes (im oberen Beispiel die 123) oder ein ganzes JSON abspeichern.

Zur Sicherheit sollte aber auf jeden Fall die Infos in dem Cookie verschlüsselt sein und nicht einfach die Kontakt-ID als Klartext stehen! Um die Daten sicher in Cookies zu speichern, ist die Nutzung von JWT empfehlenswert.

Nach dem Bestätigen des Kundenkontos kann man die Response von Propstack nehmen und zum Einloggen nutzen.

Wenn ein Kunde bereits ein Kundenkonto hat und sich nun anmelden möchte, gibt es einen Endpoint zum Verifizieren der E-Mail-Adresse und des Passworts:

POST /v1/contacts/login

{
  "credentials": {
    "email": "[e-mail]",
    "password": "12345678"
  }
}

Wenn die Login-Daten stimmen, erhält man die gleiche Antwort wie nach dem Double Opt-In, welche man wieder zu Erstellen eines Cookies verwenden würde:

{
  "client": {
    "id": 123,
    "name": "Foo Bar"
  }
}

Passwort zurücksetzen

Es kann durchaus passieren, dass ein Kunde sein Passwort für den Kundenbereich vergessen hat. Deshalb gibt es über die API auch die Möglichkeit das Passwort für einen Kunden zurücksetzen zu können.

Dafür muss die Homepage zunächst wieder ein Formular anbieten, in der man nur eine E-Mail-Adresse angeben muss

POST /v1/contacts/send_password_reset

{
  "email": "[e-mail]"
}

Wenn ein Kontakt mit der angegebenen E-Mail-Adresse gefunden wird, beginnt der Prozess zum Zurücksetzen des Passworts. In der Antwort befindet sich dafür ein Token, um später das Vergeben eines neuen Passworts zu verifizieren:

{
  "token": "xyz"
}

Dieser Token wird ähnlich wie beim Double Opt-In verwendet, um eine E-Mail an den Kunden zu senden, mit einem Link, der diesen Token in der URL beinhaltet, z.B.:

https://www.meine-immobilien.de/reset-password/xyz

Beispiel-Formular zum Vergeben eines neuen Passworts

Auf dieser Seite, die von der Homepage bereitgestellt wird, sollte sich ein kleines Formular befinden, in der der Kontakt ein neues Passwort vergeben kann.

Das neue Passwort wird dann zusammen mit dem Token aus der vorherigen URL an Propstack mitgeschickt, damit Propstack das Passwort für den Kontakt aktualisiert:

POST /v1/contats/xyz/reset_password

{
  "client": {
    "password": "87654321",
    "password_confirmation": "87654321"
  }
}

Wenn die Aktualisierung des Passworts erfolgreich war, erhält man wieder die gleiche Antwort wie bei einem Login, welche man nutzen kann, um den Kontakt direkt anzumelden ohne noch mal die Zugangsdaten eingeben zu müssen.

{
  "client": {
    "id": 123,
    "name": "Foo Bar"
  }
}

Zusammenfassung

Mit Hilfe von 2 Endpoints kann man ein neues Kundenkonto erstellen und bestätigen. Es gibt einen Endpoint zum Anmelden in ein Kundenkonto. Für das Zurücksetzen eines Passworts gibt es ebenfalls 2 Endpoints

Propstack bietet keine Formulare zum Registrieren/Anmelden an, und verschickt auch keine E-Mails zum Double Opt-In oder Zurücksetzen des Passworts; das man auf der Homepage selber entwickeln. So hat man komplette Freiheit was das Design der E-Mails und der Formulare angeht.