Die hier referenzierte PEIQ Ad API (Beta) befindet sich noch im Modus Beta und ist teilweise noch “work in progress”
Anlegen und Ändern von Geschäftspartnern
Geschäftspartner können direkt aus dem CRM heraus mit POST /businesspartners über die AdAPI in PEIQ angelegt und mit PUT /businesspartners/{number} geändert werden. Neben den definierten Pflichtfeldern gilt, dass dabei nicht mitgelieferte Elemente in PEIQ beim Anlegen mit Default-Werten gefüllt werden bzw. leer bleiben. Auch bei Änderungen werden einzelne Werte, deren Elemente an der AdAPI nicht mitgeliefert werden, in PEIQ nicht verändert. So können über die AdAPI gezielt nur die relevanten Werte übertragen werden.
Bei einem Set von Daten (Array), wie z.B. business_partner_information, von denen es bei einem Geschäftspartner mehrere Datensätze (z.B. für jeden Rechnungsmandant einen) geben kann gilt, dass jeder Datensatz, der behalten werden soll, mitgeliefert werden muss (einzelne Elemente innerhalb des Datensatzes können jedoch weggelassen werden, wenn diese in PEIQ nicht verändert werden sollen). Wenn an der Menge der in PEIQ vorhandenen Datensätze nichts verändert werden soll, so muss die übergeordnete Struktur bei der Übertragung weggelassen werden.
Eine Ausnahme gibt es bei Adressen:
Wenn
"scope": "all"mitgegeben wird, dann müssen alle Adressen einer Adressart mitgeliefert werden, die in PEIQ vorhanden sein sollen.Bei
"scope": "active only"wird nur eine Adresse mitgeliefert und diese in PEIQ als ab sofort gültige Adresse übernommen. Alle bisherigen Adressen dieser Adressart werden in PEIQ behalten und als nicht mehr gültig markiert.
Nummernvergabe beim Anlegen
Die Anlage von Geschäftspartnern kann sowohl direkt in PEIQ, als auch durch verschiedene externe Systeme über die AdAPI erfolgen. Da die Geschäftspartnernummer das Merkmal zur eindeutigen Identifizierung ist, wird empfohlen, diese Nummer bei neuen Geschäftspartnern von PEIQ aus einem dort definierten Nummernkreis vergeben zu lassen.
Beim Anlegen über die AdAPI wird die jeweils neu vergebene Nummer von PEIQ an das externe System zurückgegeben. Diese Logik wird verwendet, wenn beim Anlegen mit POST /businesspartners das Element "number" nicht mitgeliefert wird.
Alternativ kann die Geschäftspartnernummer auch direkt beim Anlegen über die AdAPI vom externen System im Element "number" mitgeliefert werden. Dies wird empfohlen, wenn es sich zum Beispiel um die einmalige Übernahme von Stammdaten aus einem Altbestand handelt. Dabei ist zu beachten, dass sich die Nummernkreise nicht überschneiden bzw. der Startwert in PEIQ nach der Initialbefüllung auf den nächstmöglichen Wert gesetzt wird, bevor neue Geschäftspartner mit Nummernvergabe durch PEIQ angelegt werden.
Davon unberührt kann optional eine externe Kundennummer über die AdAPI transportiert werden, die allerdings informativen Charakter hat und nicht als Kennzeichen zur eindeutigen Identifizierung dient.
Abrufen von zuletzt geänderten Geschäftspartnern
Über den Endpunkt GET /businesspartners/events (Feed-orientiert) kann sich ein externes System die Geschäftspartnernummern, welche seit dem letzten Offset geändert wurden oder neu hinzugekommen sind (beim ersten Mal ohne Offset), abrufen. Mit dem Ergebnis wird ein Offset zurückgegeben.
Damit das CRM immer den neuesten Stand der Geschäftspartner kennt, können unter Angabe des Offsets die IDs ("number") der zuletzt geänderten Geschäftspartner abgefragt werden. Mit dem Ergebnis wird erneut ein Offset zurückgegeben. Dieses Offset kann wiederum beim nächsten Aufruf mitgegeben werden, um nur die geänderten Daten seit dem letzten Abruf zu erhalten.
Die Daten der Geschäftspartner können dann jeweils mit Hilfe der ID ("number") mittels GET /businesspartners/{number} abgefragt werden.
Abrufen von bekannten Geschäftspartnern
Die Geschäftspartnernummer wird beim Anlegen eines Geschäftspartners über die AdAPI von PEIQ automatisch angelegt und an das externe System übermittelt, sofern sie beim Anlegen nicht im Element "number" definiert wurde, siehe Nummernvergabe beim Anlegen.
Informationen eines bekannten Geschäftspartners können bei GET /businesspartners/{number} unter Angabe der Geschäftspartnernummer "number" abgefragt werden.
Suche nach Geschäftspartnern
Die Suche nach Geschäftspartnern erfolgt als GET über folgenden Endpunkt:
{{baseURL}}/adapi/v1/businesspartners/search
Parameter - Suchkriterien
Die Suche nach Geschäftspartnern kann mit vorgegebenen Suchkriterien eingegrenzt werden. Bei der Suche können verschiedene Parameter angegeben werden:
Parameter | Beschreibung |
|---|---|
limit | Begrenzung des Suchergebnisses auf eine bestimmte Anzahl. |
offset | Initial leer. Werden mehr Geschäftspartner gefunden, als im |
name | Nachname / Name |
first_name | Vorname / Name2 |
street_name | Straßenname |
zip | Postleitzahl |
city | Ort |
country | Land |
phone_number | Telefonnummer |
area_code | Vorwahl |
country_code | Ländervorwahl |
Email-Adresse |
Suchbedingungen
Bei der Suche dürfen nur die Parameter angegeben werden, zu denen auch Werte geprüft werden sollen.
Bei der Suche werden nur Geschäftspartner berücksichtigt, die dem Modul Werbemarkt zugeordnet sind.
Eine Wildcard-Suche ist mit
*möglich.
Sollen alle Geschäftspartner gefunden werden, deren Nachname mit "Ma" beginnt, so ist die Suche mitname=ma*einzuschränken.Bei Suche nach einem bestimmten Ort werden alle Adressen (Haupt,- Rechnungs- und weitere Adressen, aktuelle und nicht mehr gültige) durchsucht. So erhält man z.B. als Ergebnis einen Geschäftspartner, der zum gesuchten Ort nur eine Rechnungsadresse hat.
Die Suche kann nach nach Vorwahl und Ländervorwahl eingeschränkt werden. Dabei müssen die Werte so angegeben werden, wie sie in NGen gespeichert sind, oder mit Wildcard
*- z.B.country_code=*49für Geschäftspartner mit Telefonnummer in Deutschland.
Suchergebnisse
Ergebnis der Suche ist eine Ergebnisliste mit den Kundennummern der gefundenen Geschäftspartner.
Detaillierte Informationen zu den gefundenen Geschäftspartnern können über den Endpunkt
{baseURL}}/adapi/v1/businesspartners/{numer}
abgefragt werden (siehe Absatz “Abrufen von bekannten Geschäftspartnern”).