Schnittstellen der Ameise

Disclaimer:

Die Ameise ist ein Produkt von Dionera GmbH (Tochter blau direkt GmbH) und liegt außerhalb des Einflussbereichs vom MVP-Connector. Wir können nur mit den Schnittstellen und Möglichkeiten arbeiten, die angeboten werden. 

Die Ameise bietet verschiedene Services zum Datenaustausch:

1. Webservice (Mitarbeiter / Vermittler) als API

2. OAuth2: Authentifizierung als Mitarbeiter (user) 

3. DailyUp

4. Events (Ansteuern von externen Webhooks)

Qonekto nutzt aktuell 1, 2, 3

Die Schnittstellendokumentation kann unter folgendem Link eingesehen werden: 

https://docs.dionera.com

Webservice Mitarbeiter 

https://docs.dionera.com/webservice/mitarbeiter/

Mit dem Mitarbeiter Webservice kann per API umfangreich Daten gelesen und geschrieben werden. Vom Prinzip her genauso wie ein Mensch über die Weboberflösche maklerinfo.biz. Nur dass dies eben über den "Maschinenzugang" funktionert. Meist sind mehrere Aufrufe  (Requests) der Schnittstelle notwendig, um eine kompletten Datensatz zu lesen oder zu schreiben. (Bsp. Kontakt-Basisdaten, Kontakt-Details, Adresse, Kommunikation, etc.) 

Der Webservice kann nur auf Anfrage Daten liefern oder schreiben. Der Webservice liefert nicht automatisch neue Daten oder Veränderungen!

Eine API ist so etwas wie eine Laderampe. Sie steht da und man kann dort Daten abliefern und abholen. Um dies zu tun, braucht es aber einen ensprechenden Transporter, der an die Rampe fährt. Dieser Transporter ist der MVP-Connector. 

Oauth2

Oauth2 ist ein Service von Dionera zur Authentifizierung von Usern (Mitabreiterebene). Damit legitimieren wir uns im MVP-Connector. Schließlich ist es wichtig, dass nur erlaubte Nutzer die Daten lesen, Daten schreiben und Daten verändern können und kein unbefugter Dritter. Der daraus generierte Token berechtigt ebenfalls zur Nutzung der API. Die Authentifizerung erfolgt hier auf Mitarbeiterebene. 

Dies ist bekannt von verschiedenen blau direkt Services, wie z.b. PANDA. 

Mit "Login via Ameise" gibst du dem MVP-Connector die Berechtitung, die Daten abzurufen oder Daten zu schreiben.  

DailyUp

Der Service DailyUp pusht einmal täglich (meist Nachts) alle Daten einer Hauptvermittlernummer auf einen Server (FTP). Dies geschieht mit verschiedenen Listen. Die Daten sind nicht 100%ig alle Informationen aus der Ameise, z.B. wird keine KoHi übertragen. Mit den Kunden und Vertragsdaten werden eine Reihe von Listen übertragen. Z.B. mögliche Rechtsformen, Länder, Vertragsstatus, Zahlweisen, etc. 

Die Listen können genutzt werden, um Felder im CRM 1:1 anzulegen. 

Der DailyUp liefert immer den Gesamtbestand zum jeweiligen. Der Service liefert keine Veränderungen oder Unterschiede zum vorherigen Upload (Delta) oder liefert ein Log, ob und wann der Datensatz verändert wurde und wo. 

Der Service DailyUp muss bei blau direkt normalerweise separat beauftragt werden und ist kostenpflichtig. Sofern du Dailyup über Qonekto nutzen möchtest, erfolgt die Einrichtung immer über qonekto. Wir übernehmen wir für dich alle notwendigen Einrichtungen und übernehmen die Kommunikation mit blau direkt. 

Der MVP-Connector stellt einen Ordner pro Vermittler (bei uns Team) auf einem FTP-Server bereit. Diese Daten müssen blau direkt übermittelt werden. Die erforderlichen Daten, die blau direkt für die Einrichtung des Services braucht, bekommst du im Reiter “Ameise”.

Aus den gesamten Daten aus Dailyup erzeugt der MVP Connector jede Nacht die entsprechendne Updates und Änderungen. Das Dailyup triggert dann alle notwendigen Events, um die Daten in einem Fremdsystem zu updaten. 

Eindeutige IDs

Um Datensätze eindeutig zu identifizieren gibt es IDs, die je nach System unterschiedlich sind.

Kundennummer: z.b. 5001234567

Vertragsnummer: 1119876

Der Vorteil ist, dass du hiermit URLs generieren kannst, um so direkt in den Vertrag zu “springen”. 

Beispiel: 

https://www.maklerinfo.biz/maklerportal/?show=vertrag&vertrag=VERTRAGSNUMMER

oder 

https://www.maklerinfo.biz/maklerportal/?show=kunde&kunde=KUNDENNUMMER

Events können bei bestimmten Informationen/Veränderungen. Z.B. bei einem neuen Dokument, wenn sich ein Kunden ins System eingeloggt hat, etc. Events müssen separat angelegt werden (Aufwand! Nur für Enterprise Kunden möglich) 

Diese Events triggern einen Webhook (https://support.blaudirekt.de/hc/de/articles/4409625338129-Was-sind-webhooks-) 

Damit können dann zusammen mit der API (Webservice) Übertragungen ausgelöst werden, die zeitnah (meist ein paar Sekunden) erfolgen und damit quasi “Echtzeit” darstellen. 

Beispiel: Kunde gibt eine neue Anschrift in simplr ein. Das Event “Adresse geändert” wird getriggert. Fremdsystem holt sich über API die neue Adresse des Kunden. Eine Folgeaktion kann im Fremdsystem ausgelöst werden.

Stand 12/2022 gibt es folgende Events: 

Mandant » Vermittler 28 

Mandant » Mitarbeiter 5 

Mandant » Gesellschaft 1 

Vermittler » Kunde 16 

Vermittler » Gesellschaft 2

Events werden von uns aufgrund der Komplexität aktuell nicht genutzt. Die benötigten Daten kommen einmal nachts sowieso als Veränderung über. Der einzige Vorteil wäre lediglich die schnellere Aktualisierung.