| Info |
|---|
Die hier referenzierte PEIQ Ad API (Beta) befindet sich noch im Modus Beta und ist teilweise noch “work in progress” |
Inhaltsverzeichnis
| Expand | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
|
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.
...
| Note |
|---|
Eine Ausnahme gibt es bei Adressen:
|
Das Befüllen mit Default-Werten bei Anlage neuer Cluster funktioniert nur dann, wenn die entsprechenden Felder in der API nicht mit übergeben werden.
Nummernvergabe beim Anlegen
...
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.
...
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.
...
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
...
Informationen eines bekannten Geschäftspartners können bei GET /businesspartners/{number} unter Angabe der Geschäftspartnernummer "number" abgefragt werden.
...
Die Suche nach Geschäftspartnern erfolgt als GET über folgenden Endpunkt GET /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.
...
Detaillierte Informationen zu den gefundenen Geschäftspartnern können über den Endpunkt GET /businesspartners/{number} abgefragt werden (siehe Absatz “Abrufen von bekannten Geschäftspartnern”).
...
Bankverbindungen sind als eigenständige Cluster mit Geschäftspartnern verknüpft.
...
Der Endpunkt accountdetails ermöglicht das Abfragen und Anlegen von Bankverbindungen. Neu angelegte Bankverbindungen sind über den Endpunkt businesspartners mit Geschäftspartnern zu verknüpfen.
Abrufen von Bankdaten(-Nummern) eines Geschäftspartners
Über den Endpunkt GET /businesspartners/{number} kann sich ein externes System die eindeutige Nummer der Bankdaten, welche bereits mit einem Geschäftspartner verknüpft ist, ausgeben lassen:
...
Bei der Abfrage der Bankverbindung ist die aus dem Endpunkt GET /businesspartners/{number} erhaltene number aus den account_details anzugeben (ID der Bankverbindung). Nun kann sich ein externes System über den Endpunkt GET /accountdetails/{number} die Daten der Bankverbindung des Geschäftspartners abrufen.
Anlage der Bankverbindung
Über den Endpunkt POST /accountdetails können Bankverbindungen neu angelegt werden. Der Rückgabewert des POST ist die ID der Bankverbindung (“account_details” → “number”: “204-4996543”).
...
Bei Neuanlage oder Update einer Bankverbindung finden folgende Prüfungen statt:
Ungültige deutsche IBAN → Fehlermeldung “IBAN is not valid”
Gültige deutsche IBAN → BLZ wird aus IBAN ermittelt und die entsprechende Bank aus der Datenbank zugeordnet, keine BIC notwendig
IBAN fehlt bei Neuanlage oder soll bei Update geleert werden → Fehlermeldung
BIC fehlt bei ausländischr IBAN → Fehlermeldung
Ausländische IBAN → wird ohne Prüfung übernommen und Bank (sofern die BIC noch nicht bekannt ist) mit den angegebenen Daten angelegt
Rechnungsmandant fehlt bei Neuanlage oder soll bei Update geleert werden → Fehlermeldung
Aktualisierung der Bankverbindung
Über den Endpunkt PUT /accountdetails/{number} können Bankverbindungen aktualisiert werden.
...
Um eine neue Bankverbindung zu einem Geschäftspartner hinzuzufügen muss der Rückgabewert des Endpunktes POST /accountdetails via Endpunkt PUT /accountdetails/{number} am Geschäftspartner hinzugefügt werden. Dabei ist es möglich, ausschließlich die accountdetails zum Geschäftspartner zu übermitteln:
| Code Block |
|---|
{
"account_details": [
{
"number": "204-4996543"
},
{
"number": "204-4996770"
},
{
"number": "204-4996780"
}
]
}
|
| Include Page | ||||
|---|---|---|---|---|
|