Cele mai bune practici de integrare a API-urilor FedEx

Acesta este un ghid rapid de referință care are scopul de a ajuta consumatorii API să înțeleagă modalitățile de îmbunătățire a experienței de integrare cu FedEx și de asigurare a calității soluției de integrare în ceea ce privește designul, viteza și securitatea.

Pentru a integra eficient cu API-urile FedEx, dezvoltatorii ar trebui să urmeze cele mai bune practici de integrare prezentate în cele ce urmează:

URI-uri API

• Există URI-uri API separate pentru testare și producție. 
• Dezvoltatorii ar trebui să utilizeze URI-urile de testare pentru testarea dezvoltării și integrării și URI-urile de producție pentru producție.

URI-urile API sunt enumerate în lista următoare:

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

Producție: https://apis.fedex.com/

Gestionarea acreditărilor

• Cheia API și cheia secretă

• Cheia API și cheia secretă sunt utilizate pentru a vă identifica aplicația și trebuie utilizate în solicitarea tokenului OAuth.

1. Cheia API și cheia secretă ar trebui păstrate în siguranță. Nu distribuiți cheia API sau cheia secretă prin e-mail sau prin codul distribuit, inclusiv JavaScript pe partea client.
2. Aplicația dvs. va fi compromisă dacă cheia API sau cheia secretă sunt furate. Dacă suspectați că acreditările dvs. sunt furate sau compromise, recreați imediat cheia secretă.
3. Evitați să înregistrați în jurnal informații sensibile precum cheia secretă.

• Nu codați hard cheia API și cheia secretă în codul dvs.
• Aplicația dvs. ar trebui să fie capabilă să actualizeze dinamic cheia API și cheia secretă.
• Acreditările clientului ar trebui stocate într-un seif/un loc sigur, pentru a nu putea fi compromise.

• Tokenul OAuth

• Tokenul de acces ar trebui stocat doar pe serverul aplicației web și nu trebuie expus browserului.
• Nu codificați hard tokenul în aplicațiile dvs.
• Securizați tokenurile de acces pentru a evita compromiterea lor.
• Evitați apelurile multiple către API-ul cu tokenul OAuth pentru un nou token de acces. Este recomandat să memorați în cache tokenul de acces până când codul de eroare HTTP 401 este observat. Regenerați tokenul OAuth în orice moment.
• Nu expuneți tokenul utilizatorului final sau aplicației.
• Utilizați protocolul HTTPS pentru orice tranzacție API.

Practici de codare

• Pentru a menține conformitatea cu cel mai recent și cel mai securizat protocol de comunicații cu criptare de date, este recomandat să se utilizeze Transport Layer Security (TLS), versiunea 1.2 sau o versiune ulterioară.
• Nu uitați să setați antetele API necesare pentru fiecare solicitare API. Veți găsi informațiile privind antetele pe pagina cu documentația pentru fiecare API. 
• „Content-Type” din HTTP POST ar trebui să fie „application/json”.
• Recurgeți la codul eșantion pentru a începe lucrul cu fiecare API. Fiecare punct final API este însoțit de mai multe eșantioane care vă vor ajuta să înțelegeți elementele și formatele obligatorii și alte detalii.
• Atunci când utilizatorii sau dezvoltatorii trimit valori cu multe zecimale, pot apărea erori neobișnuite. Pentru greutate și valoare monetară/sumă, sunt permise doar două poziții explicite pentru zecimale. Dimensiunile – precum lungimea, lățimea și înălțimea – nu acceptă zecimalele.

Exemplu: Greutate: 45,26, valoare monetară/sumă: 100,52, lungime: 10, lățime: 25, înălțime: 15.

• Evitați să trimiteți elemente necompletate.

Exemplu: “Streetlines”:””

• Trimiteți doar datele necesare pentru a procesa solicitarea.

De exemplu, pentru o expediere internă în SUA, evitați să trimiteți factura comercială și datele privind marfa care ar putea fi obligatorii doar pentru expedierile internaționale.

• În cursul dezvoltării, determinați care să fie reacția în cazul în care un element de răspuns neobligatoriu, precum un tarif, nu este returnat. Evaluați răspunsul tranzacției cu privire la elementele absente înainte de a utiliza datele.

De exemplu, este posibil să expediați un colet dacă evaluarea nu este funcțională. Testați răspunsul tranzacției cu privire la elementele absente înainte de a utiliza datele.

• În general, evitați dependențele hard la integrarea API-urilor FedEx, după caz.
• Pentru a reduce latența și a obține rezultate exacte, ar trebui utilizate următoarele:
  
  • Filtrare - Utilizați această opțiune pentru a restrânge căutarea cu parametri pe care-i căutați.
  • Sortare - Utilizați această opțiune pentru a sorta rezultatele după un anumit parametru, în ordine crescătoare sau descrescătoare.
• Verificați dacă acele câmpuri obligatorii – precum codul poștal al destinatarului și greutatea coletului – conțin date, înainte de a trimite tranzacția. Validați corectitudinea datelor pentru câmpul în cauză. Acest lucru va reduce erorile de tranzacție.
  

De exemplu, pentru codurile poștale din SUA, verificați dacă acest câmp conține numai date numerice și dacă este de forma unui număr de cinci cifre sau în formatul unui cod poștal ZIP+4.

• Pentru a evita efectul negativ asupra disponibilității și fiabilității sistemului FedEx:
  
  • Nu rulați testarea performanței în mediul de testare sau cel de producție.
  • Stabiliți o logică de codare pentru a evita eșecul repetat al aceleiași tranzacții.
• Limita de restricție este setată la 1400 de tranzacții în 10 secunde. Dacă această limită este atinsă în primele câteva secunde, va fi returnat codul de eroare HTTP 429 Prea multe solicitări, iar tranzacțiile vor fi restricționate până când s-au scurs cele 10 secunde; tranzacțiile se vor relua apoi.
  

De exemplu, dacă primim 1400 de solicitări în primele patru secunde, un cod de eroare HTTP 429 Prea multe solicitări - „Am primit prea multe solicitări într-un interval scurt. Așteptați puțin și încercați din nou.” va fi returnat, iar tranzacțiile vor fi restricționate în următoarele șase secunde, după care se vor relua.

• Nu codați hard regulile de business, precum tipuri de servicii, tipuri de colete, limite de greutate etc. pentru expedieri, deoarece acestea pot suferi modificări.

Tratarea erorilor

Fiecare răspuns API va conține un cod de stare HTTP și o sarcină răspuns. Unele răspunsuri vor fi însoțite de o eroare, un avertisment sau o notă, după caz. Avertismentele și notele nu indică un eșec; cu toate acestea, mesajul de eroare sau de avertizare ar trebui înregistrat în jurnal și analizat. Prin tratarea corespunzătoare a erorilor, vă veți asigura că integrarea cu FedEx decurge fără probleme și veți putea evita deteriorările.

Coduri de stare HTTP

Tarif

• Există două modalități de a obține un tarif:
  
  • Tarif pentru un anumit serviceType (tip de serviciu) - Rezultatele vor fi filtrate de valoarea serviceType (tip de serviciu) indicată. Acest lucru va reduce dimensiunea răspunsului și va scădea timpul de răspuns al tranzacției.
    

    Exemplu: STANDARD_OVERNIGHT

  • Comparare tarife – Dacă nu se indică niciun serviceType (tip de serviciu), atunci toate serviciile aplicabile și tarifele corespunzătoare vor fi returnate.
• Utilizați API-ul de disponibilitate a serviciilor pentru a determina ce servicii, opțiuni de colet și servicii speciale sunt disponibile pentru o anumită pereche origine-destinație și verificați serviceType (tipul de serviciu) și opțiunea de colet în solicitarea tarifelor.
  

  De exemplu, STANDARD_OVERNIGHT (printre altele) nu este disponibilă între toate codurile poștale.

• Pentru a se aplica un serviciu special pentru o expediere, trebuie incluse tipul serviciului special și detaliile despre acesta.
  
  • Notă: Unele servicii speciale nu au detalii.
• Vizualizați Documentația API pentru tarife.

Expediere

• Utilizați API-ul de disponibilitate a serviciilor pentru a determina ce servicii sunt disponibile pentru o anumită pereche origine-destinație și verificați serviceType (tipul de serviciu) și opțiunea de colet în solicitarea de expediere.
• Pentru a se aplica un serviciu special pentru o expediere, trebuie incluse tipul serviciului special și detaliile despre acesta.
  
  • Notă: Unele servicii speciale nu au detalii.
• Efectuați închiderea pentru FedEx Ground la sfârșitul zilei de expediere înainte de a fi preluată expedierea.
  
• Vizualizați Documentația API-ului de expediere.
  

Urmărire

• Limitați la 30 numărul de numere de urmărire dintr-o solicitare cu traseu unic. Acest lucru va reduce dimensiunea răspunsului și va scădea timpul de răspuns al tranzacției.
• Limitați numărul de ocazii în care este urmărit un colet la volumul necesar în scopul afacerilor.
• Pentru urmărirea lotului, eliminați orice colete care au returnat starea de urmărire „livrat” din lot.
• Consultați Documentația API de urmărire.

Validarea adresei

• FedEx oferă validarea adresei ca o sugestie, nu ca o identificare finală. Utilizatorul final trebuie să stabilească, în cele din urmă, dacă o adresă este utilizabilă, din datele furnizate și nevoile sale de afaceri. Trebuie să existe un proces care să trateze adresele care nu pot fi validate, astfel încât comenzile să poată fi procesate în continuare.
• Pentru a asigura o experiență de expediere mai bună, nu stabiliți ca procesul de expediere să depindă de servicii opționale, precum validarea adresei.

De exemplu, dacă API-ul de validare a adresei nu este disponibil în momentul introducerii comenzii sau al expedierii, ar trebui să fie instituită o contingență pentru a finaliza expedierea.

• Consultați Documentația API-ului de validare a adresei.
  

Căutarea locațiilor FedEx

• Restrângeți căutarea furnizând atribute specifice (și anume, tipul locației, serviciile oferite etc.) pentru a obține opțiuni de locație adecvate și un timp de răspuns mai rapid.
• Vizualizați documentația API-ului de căutare a locațiilor FedEx.
  

Solicitare de preluare

• Nu introduceți o ora trecută a pregătirii coletului, o data trecută sau o dată care este prea îndepărtată în viitor pentru programarea unei preluări.
• Preluările anonime nu sunt permise.
  
• Consultați Documentație API de solicitare de preluare.
  

Disponibilitatea serviciilor

• Pentru a obține rezultate pentru mai multe companii de operare, precum FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) și FedEx Ground® Economy, fie omiteți elementul carrierCodes, fie trimiteți solicitări separate de disponibilitate a serviciilor, deoarece nu se pot specifica mai multe coduri de transportator.
• Asigurați-vă că aveți aprobare prealabilă pentru paleți individuali de 151 lb sau mai mult și paleți care depășesc 2.200 lb.
  
• Dacă specificați SATURDAY_DELIVERY la opțiunile variabile, veți obține atât opțiunile Livrare sâmbătă, cât și opțiunile regulate pentru toate serviciile în care livrarea de sâmbătă este o opțiune. Nu specificați SATURDAY_DELIVERY pentru servicii speciale, în caz contrar, se vor returna doar orice opțiuni Livrare sâmbătă aplicabile.
• Consultați Documentația API de disponibilitate a serviciilor.

Asistență clienți

Dacă aveți întrebări sau aveți nevoie de asistență, suntem aici pentru a vă ajuta! Accesați pagina noastră Asistență pentru resurse și informații despre modalitățile de a ne contacta.