Policenwerk Kunden- und Maklerportal

API - Kunden erstellen

Sie senden Ihre Kunden-Daten an unsere API und wir erstellen Ihnen diesen Kunden in unserem System.

Die API ist für die Erstellung von Kunden gedacht, die Sie in unserem System anlegen möchten.
Die API prüft die übermittelten Daten auf Vollständigkeit und Gültigkeit.
Bei erfolgreicher Erstellung erhalten Sie eine Bestätigung mit der Kunden-ID zurück.
Bei Fehlern in den übermittelten Daten erhalten Sie eine Fehlermeldung mit den entsprechenden Hinweisen.

Technische Anforderungen an die API-Kommunikation

Domain Live: login.policenwerk.de
Domain für Testzwecke: test.policenwerk.de
Endpunkt: /api/customer/create
Authentifizierung: Siehe API Authentifizierung

Alle Anfragen werden als HTTP-POST übertragen.
Das Datenformat für Anfragen und Antworten ist stets application/json.
Die API ist ausschließlich über HTTPS erreichbar.
Es müssen immer alle Felder angegeben werden, auch wenn diese nur Optional sind. Falls bei Optionalen Felder kein Wert vorhanden ist, diesen einfach leer lassen.
Die SSL/TLS-Verschlüsselung der Server kann über SSL Labs unabhängig überprüft werden: SSL Labs (Analyse login.policenwerk.de).

Kunden-Daten

Feldname	Datentyp	Beschreibung	Notwendigkeit
anrede	integer `tinyint(3)`	Anrede (siehe Vordefinierte Werte) `2`	Optional
titel	integer `tinyint(3)`	Titel (siehe Vordefinierte Werte) `4`	Optional
vorname	string `varchar(100)`	Vorname des Kunden `Max`	Pflichtfeld
nachname	string `varchar(100)`	Nachname des Kunden `Mustermann`	Pflichtfeld
geburtstag	date `YYYY-MM-DD`	Geburtstag des Kunden `1980-05-21`	Pflichtfeld
strasse	string `varchar(150)`	Strasse `Max-Muster-Weg`	Pflichtfeld
hausnr	string `varchar(10)`	Hausnummer `10b`	Pflichtfeld
plz	string `varchar(10)`	Postleitzahl `12345`	Pflichtfeld
ort	string `varchar(100)`	Wohnort `Musterstadt`	Pflichtfeld
land	integer `tinyint(3) unsigned`	Länderkennzeichen; erlaubte Werte: 1=DE, 2=AT, 3=CH. Kunden aus anderen Ländern werden nicht angenommen! `1`	Pflichtfeld
tel	string `varchar(25)`	Telefon oder Mobil-Nummer `+49 (0)1234-998877 6`	Optional
email	string `varchar(100)`	E-Mail Adresse `max.mustermann@policenwerk.de` Die E-Mail-Adresse ist eindeutig einer Makler-ID zugeordnet und dient als Identifikator. Ein Makler kann nur genau einen Kunden pro E-Mail-Adresse anlegen.	Pflichtfeld
kontoinhaber	string `varchar(200)`	Kontoinhaber (falls abweichend) `Erika Mustermann`	Optional
iban	string `varchar(22)`	IBAN Bankverbindung `DE02701500000000594937`	Pflichtfeld

Nur bei Kunden mit Firmenadresse

Parameter	Datentyp	Beschreibung	Notwendigkeit
firma	string `varchar(100)`	Firmenname (Vollständig inkl. Rechtsform) `MAX Muster GmbH & Co KG`	Pflicht wenn Firma, sonst Optional
ustid	string `varchar(20)`	Umsatzsteuer ID Nummer `DE123456789`	Optional
handelsr_nr	string `varchar(20)`	Handelsregister Nummer `HRA 1234`	Optional
handelsr	string `varchar(100)`	Handelsregister `AG Würzburg`	Optional

Antwort bei Fehlern

HTTP-Statuscodes

400 Bad Request: Die Anfrage ist fehlerhaft oder unvollständig.
401 Unauthorized: (siehe Authentifizierung)

Wenn spezifische Felder in der Anfrage fehlen oder ungültig sind, erhalten Sie eine detaillierte Fehlermeldung im JSON-Format zurück.
Dabei werden die fehlenden oder ungültigen Felder aufgelistet und es wird eine Beschreibung des Fehlers gegeben.

HTTP-Statuscode	JSON-Feld "error" enthält Beschreibung
400 Bad Request	{"land":["Bitte w\u00e4hlen Sie ein g\u00fcltiges Land aus unserer Liste aus."],"email":["Das Feld email beinhaltet keine g\u00fcltige E-Mail-Adresse."]}
400 Bad Request	{"hausnr":["Das Feld hausnr ist ein Pflichtfeld."]}

Antwort bei Erfolg

HTTP-Statuscodes

Der zurückgegebene HTTP-Statuscode entspricht immer dem Status der gesamten Anfrage.
Authentifizierung erfolgreich, aber fehlerhafte oder unvollständige Nutzdaten: Die API gibt einen 400-Bad Request zurück, auch wenn das Login korrekt war.

JSON-Felder

Feldname	Datentyp	Beschreibung	Wann erhältlich
login	boolean `true/false`	Gibt an, ob die Authentifizierung erfolgreich war.	Immer
token_valid_until	string `YYYY-MM-DD HH:MM:SS`	Gültigkeitsdatum, bis zu dem Sie das Token verwenden können.	Nur bei erfolgreicher Authentifizierung
warning	string `varchar(x)`	Login-Token is about to expire in less than 14 days	Nur bei fast abgelaufenem Token
error	string `leer`	Dieses Feld ist Erfolg immer leer.	Immer
success	boolean `true`	Gibt an, ob die Erstellung des Kunden erfolgreich war.	Nur bei erfolgreicher Erstellung oder Update eines bereits bestehenden Kunden mit gleicher E-Mail Adresse.
customer_id	string `varchar(20)`	Die eindeutige ID des Kunden.	Nur bei erfolgreicher Erstellung oder Update eines bereits bestehenden Kunden mit gleicher E-Mail Adresse.

Beispiele


                    curl -X POST "https://test.policenwerk.de/api/customer/create" -H "Content-Type: application/json" -d \
                    '{
                    "user_id": "", "login_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                    "nachname": "Mustermann", "strasse": "Musterstraße", "hausnr": "1a", "plz": "12345", "ort": "Musterstadt", "email": "keine-gueltige-email", "land": 2}'
                    }'

Antwort:

{"login":true,"token_valid_until":"2027-06-11 00:00:00","warning":"","error":{"vorname":["Das Feld vorname ist ein Pflichtfeld."],"email":["Das Feld email beinhaltet keine g\u00fcltige E-Mail-Adresse."]}}


                    curl -X POST "https://test.policenwerk.de/api/customer/create" -H "Content-Type: application/json" -d \
                    '{
                    "user_id": "", "login_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                    "vorname": "Max", "nachname": "Mustermann", "strasse": "Musterstraße", "hausnr": "1a", "plz": "12345", "ort": "Musterstadt", "email": "test@test.de", "land": 2}'
                    }'

Antwort: {"login":true,"token_valid_until":"2027-06-11 00:00:00","warning":"","error":"","success":true,"customer_id":"34313"}