Diese Anleitung erklärt Schritt für Schritt, wie Sie API-Zugangsdaten von Seereedereien (Maersk, CMA CGM, COSCO, Hapag-Lloyd usw.) und ähnlichen externen Systemen anfordern und in heyAtlas hinterlegen.
1. Wann werden sie benötigt?
heyAtlas-Tools wie Frachtratenabfrage, Container-/Schiffsverfolgung, Tarifabruf und Booking verbinden sich im Namen Ihres Unternehmens mit der API der Reederei. Für diese Verbindung sind die API-Zugangsdaten erforderlich, die die Reederei speziell für Sie ausstellt. Ohne Zugangsdaten können die entsprechenden Tools nicht ausgeführt werden, und der Assistent fragt Sie nach Verbindungsdetails.
2. Wen ansprechen und wie
- Ihr erster Ansprechpartner ist Ihr Account Representative oder Vertriebsmitarbeiter bei der Reederei.
- Bei den meisten großen Reedereien wird die Anfrage über Ihren Ansprechpartner an das Integrations-/IT-Team weitergeleitet.
- Geben Sie in Ihrer Anfrage Folgendes an: den Anwendungsfall (z. B. Frachtratenabfrage, Containerverfolgung), die benötigte Umgebung (Test/Produktion) und Ihren Kundencode.
Copy-paste-Anfragevorlage für E-Mail
Betreff: API-/Integrationszugangsanfrage — [Firmenname], Kundennr.: [XXXX]
Hallo,
bei [Firmenname] steuern wir unsere Abläufe über unseren digitalen Assistenten. Könnten Sie uns bitte die für uns zugewiesenen API-Zugangsdaten bereitstellen (Benutzername / API key, Endpoint-URLs und ggf. Kundencode)? Unser Anwendungsfall: [Frachtratenabfrage / Containerverfolgung / Booking]. Wir benötigen zunächst die Details für die Testumgebung und nach erfolgreicher Validierung die Produktionszugangsdaten.
Bitte teilen Sie Passwörter und Schlüssel über einen sicheren Kanal und nicht im E-Mail-Text.
Vielen Dank.
3. Was Sie anfordern sollten
| Punkt | Hinweise |
|---|
| API-Benutzername / Client ID | Die Anmeldeidentität |
| API-Passwort / Schlüssel / Client Secret | Geheimer Wert — muss über einen sicheren Kanal geteilt werden |
| Endpoint URL | Test- und Produktionsadressen können unterschiedlich sein |
| Kundencode | Bei einigen Reedereien verpflichtend |
| Umgebung | Test (sandbox) oder Produktion |
| IP-Beschränkung | Wenn die Reederei eine IP-Allowlist erzwingt, müssen heyAtlas-IPs hinzugefügt werden |
4. Reedereispezifische Tipps
- Reedereien mit Self-Service-Entwicklerportal (z. B. Maersk, CMA CGM, Hapag-Lloyd): Sie können sich im Namen Ihres Unternehmens im Entwicklerportal der Reederei registrieren, eine Anwendung erstellen und Ihren eigenen Schlüssel generieren. Die Freigabe kann einige Werktage dauern.
- Reedereien mit manuellem Prozess: Über Ihren Ansprechpartner wird ein Formular ausgefüllt; das Integrationsteam liefert die Schlüssel.
- Sie müssen nicht wissen, welchen Authentifizierungstyp (API Key, OAuth2 usw.) die jeweilige Reederei verwendet; die heyAtlas-Systemdefinition wendet automatisch die richtige Methode an. Ihre Aufgabe ist nur, die von der Reederei bereitgestellten Details vollständig einzugeben.
5. Eingabe der Daten in heyAtlas
- Öffnen Sie im Portal Einstellungen → Zugangsdaten (Unternehmensadmin-Berechtigung erforderlich).
- Wählen Sie das relevante System (Reederei) aus und füllen Sie die von der Reederei bereitgestellten Felder aus.
- Sie können mehrere Zugangsdaten für dasselbe System definieren und eine als Standard markieren (z. B. unterschiedliche Kundencodes).
- Prüfen Sie nach dem Speichern die Verbindung, indem Sie das zugehörige Tool über den Assistenten testen.
Siehe auch: Zugangsdaten verwalten und Systemverbindungen.
6. Sicherheit
- Vermeiden Sie es, Passwörter und Schlüssel als Klartext im E-Mail-Text zu erhalten; bevorzugen Sie einen sicheren Freigabelink.
- heyAtlas speichert Zugangsdaten verschlüsselt und zeigt sie auf dem Bildschirm niemals als Klartext an.
- Wenn Sie einen Leak vermuten, bitten Sie die Reederei, den Schlüssel zu rotieren, und aktualisieren Sie den neuen Wert in heyAtlas.
- Siehe auch: Sicherheit von Zugangsdaten.
7. Häufige Probleme
- 401-/403-Fehler: Das Passwort könnte falsch eingegeben, abgelaufen oder das Konto noch nicht aktiviert sein. Geben Sie die Daten erneut ein; wenn das Problem bleibt, lassen Sie sie von Ihrem Ansprechpartner prüfen.
- Test-/Produktionsverwechslung: Ein Testschlüssel funktioniert nicht gegen den Produktions-Endpoint (oder umgekehrt). Prüfen Sie, für welche Umgebung die Daten eingetragen wurden.
- "Zugriff gewährt", aber nichts funktioniert: Bei manchen Reedereien werden API-Abonnements pro Produkt aktiviert (z. B. nur Tracking); fragen Sie, welche Produkte Ihr Abonnement abdeckt.
- IP-Blockierung: Wenn die Reederei IP-Beschränkungen erzwingt, muss die IP, von der heyAtlas aufruft, auf die Allowlist gesetzt werden; Sie können die IP-Details bei unserem Support-Team anfordern.
8. Hilfe erhalten
Wenn der Prozess stockt, eröffnen Sie ein Support-Ticket über Support → Meine Tickets; geben Sie einfach an, um welche Reederei es geht und bei welchem Schritt Sie festhängen.
