Bewährte Vorgehensweisen zur Integration der FedEx APIs

In diesem übersichtlichen Leitfaden wird die Integration von FedEx APIs erläutert, um eine leistungsstarke, schnelle und sichere Lösung zu erhalten.

Mit diesen bewährten Vorgehensweisen können Entwickler APIs effizient integrieren:

API-URIs

• Zum Testen und für die Produktion werden verschiedene API-URIs verwendet. 
• Entwickler sollten die Test-URIs zum Entwickeln und Testen der Integration und die Produktions-URIs für die Produktion verwenden.

Hier finden Sie die API-URIs:

Test: https://apis-sandbox.fedex.com/

Produktion: https://apis.fedex.com/

Verwaltung von Anmeldeinformationen

• API-Schlüssel und geheimer Schlüssel

• Mithilfe Ihres API-Schlüssels und des geheimen Schlüssels wird Ihre Anwendung identifiziert. Diese Schlüssel für die Anforderung eines OAuth-Tokens verwendet werden.

1. API-Schlüssel und geheimer Schlüssel müssen unbedingt vertraulich behandelt werden. Geben Sie diese keinesfalls per E-Mail oder verteilten Code mit clientseitigem JavaScript weiter.
2. Die Sicherheit Ihrer Anwendung ist gefährdet, wenn Ihr API-Schlüssel oder der geheime Schlüssel entwendet werden. Wenn Sie vermuten, dass die Sicherheit Ihrer Anmeldeinformationen nicht mehr gewährleistet ist, müssen Sie unverzüglich den geheimen Schlüssel erneut erstellen.
3. Sensible Informationen wie den geheimen Schlüssel sollten Sie nicht protokollieren.

• Hartcodieren Sie API-Schlüssel und geheimen Schlüssel nicht in Ihren Code.
• Ihre Anwendung muss API-Schlüssel und geheimen Schlüssel dynamisch aktualisieren können.
• Bewahren Sie die Client-Anmeldedaten in einem Tresor oder an einem sicheren Ort auf.

• OAuth-Token

• Das Zugriffstoken darf nur auf dem Server der Webanwendung gespeichert und nicht im Browser offengelegt werden.
• Das Token darf nicht in Ihre Anwendungen hartcodiert werden.
• Schützen Sie die Zugriffstokens, um eine Offenlegung zu verhindern.
• Vermeiden Sie mehrfache Aufrufe des OAuth-Tokens für neue Zugangstokens. Es wird empfohlen, das Zugriffstoken bis zum Auftreten von HTTP-Fehlercode 401 zwischenzuspeichern. Erstellen Sie das OAuth-Token dann erneut.
• Legen Sie das Token nicht gegenüber dem Endbenutzer oder der Anwendung offen.
• Verwenden Sie für API-Übertragungen stets HTTPS.

Codierungsverfahren

• Verwenden Sie Transport Layer Security (TLS) 1.2 oder höher, um die Compliance mit dem aktuellen und sicheren Kommunikationsprotokoll für die Datenverschlüsselung zu gewährleisten.
• Legen Sie für jede API-Anforderung die korrekten API-Header fest. Die Header-Informationen finden Sie jeweils am Seitenende der API-Dokumentation. 
• Legen Sie „Content-Type“ in HTTP POST auf „application/json“ fest.
• Orientieren Sie sich bei jeder API am Beispielcode. Für jeden API-Endpunkt werden verschiedene Beispiele bereitgestellt, mit denen die erforderlichen Elemente, Formate usw. erläutert werden.
• Wenn Benutzer oder Entwickler zu viele Dezimalstellen in den Werten übermitteln, kann dies ungewöhnliche Fehler verursachen. Für Währungsbeträge oder Gewichtsangaben sind nur zwei Dezimalstellen zulässig. Für Abmessungen wie Länge, Breite und Höhe dürfen keine Dezimalstellen verwendet werden.

Beispiele: Gewicht: 45,26, Währungsbetrag/Wert: 100,52, Länge: 10, Breite: 25, Höhe: 15.

• Vermeiden Sie das Senden leerer Elemente.

Beispiel: „Adresszeilen“: „“

• Senden Sie nur Daten, die für die Verarbeitung der Anfrage erforderlich sind.

Übertragen Sie beispielsweise für Sendungen innerhalb der USA keine Handelsrechnungs- oder Warendaten, die nur für internationale Sendungen erforderlich sind.

• Legen Sie bei der Codeentwicklung fest, wie reagiert werden soll, wenn ein nicht erforderliches Element (z. B. ein Tarif) nicht zurückgegeben wird. Überprüfen Sie vor Verwendung der Daten die zurückgegebene Übertragung auf fehlende Elemente.

Es ist beispielsweise möglich, ein Paket zu versenden, wenn der Tarif nicht anwendbar ist. Überprüfen Sie vor Verwendung der Daten die zurückgegebene Übertragung auf fehlende Elemente.

• Vermeiden Sie nach Möglichkeit starre Abhängigkeiten hinsichtlich der Integration der FedEx APIs.
• Mit folgenden Funktionen können Sie die Latenzzeit verkürzen und präzise Ergebnisse abrufen:
  
  • Filtering – Eingrenzen der Suche mithilfe der gewünschten Parameter
  • Sorting – Sortieren der Ergebnisse nach einem bestimmten Parameter in auf- oder absteigender Reihenfolge
• Überprüfen Sie vor dem Übertragen der erforderlichen Felder, z. B. Postleitzahl des Empfängers und Gewicht des Pakets, dass diese Daten enthalten. Überprüfen Sie, dass die Daten den Vorgaben der jeweiligen Felder entsprechen. Dadurch können Fehler in der Übertragung minimiert werden.
  

Überprüfen Sie beispielsweise bei US-amerikanischen Postleitzahlen, dass im Feld nur numerische Werte in fünfstelligem Format oder im Format ZIP+4 vorliegen.

• Vermeiden Sie eine Beeinträchtigung der Verfügbarkeit und Zuverlässigkeit des FedEx Systems:
  
  • Führen Sie keine Leistungstests in der Test- oder Produktionsumgebung durch.
  • Implementieren Sie Code, mit dem das wiederholte Fehlschlagen derselben Übertragung verhindert wird.
• Die Begrenzung wird auf 750 Transaktionen in einem Zeitraum von 10 Sekunden festgelegt. Wenn dieser Grenzwert innerhalb des Zeitraums erreicht wird, wird der HTTP-Fehler-Code 429 Too many requests zurückgegeben. Weitere Transaktionen werden erst nach Ablauf der 10 Sekunden ausgeführt.
  

Beispiel: Wenn wir innerhalb der ersten vier Sekunden 750 Anfragen empfangen, wird folgender HTTP-Fehler-Code ausgegeben: „429 Too many requests Wir haben in zu kurzer Zeit zu viele Anfragen empfangen. Versuchen Sie es in Kürze erneut.“ Transaktionen werden für die restlichen sechs Sekunden angehalten und anschließend fortgesetzt.

• Geschäftsregeln für Sendungen wie Servicetypen, Pakettypen, Gewichtsbeschränkungen usw. dürfen nicht hartcodiert werden, da diese Änderungen unterliegen.

Fehlerbehandlung

Jede API-Antwort enthält einen HTTP-Statuscode und Nutzdaten. Antworten können einen Fehler, eine Warnung oder einen Hinweis umfassen. Warnungen und Hinweise sind keine Anzeichen für einen Fehler. Fehlermeldungen und Warnungen müssen jedoch protokolliert und überprüft werden. Durch eine ordnungsgemäße Fehlerbehandlung können eine fehlerfreie Integration mit FedEx gewährleistet und Serviceunterbrechungen vermieden werden.

HTTP-Statuscodes

Preis

• Preisangebote können mit zwei Methoden abgerufen werden:
  
  • Preis für einen bestimmten serviceType – die Ergebnisse werden entsprechend dem angegebenen serviceType-Wert gefiltert. Die Größe der Antwort wird so verringert und die Antwortzeit verkürzt.
    

    Beispiel: STANDARD_OVERNIGHT
    

  • Alle Preise des Shops – ohne Angabe eines serviceType werden alle zutreffenden Services mit den entsprechenden Tarifen zurückgegeben.
• Mithilfe der API für die Serviceverfügbarkeit können die verfügbaren Services, Paketoptionen und Sonderservices für eine bestimme Kombination aus Ausgangs- und Zielort ermittelt werden. In der Preisanfrage werden serviceType und Paketoptionen ausgegeben.
  

  Beispielsweise steht u. a. die Option STANDARD_OVERNIGHT nicht für alle Postleitzahlen zur Verfügung.

• Für die Anwendung eines Sonderservice auf eine Sendung müssen der Sonderservicetyp und die zugehörigen Details angegeben werden. 
  
  • Hinweis: Nicht alle Sonderservices verfügen über Details.
• Beachten Sie die Dokumentation der Preis-APIs.

Send.

• Mithilfe der API für die Serviceverfügbarkeit können die verfügbaren Services für eine bestimme Kombination aus Ausgangs- und Zielort ermittelt werden. In der Versandanfrage werden serviceType und Paketoptionen ausgegeben.
• Für die Anwendung eines Sonderservice auf eine Sendung müssen der Sonderservicetyp und die zugehörigen Details angegeben werden.
  
  • Hinweis: Nicht alle Sonderservices verfügen über Details.
• Schließen Sie FedEx Ground am Ende des Versandtages vor Abholung der Sendung ab.
  
• Beachten Sie die Dokumentation der Versand-APIs.
  

Verfolgen

• Begrenzen Sie die Anzahl der Sendungsverfolgungsnummern in einer Verfolgungsanfrage auf 30. Die Größe der Antwort wird so verringert und die Antwortzeit verkürzt.
• Begrenzen Sie die Anzahl der Verfolgungsanfragen für ein Paket auf das für Geschäftszwecke erforderliche Maß.
• Entfernen Sie bei der Chargenverfolgung die Pakete aus der Charge, für die als Status „zugestellt“ zurückgegeben wurde.
• Beachten Sie die Dokumentation der Sendungsverfolgungs-APIs.

Adressprüfung

• FedEx stellt die Adressprüfung als Empfehlung und nicht als endgültige Festlegung bereit. Die Festlegung, ob eine Adresse nutzbar ist, muss vom Endbenutzer auf Grundlage der bereitgestellten Daten und des Geschäftszwecks vorgenommen werden. Um die Verarbeitung von Bestellungen sicherzustellen, muss ein Verfahren für die Behandlung von Adressen implementiert werden, die nicht überprüft werden können.
• Verbessern Sie die Versanderfahrung, indem Sie den Versandvorgang nicht von optionalen Services wie der Adressprüfung abhängig machen.

Wenn beispielsweise zum Zeitpunkt der Bestellungseingabe oder des Versands die API für die Adressprüfung nicht verfügbar ist, muss für den Abschluss der Lieferung ein entsprechendes Verfahren implementiert sein.

• Beachten Sie die Dokumentation der Adressprüfungs-APIs.
  

Suche nach FedEx Stationen

• Grenzen Sie die Suche mithilfe spezifischer Attribute (z. B. Stationstyp, angebotene Services) auf geeignete Stationen ein. So lassen sich auch die Antwortzeiten verkürzen.
• Beachten Sie die Dokumention der APIs für die FedEx Stationssuche.
  

Abholanfrage

• Geben Sie als Abholzeit keine Uhrzeiten oder Daten ein, die in der Vergangenheit liegen. Geben Sie zum Buchen einer Abholung auch keine Daten ein, die zu weit in der Zukunft liegen.
• Anonyme Abholungen sind nicht zulässig.
  
• Beachten Sie die Dokumentation für die Abholanfrage-APIs.
  

Serviceverfügbarkeit

• Wenn Sie Ergebnisse für mehrere Betriebsgesellschaften wie FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) und FedEx Ground® Economy abrufen möchten, vermeiden Sie die Angabe des carrierCodes-Elements oder senden Sie separate Anfragen zur Service-Verfügbarkeit. Es können nicht mehrere Frachtführer-Codes angegeben werden.
• Stellen Sie die Vorabgenehmigung für Einzelpaletten über 68,5 kg und für ein Palettengesamtgewicht über 998 kg sicher.
  
• Mit der Festlegung der variablen Optionen auf SATURDAY_DELIVERY erhalten Sie sowohl Optionen für die Samstagszustellung als auch reguläre Optionen für alle Services mit optionaler Samstagszustellung. Wenn Sie SATURDAY_DELIVERY für spezielle Services festlegen, werden hingegen nur entsprechende Optionen mit Samstagszustellung zurückgegeben.
• Beachten Sie die Dokumentation für die Serviceverfügbarkeits-APIs.

Kunden-Support

Wenn Sie Fragen haben oder Unterstützung benötigen, helfen wir Ihnen gerne weiter. Auf unserer Support-Seite stellen wir Ressourcen und Kontaktinformationen bereit.