Accesso all’account e ai documenti
Scaricare un allegato esistente da un progetto di portabilità di proprietà del proprio account API. Utilizzare un account API abilitato tramite HTTPS da un indirizzo IP consentito. Il progetto non deve essere stato eliminato. L’identificativo del documento viene cercato all’interno di quel progetto; non è un collegamento pubblico globale per il download.
Identificare il documento
Leggere la risposta con i dettagli del progetto e utilizzare una voce del relativo elenco uploads. La voce include il valore numerico di id, il nome originale del file, l’estensione memorizzata e il valore relativo di download_url. Utilizzare il valore del progetto uniqueid e l’identificativo di quel caricamento, non l’identificativo numerico della riga del progetto né quello di una riga relativa a un numero telefonico.
Risolvere un URL relativo restituito esclusivamente rispetto all’host API configurato e attendibile. Il download richiede la stessa autenticazione dell’account; i metadati del documento non consentono l’accesso senza autenticazione.
Inviare la richiesta e salvare la risposta
Impostare PROJECT_ID e DOCUMENT_ID sui valori del progetto del proprio account. Applicare la codifica URL all’identificativo del progetto. Questo esempio salva separatamente i byte e le intestazioni della risposta, utilizzando un nome locale di destinazione fisso anziché fidarsi del nome del file allegato.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--dump-header document-headers.txt \
--output porting-document.bin \
"https://api.multitel.net/v3/lnp/project/$PROJECT_ID/document/$DOCUMENT_ID"La richiesta è di tipo GET e non ha un corpo. Legge un singolo allegato completo, senza paginazione specifica dell’endpoint, senza una struttura contenitore JSON e senza un contratto documentato per il download di intervalli di byte.
Risposta binaria e intestazioni
In caso di successo, il corpo contiene i byte memorizzati dell’allegato dopo la decodifica prevista dall’archiviazione preesistente, non dati base64 né un oggetto di risposta JSON. Il metodo invia un’intestazione Content-Disposition per l’allegato utilizzando il nome del file memorizzato, dal quale vengono rimosse le virgolette doppie. L’intestazione non garantisce un percorso di file locale sicuro o codificato secondo gli standard; scegliere autonomamente il nome del file di destinazione.
| Estensione memorizzata | Content-Type |
|---|---|
| application/pdf | |
| png | image/png |
| jpg, jpeg | image/jpeg |
| doc | application/msword |
| Altri valori | application/octet-stream |
Il confronto delle estensioni non distingue tra maiuscole e minuscole. Il tipo MIME viene scelto in base all’estensione memorizzata, non mediante l’ispezione del contenuto, e non garantisce che il documento sia valido.
Verificare il file scaricato
- Controllare sia lo stato HTTP sia le intestazioni della risposta. Gli errori di autenticazione o di ricerca possono restituire una risposta JSON dell’API anziché un file. Non considerare qualsiasi corpo non vuoto o file salvato come prova del completamento corretto del download di un PDF.
- Se il corpo contiene un errore JSON, controllare
status.codeestatus.msg. Tenere separati i dati di errore dal documento previsto. - Verificare che il file ottenuto non sia vuoto e si apra come file del tipo previsto. Se si conserva l’originale, confrontarne la somma di controllo con quella della copia prima di fare affidamento su quest’ultima.
- Se il risultato è vuoto, non valido o diverso dall’originale, interrompere l’operazione e chiedere all’assistenza di controllare l’allegato memorizzato. Ripetere il download non risolve i problemi di archiviazione.
Compatibilità con l’archiviazione preesistente
L’attuale percorso di caricamento dell’API e i componenti di scrittura dei caricamenti del portale e dei sistemi preesistenti esaminati memorizzano i byte dei documenti applicando sequenze di escape. Questo download annulla tale trasformazione. I test offline del gestore effettivo preservano tutti i valori dei byte e le barre rovesciate letterali per quel formato di archiviazione.
Questo non costituisce una garanzia per ogni record storico o importato dall’esterno. Il gestore decodifica sempre il blocco binario memorizzato e non rileva se un record è stato importato senza le sequenze di escape previste. Inoltre, non ricorre a un percorso di file alternativo quando un record non contiene un blocco binario memorizzato. Questi record possono restituire byte alterati o un contenuto vuoto. Verificare il risultato e chiedere all’assistenza di esaminare l’allegato interessato, anziché modificare un documento del cliente o presumere che i suoi metadati dimostrino la disponibilità del file.
Il portale attuale utilizza prima questo percorso dell’API e dispone anche di ulteriori meccanismi locali alternativi. Un download riuscito dal portale non dimostra che ogni record preesistente possa essere scaricato direttamente tramite questa API.
Errori ed effetti
Un progetto inesistente, eliminato o non di proprietà del proprio account restituisce il codice API 404 con un messaggio che indica che il progetto non è stato trovato. Un caricamento inesistente all’interno di un progetto di proprietà del proprio account restituisce il codice API 404 con un messaggio che indica che il documento non è stato trovato. Leggere i corpi degli errori dell’API oltre allo stato HTTP. Per un record esistente che non contiene byte memorizzati utilizzabili, questo gestore non fornisce una risposta dedicata e affidabile che ne segnali il mancato reperimento.
L’endpoint esaminato legge un allegato. Non carica, modifica o rimuove documenti, non invia richieste di portabilità e non addebita importi all’account. Gli allegati di portabilità possono contenere informazioni sull’identità, sulla fatturazione o sulle autorizzazioni: mantenerli all’interno dei flussi di lavoro autorizzati dell’account ed escluderli dai registri pubblici, dai dati di analisi e dalle schermate della documentazione.