Verbindung einrichten
Damit TOPIX ERP mit nexcore verbunden werden kann, muss die Verbindung einmalig über die vorhandene REST-API eingerichtet werden.
Die Integration ermöglicht einen automatisierten Datenaustausch zwischen beiden Systemen.
Voraussetzungen
TOPIX (API)
Aktiver TOPIX-Client (Cloud oder On-Premise) und Nutzerzugriff auf die Einstellungen.
TOPIX (Webhooks)
TOPIX-Client (Cloud): Erfrage die valide Webhook-URL bei Deinem TOPIX-Berater. TOPIX-Client (On-Premise): Erstellung einer validen Webhook-URL von Deinem Administrator zusammen mit Deinem TOPIX-Berater. Wichtig: die URL muss über das Internet erreichbar sein und über ein gültiges SSL-Zertifikat verfügen.
nexcore
Aktive nexcore Tenant und Nutzerzugriff mit Rechten für den Developer Bereich.
API-Einrichtung
API-Key erstellen (nexcore)
Navigiere zuerst in nexcore über Einstellungen zum Bereich Developer, um dort einen API-Key für die Verbindung mit TOPIX zu erstellen.
Mit einem Klick auf den Button "+ API-Key erstellen" öffnet sich ein Dialog in welchem Du einen Kommentar zur späteren Zuordnung der Verwendung des Keys eingeben musst.
Der API-Key wird nur einmal angezeigt! Kopiere und notiere Dir die API Key-ID und den API Key für die weitere Verwendung (beide Elemente werden für die Installation von nexcore.CONNECT oder die Einrichtung einer API-Verbindung benötigt)
Der nun erstellte, individuelle API-Key wird Dir sofort in der API-Key-Liste angezeigt und kann ab sofort verwendet werden.
Wenn Du mehrere Integrationen nutzt (z. B. ERP-System, BI-Tool, Webservice), empfiehlt es sich, für jede Anwendung einen separaten API-Key mit individuellem Kommentar zu erstellen. So kannst Du die Nutzung besser nachvollziehen.
Verbindung testen (TOPIX)
Klicke nachdem Du die API-Key Informationen eingefügt hast auf den Button "Verbindung testen".
Wenn alles korrekt eingetragen wurde, erscheint eine Meldung mit der Information "Verbindung erfolgreich".
Sollte die Verbindung nicht erfolgreich sein, überprüfe zunächst die eingetragenen Werte für API-Key und API-Key ID – wurden diese ggf. vertauscht?
Sollte es zu Problemen mit der Einrichtung Deiner Verbindung kommen, wende Dich zunächst an Deinen TOPIX-Berater. Wir stehen in engem Austausch mit diesem und können uns bei Bedarf direkt bzgl. eventueller Probleme austauschen.
Webhooks in TOPIX einrichten
Events abonnieren
Klicke dann auf den Button "Events abonnieren" und bestätige im daraufhin erscheinenden Dialog "Events neu generieren" mit "OK".
Nach wenigen Sekunden sollte Dir eine Meldung mit der Information "Events erfolgreich erstellt" angezeigt werden
Nach erfolgreicher Einrichtung sollte die erzeugte Subscription nicht gelöscht werden.
Das Löschen einer Subscription führt dazu, dass keine Events mehr an TOPIX übertragen werden.
Webhook testen
Wenn die vorhergehende Rückmeldung positiv war, klicke nun auf den Button "Webhook testen" und bestätige im daraufhin erscheinenden Dialog "Möchten sie den Webhook testen?" mit "OK".
Nach wenigen Sekunden sollte Dir eine Meldung mit der Information "Nexcore Webhook erfolgreich" angezeigt werden
Häufige Fehler und Lösungsmöglichkeiten
Es kann keine Verbindung hergestellt werden
Die Verbindung zwischen TOPIX und nexcore basiert auf einer REST-API. Über diese wird zunächst die technische Erreichbarkeit und Authentifizierung geprüft („Verbindung testen“).
Kann keine Verbindung hergestellt werden, bedeutet dies, dass TOPIX die nexcore-API nicht erfolgreich erreichen oder sich nicht authentifizieren kann. In diesem Fall findet keinerlei Datenaustausch statt.
Mögliche Ursachen
Der API-Key ist nicht korrekt oder unvollständig hinterlegt.
API-Key und API-Key-ID wurden vertauscht.
Der API-Key wurde zwischenzeitlich gelöscht oder neu generiert.
Die hinterlegte URL ist fehlerhaft (z. B. http statt https).
Die Webhook-/API-URL ist nicht öffentlich erreichbar.
Eine Firewall oder Proxy blockiert ausgehende HTTPS-Anfragen.
Das SSL-Zertifikat der Zieladresse ist ungültig oder abgelaufen.
Lösungsansätze
API-Key und API-Key-ID prüfen
In nexcore werden zwei Werte angezeigt:
API Key-ID (entspricht "API Key-ID" in TOPIX)
API Key (entspricht "API-Schlüssel in TOPIX)
Bitte stelle sicher, dass diese Werte in Deinem TOPIX-Mandanten nicht vertauscht wurden.
API-Key auf Gültigkeit prüfen
In nexcore unter Einstellungen → Developer → API prüfen, ob der API-Key aktiv ist.
Falls unsicher, neuen API-Key generieren und in TOPIX aktualisieren.
URL prüfen
Ist die URL exakt wie in nexcore angegeben hinterlegt?
Wird https verwendet?
Keine zusätzlichen Leerzeichen?
Erreichbarkeit prüfen
Ist der Server online?
SSL-Zertifikat gültig?
Firewall blockiert ausgehende HTTPS-Verbindungen?
Weitere Informationen zu den API-Einstellungen in nexcore findest Du hier.
Sichere Dir den nexcore API Key und zugehörige API Key-ID immer an einem gesicherten Speicherort, um auf diese Informationen später noch einmal zugreifen zu können.
Es werden keine Events übertragen
Nachdem die API-Verbindung erfolgreich eingerichtet wurde, erfolgt die automatische Aktualisierung von Daten über sogenannte Webhook-Subscriptions.
Dabei abonniert TOPIX bestimmte Events in nexcore.
Wenn sich in nexcore relevante Daten ändern (z. B. Statusänderungen, Aktualisierungen), sendet nexcore ein Event an TOPIX.
Existiert keine aktive Subscription, erhält TOPIX keine Benachrichtigungen mehr über Änderungen in nexcore.
Die Verbindung funktioniert technisch weiterhin – jedoch findet kein automatischer Datenaustausch statt.
Wird eine bestehende Subscription gelöscht (z. B. über das Papierkorb-Symbol), empfängt TOPIX ab diesem Zeitpunkt keine Events mehr, auch wenn die API-Verbindung weiterhin erfolgreich getestet werden kann.
Mögliche Ursachen
Es existiert keine aktive Webhook-Subscription.
Eine bestehende Subscription wurde manuell gelöscht.
„Events abonnieren“ wurde nach der Einrichtung nicht ausgeführt.
Die Webhook-URL wurde nachträglich geändert.
Die Subscription wurde erzeugt, konnte aber nicht korrekt gespeichert werden.
Die Webhook-URL ist nicht mehr erreichbar (z. B. Server offline oder Zertifikatproblem).
Lösungsansätze
Subscriptions prüfen
Öffne in TOPIX die Schnittstelleneinstellungen.
Prüfe die Liste der Subscriptions.
Ist die Liste leer, existiert keine aktive Subscription.
Events erneut abonnieren
Klicke auf „Events abonnieren“.
Bestätige „Events neu generieren“.
Prüfe anschließend, ob die Subscription nun in der Liste angezeigt wird.
Webhook-Logs in nexcore prüfen
In nexcore unter Einstellungen → Developer → Logs prüfen, ob eingehende Webhook-Requests angezeigt werden.
Werden keine Requests protokolliert, sendet TOPIX aktuell keine Events.
Webhook-URL prüfen
Ist die URL exakt wie in nexcore hinterlegt?
Wurde sie kürzlich geändert?
Ist sie über das Internet erreichbar?
Ist das SSL-Zertifikat gültig?
Weitere Informationen zu den Webhook-Einstellungen in nexcore findest Du hier.
Zuletzt aktualisiert