Upload di file

Alcune operazioni API non ricevono direttamente il file binario nella chiamata principale. In questi casi il flusso corretto è sempre in tre passaggi:

1. caricare prima il file con l'endpoint dedicato POST /api/v3/upload;
2. leggere l'upload_id restituito in risposta;
3. usare quell'ID nella richiesta successiva, nel campo che rappresenta il documento da allegare.

In pratica, il file viene caricato una sola volta e poi richiamato tramite il suo identificativo numerico.

informazioni

Nella specifica OpenAPI allegata, POST /api/v3/upload documenta in modo chiaro lo scopo dell'endpoint e la struttura della risposta, che include upload_id e i metadati del file. Alcune richieste PEC usano poi campi come contract_upload_id, identity_document_upload_id e order_module_upload_id per riferirsi ai documenti già caricati.

Come funziona il flusso

Quando una chiamata richiede un documento, non devi inserire il contenuto del file dentro il JSON della richiesta finale. Devi invece:

• caricare il file con l'endpoint di upload;
• conservare l'ID restituito;
• passare quell'ID nel campo previsto dalla chiamata applicativa.

Questo approccio ha due vantaggi:

• separa il caricamento del file dalla logica della richiesta principale;
• permette all'API di trattare i documenti come risorse già registrate, identificate in modo univoco.

1. Caricare il file

Il primo passaggio è chiamare POST /api/v3/upload.

Esempio

L'esempio seguente mostra il flusso operativo atteso: si invia un file all'endpoint dedicato e si ottiene in risposta il suo identificativo.

curl --request POST \
  --url 'https://api.shellrent.com/api/v3/upload' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --form '[email protected]'

Esempio di risposta

{
  "error": 0,
  "message": "",
  "data": {
    "upload_id": 987654,
    "mimetype": "application/pdf",
    "filename": "8f1f0e5d7c2a4b3e.pdf",
    "original_filename": "modulo-ordine.pdf",
    "file_extension": "pdf",
    "upload_date": "2026-04-15 10:30:00"
  }
}

Il valore davvero importante, per i passaggi successivi, è upload_id.

2. Usare l'ID del file in una richiesta successiva

Dopo l'upload, il file non va più reinviato. Nella chiamata applicativa devi passare il suo ID numerico.

Caso reale previsto dalla specifica

Nella specifica OpenAPI ci sono già richieste che funzionano in questo modo. Ad esempio, nelle richieste di cambio intestatario PEC sono presenti campi come:

• contract_upload_id
• identity_document_upload_id
• order_module_upload_id

Questi campi non contengono il file, ma l'ID del file già caricato con POST /api/v3/upload.

Esempio illustrativo con POST /api/v3/shop/pec

Per mostrare con chiarezza il meccanismo, puoi usare anche un esempio descrittivo su POST /api/v3/shop/pec.

warning

Nella specifica OpenAPI attuale, POST /api/v3/shop/pec è documentata con il solo campo service_id. Nell'esempio seguente aggiungiamo volutamente un oggetto data solo a scopo illustrativo, per mostrare come si passa l'ID di un file caricato in una richiesta business.

Esempio

{
  "service_id": 123,
  "data": {
    "company_name": "Azienda Demo Srl",
    "contact_email": "[email protected]",
    "requested_mailbox": "[email protected]",
    "identity_document_upload_id": 987654
  }
}

In questo esempio:

• il file è già stato caricato in precedenza;
• 987654 è l'ID restituito da POST /api/v3/upload;
• la richiesta finale passa solo quell'ID, non il contenuto del file.

Buone pratiche

Per evitare errori, è consigliabile:

• completare prima tutti gli upload necessari;
• salvare gli upload_id restituiti;
• usare nomi file chiari, così da riconoscere più facilmente i documenti caricati;
• verificare sempre di associare il file corretto al campo corretto della richiesta finale.

In sintesi

Quando una API richiede un documento:

• carica prima il file con POST /api/v3/upload;
• recupera l'upload_id dalla risposta;
• usa quell'ID nella chiamata successiva.

È questo il pattern da seguire ogni volta che un endpoint richiede un file tramite un campo dedicato come *_upload_id.