L'API Sottoscrizione dei numeri di monitoraggio alla Visibilità integrata avanzata consente agli abbonati a Visibilità integrata avanzata di associare i numeri di monitoraggio a un progetto webhook usando endpoint API. La funzionalità Associazione dei numeri di monitoraggio supporta due metodi di elaborazione:

• Associazione dei numeri di monitoraggio – Sincrona restituisce i risultati di elaborazione all'interno della stessa risposta HTTP. Questa opzione è adatta soprattutto alle applicazioni che richiedono una conferma immediata quando si associa un numero più piccolo di numeri di monitoraggio. 
• Associazione dei numeri di monitoraggio – Asincrona invia la richiesta per l'elaborazione in background e restituisce un ID processo che consente di recuperare lo stato di elaborazione e i risultati in un secondo momento. Questa opzione è ideale per l'elaborazione di batch più grandi di numeri di monitoraggio. 

Scegliete il metodo di elaborazione più idoneo ai requisiti in termini di prestazioni e carico di lavoro dell'applicazione.

Nota:

• È necessario l'accesso di amministratore o collaboratore al progetto Visibilità integrata avanzata
• Maggiori informazioni sulla Visibilità integrata avanzata e sulle sue funzionalità sono disponibili nella pagina della documentazione sulla Visibilità integrata avanzata.

L'API Sottoscrizione dei numeri di monitoraggio alla Visibilità integrata avanzata offre i seguenti vantaggi:

• La possibilità di associare, aggiornare e gestire facilmente i numeri di monitoraggio del progetto webhook di Visibilità integrata avanzata attraverso endpoint API.
• La possibilità di associare diversi numeri di monitoraggio in un'unica richiesta API anziché elaborare ciascun numero di monitoraggio singolarmente.
• La scelta tra l'elaborazione sincrona per ottenere risultati immediati e l'elaborazione asincrona per le operazioni di batch più grandi.

Usate i seguenti endpoint per gestire il progetto Visibilità integrata avanzata:

• Associazione dei numeri di monitoraggio – Sincrona: consente di associare i numeri di monitoraggio a un webhook e di ricevere lo stato di elaborazione finale all'interno della stessa risposta HTTP.
• Associazione dei numeri di monitoraggio – Asincrona: consente di associare i numero di monitoraggio a un webhook e di usare in seguito il valore jobId restituito per verificare lo stato del processo asincrono o scaricare i dettagli con gli endpoint correlati:    
  • Stato dei processi dei numeri di monitoraggio
  • Dettagli del processo dei numeri di monitoraggio

Queste API sono disponibili nella panoramica del progetto Visibilità integrata avanzata.

Queste API sono accessibili solo attraverso la panoramica del progetto, come illustrato nello screenshot precedente.

La tabella seguente riassume le differenze tra gli endpoint di Associazione dei numeri di monitoraggio sincroni e asincroni.
 

Usate l'endpoint sincrono se avete bisogno di una conferma immediata per batch più piccoli di numeri di monitoraggio. Usate l'endpoint asincrono per elaborare batch più grandi che non richiedono una risposta immediata.

Usate questo endpoint per associare uno o più numeri di monitoraggio a un progetto webhook di Visibilità Integrata Avanzata e ricevere i risultati di elaborazione all'interno della stessa risposta HTTP.

Questo endpoint è destinato alle applicazioni che richiedono una conferma immediata e supporta richieste contenenti fino a 150 numeri di monitoraggio.

Input richiesto: 

• subscriptionID
• trackingNumber

Vantaggi

L'endpoint sincrono offre i seguenti vantaggi:

• Risultati di elaborazione immediati
• Informazioni dettagliate su esito positivo e negativo in un'unica risposta
• Supporto per un massimo di 150 numeri di monitoraggio a richiesta
• Validazione della richiesta e applicazione delle regole aziendali prima dell'elaborazione
• Codici di errore leggibili a macchina e messaggi di errore descrittivi
• ID transazioni per il tracciamento delle richieste e la risoluzione dei problemi

L'endpoint Associazione dei numeri di monitoraggio - Sincrona applica diverse regole di convalida, tra cui:

• Necessità di un valore subscriptionId valido e attivo
• Autorizzazione a inserire un solo valore subscriptionId a richiesta
• Necessità di un valore trackingNumber
• Controllo che i numeri di monitoraggio corrispondano ai requisiti di formattazione di FedEx, incluso il limite di numero di monitoraggio compreso tra 6 e 22 caratteri

Le risposte di errore seguono una struttura coerente con errors[] contenente codice e messaggio per semplificare l'analisi.

"errors": [

{

"code": "ERROR.CODE",

"message": "Descriptive error message"

}

L'endpoint Associazione del numero di transazione – Sincrona accetta le operazioni parzialmente riuscite. Se alcuni numero di monitoraggio hanno esito negativo, l'API Sincrona restituisce comunque 200 OK e visualizza quanto segue:

• failedTrackingNumbers
• Un messaggio descrittivo

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "Below tracking numbers failed to upload due to validation or system errors"

      }

    }

Ulteriori dettagli e regole sono disponibili nelle sezioni sulle regole aziendali.

Questo endpoint consente di inviare uno o più numeri di monitoraggio per l'elaborazione in background.

La richiesta restituisce un ID processo che è possibile usare con l'endpoint Stato del processo del numero di monitoraggio per monitorare l'elaborazione e con l'endpoint Dettagli del processo del numero di monitoraggio per scaricare i risultati di elaborazione al termine del processo.

Input richiesto:

• Azione
• Dettagli del numero di monitoraggio

È possibile associare fino a 1.000 numeri di monitoraggio in una singola richiesta.

Vantaggi

L'endpoint asincrono offre i seguenti vantaggi:

• Supporta l'invio di grandi batch con fino a 1.000 numeri di monitoraggio
• Permette di elaborare richieste di lunga durata in background
• Consente di monitorare lo stato del processo e di ottenere report di elaborazione scaricabili
• Elimina i problemi di timeout delle richieste per carichi di lavoro elevati

Questo endpoint consente di ottenere lo stato di un processo asincrono (una o più richieste consecutive in coda) o lo stato di tutti i processi inviati.

Le informazioni di input necessarie per questa richiesta sono:

• jobID : specificate l'ID del processo di cui si intende recuperare lo stato.

Nota: l'ID processo è un input facoltativo per questo endpoint. Se non specificate l'ID processo, otterrete lo stato di tutti i processi inviati.

La risposta corretta a tale richiesta restituirà i valori di jobID, stato attuale del processo e marcatura oraria di creazione e completamento del processo. La risposta mostrerà lo stato attuale dei processi. Inoltre, conterrà messaggi di esito positivo, errori o avvisi affinché gli utenti possano visualizzarli e risolverli a seconda del caso.

• Se lo stato del processo visualizzato è COMPLETATO, tutti i numeri di monitoraggio sono stati convalidati ed elaborati correttamente.
  • Lo stato COMPLETATO implica che i numeri di monitoraggio sono stati convalidati ed elaborati correttamente. Non implica che tutti i numeri di monitoraggio siano stati correttamente aggiunti al progetto Visibilità integrata avanzata.
  • Per i lavori con più numeri di monitoraggio, lo stato può essere considerato COMPLETATO anche se per alcuni numeri l'associazione al progetto ha esito negativo e per altri ha esito positivo. Per confermare lo stato di ciascun numero di monitoraggio nella richiesta di associazione originale, scaricate il report della batch.

Nota: se lo stato del processo indicato è NON RIUSCITO, a causa di vari motivi/guasti fisici non è stato possibile elaborare la richiesta e l'utente deve effettuare un nuovo tentativo.

La tabella seguente mostra gli stati del processo e le rispettive descrizioni:

Questo endpoint consente di scaricare il report JSON di un processo asincrono con stato COMPLETATO.

Le informazioni di input richieste associate a questa richiesta sono:

• jobID : specificate l'ID del processo di cui si intende recuperare lo stato. Un ID processo è obbligatorio per questo endpoint.

Nota:

• È possibile scaricare un solo report di processo asincrono alla volta.
• Se il processo non è COMPLETATO e tentate di scaricare il report, verrà visualizzato un messaggio di errore.

La risposta corretta alla richiesta fornisce il report del processo in formato JSON.

Regole aziendali comuni

• Non è previsto alcun limite al totale di numeri di monitoraggio che si possono associare a un progetto Visibilità integrata avanzata.
• I numeri di monitoraggio associati a un progetto Visibilità integrata avanzata vengono dissociati 40 giorni dopo essere stati associati al webhook.
• Le informazioni di monitoraggio protette, quali indirizzo del destinatario, firma del destinatario e informazioni sensibili sulla consegna, non sono disponibili tramite l'API Sottoscrizione dei numeri di monitoraggio.

Regole aziendali per l'endpoint sincrono

• Un massimo di 150 numeri di monitoraggio a richiesta.
• Tutti i numeri di monitoraggio devono usare lo stesso valore subscriptionId.
• La sottoscrizione al webhook di Visibilità integrata avanzata specificata deve essere valida e attiva.
• Le richieste sono soggette a un timeout di 30 secondi.

Regole aziendali per l'endpoint asincrono

• Un massimo di 1.000 numeri di monitoraggio a richiesta.
• Lo stato e i dettagli del processo di una richiesta asincrona vengono conservati per 90 giorni dopo che i numeri di monitoraggio sono stati associati al webhook di Visibilità integrata avanzata.