Empfehlung Workflow Anbindung eines externen CRM über die Ad API an den PEIQ Werbemarkt

Die hier referenzierte https://peiq.atlassian.net/wiki/spaces/PPSD/pages/974127305 befindet sich noch im Modus Beta und ist teilweise noch “work in progress”

Inhaltsverzeichnis

1 Anlegen und Ändern von Geschäftspartnern
- 1.1 Nummernvergabe beim Anlegen
2 Abrufen von zuletzt geänderten Geschäftspartnern
- 2.1 Abrufen von bekannten Geschäftspartnern
3 Suche nach Geschäftspartnern
- 3.1 Parameter - Suchkriterien
- 3.2 Suchbedingungen
- 3.3 Suchergebnisse
4 Bankverbindungen abfragen, anlegen und aktualisieren

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 CIDs der Adressen (über vorher angelegte Adressen im Endpunkt POST /adresses) einer Adressart im Feld “numbers” 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.

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

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 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

Parameter	Beschreibung
limit	Begrenzung des Suchergebnisses auf eine bestimmte Anzahl.
offset	Initial leer. Werden mehr Geschäftspartner gefunden, als im `limit` definiert wurde, kann die Suche mit dem gelieferten `offset` fortgesetzt werden, um den nächsten Block zu finden.
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	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 mit name=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=*49 fü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 GET /businesspartners/{number} abgefragt werden (siehe Absatz “Abrufen von bekannten Geschäftspartnern”).

Bankverbindungen abfragen, anlegen und aktualisieren

Bankverbindungen sind als eigenständige Cluster mit Geschäftspartnern verknüpft.

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:

{
    "number": 1110002077,
    ...
    }
    "account_details": [
        {
            "number": "204-4996543"
        }
    ]
}

Abrufen der Bankverbindung

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”).

Prüfungen bei Neuanlage oder Update

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.

Bankverbindung zu Geschäftspartner hinzufügen

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:

{
        "account_details": [
        {
            "number": "204-4996543"
        },
        {
            "number": "204-4996770"
        },
        {
            "number": "204-4996780"
        }
    ]
}