De API voor op trackingnummer gebaseerd abonnement voor Geavanceerde geïntegreerde zichtbaarheid stelt abonnees van Geavanceerde geïntegreerde zichtbaarheid in staat om trackingnummers te koppelen aan een webhook-project via API-eindpunten. De mogelijkheid om trackingnummers te koppelen ondersteunt twee verwerkingsmethoden:

• Trackingnummerkoppeling – Synchroon retourneert de verwerkingsresultaten binnen dezelfde HTTP-respons. Deze optie is het beste geschikt voor toepassingen die directe bevestiging vereisen bij het koppelen van een kleiner aantal trackingnummers. 
• Trackingnummerkoppeling – Asynchroon dient het verzoek voor achtergrondverwerking in en retourneert een taak-ID waarmee later de verwerkingsstatus en resultaten kunnen worden opgevraagd. Deze optie is het meest geschikt voor het verwerken van grotere batches met trackingnummers. 

Kies de verwerkingsmethode die het beste voldoet aan de prestaties en werklastvereisten van uw toepassing.

Opmerking:

• U moet toegang als beheerder of bijdrager hebben voor uw Geavanceerde geïntegreerde zichtbaarheid-project
• Ga naar de pagina Documentatie over Geavanceerde geïntegreerde zichtbaarheid voor meer informatie over Geavanceerde geïntegreerde zichtbaarheid en zijn functies.

De API voor een op trackingnummer gebaseerd abonnement voor Geavanceerde geïntegreerde zichtbaarheid biedt de volgende voordelen:

• U kunt eenvoudig trackingnummers koppelen, bijwerken en beheren voor uw Geavanceerde geïntegreerde zichtbaarheid-webhookproject via de API-eindpunten.
• Koppel meerdere trackingnummers aan één API-verzoek in plaats van elk trackingnummer afzonderlijk te verwerken.
• U kunt kiezen tussen synchrone verwerking voor directe resultaten of asynchrone verwerking voor grotere batchbewerkingen.

Gebruik de volgende eindpunten om uw Geavanceerde geïntegreerde zichtbaarheid-project te beheren:

• Trackingnummerkoppeling – Synchroon: stelt u in staat trackingnummers aan een webhook te koppelen en de uiteindelijke verwerkingsstatus binnen dezelfde HTTP-respons te ontvangen.
• Trackingnummerkoppeling – Asynchroon: hiermee kunt u trackingnummers koppelen aan een webhook en de geretourneerde jobId later gebruiken om de status van de asynchrone taak te controleren of details te downloaden via de bijbehorende eindpunten:    
  • Taakstatus voor trackingnummer
  • Taakgegevens voor trackingnummer

Deze API's zijn beschikbaar via uw Geavanceerde geïntegreerde zichtbaarheid-projectoverzicht.

Deze API's kunnen alleen worden geopend via uw projectoverzicht, zoals weergegeven in de schermafbeelding hierboven.

De volgende tabel vat de verschillen samen tussen de synchrone en asynchrone eindpunten voor het koppelen van trackingnummers.
 

Gebruik het synchrone eindpunt wanneer u onmiddellijke bevestiging nodig hebt voor kleinere batches met trackingnummers. Gebruik het asynchrone eindpunt bij het verwerken van grotere batches die geen onmiddellijke reactie vereisen.

Gebruik dit eindpunt om één of meer trackingnummers te koppelen aan een webhookproject voor Geavanceerde geïntegreerde zichtbaarheid en ontvang de verwerkingsresultaten binnen dezelfde HTTP-respons.

Dit eindpunt is bedoeld voor applicaties die onmiddellijke bevestiging vereisen en ondersteunt verzoeken met maximaal 150 trackingnummers.

Vereiste invoer: 

• subscriptionID
• trackingNumber

Voordelen

Het synchrone eindpunt biedt de volgende voordelen:

• Onmiddellijke verwerkingsresultaten
• Gedetailleerde informatie over succes en mislukking in één respons
• Ondersteuning voor maximaal 150 trackingnummers per verzoek
• Verzoek om validatie en handhaving van bedrijfsregels voor verwerking
• Machinaal leesbare foutcodes en beschrijvende foutmeldingen
• Transactie-ID's voor het traceren van aanvragen en het oplossen van problemen

De koppeling van trackingnummers – synchrone eindpunt handhaaft meerdere validatieregels, waaronder:

• Vereist een geldige en actieve subscriptionId
• Er is maar één subscriptionId per verzoek toegestaan
• Vereist een trackingNumber
• Zorgt ervoor dat trackingnummers voldoen aan de opmaakvereisten van FedEx, waaronder de maximale trackingnummerlimiet van 6 tot 22 cijfers

Foutreacties volgen een consistente structuur met errors[] met code en bericht voor eenvoudige parsering.

"errors": [

{

"code": "ERROR.CODE",

"message": "Beschrijvende foutmelding"

}

De koppeling van trackingnummers – synchrone eindpunt maakt gedeeltelijke successen mogelijk. Wanneer sommige trackingnummers falen, retourneert de synchrone API nog steeds 200 OK en toont het volgende:

• failedTrackingNumbers
• Een beschrijvend bericht

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "De onderstaande trackingnummers zijn niet geüpload vanwege validatie- of systeemfouten"

      }

    }

Ga naar de secties over bedrijfsregels voor meer informatie en regels.

Gebruik dit eindpunt om een of meer geabonneerde trackingnummers in te dienen voor achtergrondverwerking.

Het verzoek retourneert een taak-ID die u kunt gebruiken met het eindpunt Taakstatus trackingnummer om de verwerking te monitoren en met het eindpunt Taakdetails trackingnummer om verwerkingsresultaten te downloaden nadat de taak is voltooid.

Vereiste invoer:

• Actie
• Details van trackingnummer

U kunt maximaal 1.000 trackingnummers koppelen in één verzoek.

Voordelen

Het asynchrone eindpunt biedt de volgende voordelen:

• Ondersteunt grote batch-inzendingen tot 1.000 trackingnummers
• Maakt het mogelijk om langlopende aanvragen op de achtergrond te verwerken
• Maakt controle van de taakstatus en downloadbare verwerkingsrapporten mogelijk
• Elimineert problemen met time-outs bij grote werkbelastingen

Gebruik dit eindpunt om de status van een asynchrone taak (een of meer opeenvolgende verzoeken in de wachtrij) of de status van alle ingediende taken op te halen.

De vereiste invoerinformatie voor dit verzoek is:

• jobID– Geef de taak-ID op waarvan u de status wilt ophalen.

Let op: de taak-ID is een optionele invoer voor dit eindpunt. Als u de taak-ID niet opgeeft, dan krijgt u de status van alle ingediende taken.

De succesvolle respons voor dit verzoek zal de jobID, de huidige taakstatus en de taakcreatie en de taakvoltooiingstijdstempel retourneren. De respons zal de huidige status van de taken weergeven. De respons zal ook de succesberichten, fouten of waarschuwingen voor gebruikers bevatten die ze kunnen bekijken en oplossen, indien van toepassing.

• Als de taakstatus wordt weergegeven als VOLTOOID, dan betekent dat dat alle trackingnummers zijn gevalideerd en verwerkt.
  • De status VOLTOOID geeft aan dat de trackingnummers zijn gevalideerd en verwerkt. Het betekent niet dat alle trackingnummers zijn toegevoegd aan het Geavanceerde geïntegreerde zichtbaarheid-project.
  • Voor taken met meerdere trackingnummers kan de status als voltooid worden beschouwd, zelfs als sommige nummers niet aan het project worden gekoppeld en andere wel. Download het batchrapport om de status van elk trackingnummer in het oorspronkelijke koppelingsverzoek te bevestigen.

Let op: als de taakstatus wordt weergegeven als MISLUKT, betekent dit dat het verzoek vanwege uiteenlopende redenen/ernstige fouten niet kon worden verwerkt en dat de gebruiker het opnieuw moet proberen.

De volgende tabel toont de functiestatussen en hun respectievelijke beschrijvingen:

Gebruik dit eindpunt om het JSON-rapport voor een asynchrone taak met de status VOLTOOID te downloaden.

De vereiste invoergegevens die bij dit verzoek horen, zijn:

• jobID– Geef de taak-ID op waarvan u de status wilt ophalen. Een taak-ID is verplicht voor dit eindpunt.

Opmerking:

• U kunt maar één asynchroon functierapport tegelijk downloaden.
• Als de taak niet VOLTOOID is en u het rapport probeert te downloaden, dan zal er een foutbericht worden weergegeven.

De succesvolle respons voor dit verzoek geeft u het rapport van de taak in JSON-indeling.

Algemene bedrijfsregels

• Er is geen limiet op het totale aantal trackingnummers dat kan worden gekoppeld aan een project voor Geavanceerde geïntegreerde zichtbaarheid.
• Trackingnummers die gekoppeld zijn aan een project voor Geavanceerde geïntegreerde zichtbaarheid worden 40 dagen nadat ze succesvol aan de webhook zijn gekoppeld, ontkoppeld.
• Beveiligde trackinginformatie, zoals het adres van de ontvanger, de handtekening van de ontvanger en gevoelige leveringsinformatie, is niet beschikbaar via de API voor trackingnummerabonnementen.

Bedrijfsregels voor het synchrone eindpunt

• Maximaal 150 trackingnummers per aanvraag.
• Alle trackingnummers moeten dezelfde abonnements-ID gebruiken.
• Het gespecificeerde webhookabonnement voor Geavanceerde geïntegreerde zichtbaarheid moet geldig en actief zijn.
• Verzoeken zijn onderhevig aan een time-out van 30 seconden.

Bedrijfsregels voor het asynchrone eindpunt

• Maximaal 1.000 trackingnummers per verzoek.
• De taakstatus en taakdetails voor een asynchroon verzoek worden 90 dagen bewaard nadat de trackingnummers succesvol zijn gekoppeld aan de Geavanceerde geïntegreerde zichtbaarheid-webhook.