Per: Amministratori
Carica e allega file con una chiave hub
Ottieni un indirizzo di caricamento, carica un file, allegalo a un post, una nota, un'attività, un modulo o firma elettronicamente e scarica i file di un caso.
In questo articolo10 sezioni
Prima di iniziare
Questa pagina spiega come caricare file in un caso specifico, come aggiungerli al caso stesso e come scaricarli, utilizzando una chiave di accesso. I percorsi dei file sono indicati sotto https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.
Come funziona
Un file richiede tre passaggi: prima bisogna chiedere un indirizzo per il caricamento del file; poi il file viene caricato in quel luogo; infine, il file viene associato all’oggetto su cui si trova.
| Articolo | Indirizzo di caricamento | Allegare | Rimuovere |
|---|---|---|---|
| Un post | GET /posts/<post_id>/drive | PUT /posts/<post_id>/media | DELETE /posts/<post_id>/media |
| Una nota/commento | GET /notes/<note_id>/drive | PUT /notes/<note_id>/media | DELETE /notes/<note_id>/media |
| Un compito/obbligo | GET /tasks/<task_id>/drive | PUT /tasks/<task_id>/media | DELETE /tasks/<task_id>/media |
| Un compito per un bambino | GET /subtasks/<subtask_id>/drive | PUT /subtasks/<subtask_id>/media | DELETE /subtasks/<subtask_id>/media |
| Un documento di tipo modulo, firmato elettronicamente o scritto a mano. | GET /<forms, signs or notes>/<id>/drive con media_group=schemas | PUT /<forms, signs or notes>/<id>/schema/media | – |
- Una chiave può associare file soltanto alle poste create dall’Assistente Virtuale. È possibile associare i file a qualsiasi nota, compito o sottocompito.
- Per aggiungere un file a un commento, è necessario ottenere l’indirizzo del file, indicato tramite la tag
/drive, e poi utilizzare la tagPUT /<posts, signs, tasks or subtasks>/<id>/comments/<comment_id>/mediaper collegare il file al commento corrispondente. Una chiave può essere associata soltanto ai propri commenti. - Una forma o un file elettronico contiene soltanto un documento, e nessun altro file. Una volta che il documento è stato salvato nella forma o nel file elettronico, non viene creato alcun altro file, a meno che il primo documento non riesca a essere convertito correttamente.
1. Ottieni un indirizzo di caricamento
| Parametro | Cosa fa | Necessario | Predefinito |
|---|---|---|---|
media_group | Il tipo di file è uno dei seguenti: docs, images, audios, videos o files. Per i documenti relativi a moduli, firme elettroniche o note, il tipo di file può essere schemas. | Sì. | – |
media_extension | L’estensione del file è pdf. Deve trattarsi di un’estensione valida; files, invece, può indicare qualsiasi estensione. | Sì. | – |
tag_id | Il nome del file viene scritto in caratteri, numeri e trattini, ad esempio repair-estimate. | Sì. | – |
| Tipo | Estensioni |
|---|---|
docs e schemas | CSV, DOC, DOCX, ODT, PDF, PPT, PPTX, RTF, TXT, XLS, XLSX |
images | BMP, GIF, JPEG, JPG, PNG, SVG, TIFF, WebP |
audios | aac, aiff, amr, flac, m4a, mp3, oga, opus, wav, wma… e anche altri formati audio meno comuni. |
videos | Formati di video meno comuni: 3GP, AVI, FLV, M4V, MKV, MOV, MP4, MPEG, MPG, OGG, WebM, WMV. |
files | Qualsiasi |
curl "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate" \
-H "Authorization: Bearer YOUR_API_KEY"
Risponde a url, che rappresenta l’indirizzo da caricare, e a fields, che indica i campi del formulario da inviare insieme al file. fields.key è il percorso in cui il file verrà salvato. L’indirizzo funziona per un’ora.
2. Carica il file
Invia un messaggio POST di tipo multipart/form-data a url. Ogni elemento presente in fields deve essere inserito nel messaggio. Il file finale viene memorizzato in file. fields contiene un campo vuoto Content-Type: questo campo deve essere riempito con il tipo di file, ad esempio application/pdf. Non è necessario inviare un secondo messaggio. Questo invio avviene direttamente nella banca dati dei file, e non tramite l’API; quindi non è necessario utilizzare alcun identificatore per l’invio del messaggio.
curl -X POST "<url>" \
--form-string "key=<fields.key>" \
--form-string "Content-Type=application/pdf" \
--form-string "<every other entry of fields, as given>" \
-F "file=@repair-estimate.pdf"
Inviate gli elementi di fields insieme a --form-string, non a -F. Alcuni elementi iniziano con <; -F interpreta questi elementi come file.
Risponde a 201. Il file più grande è il limite massimo per il ruolo del “Virtual Assistant” in questo ambito: 5.000 MB, per impostazione predefinita. Un amministratore può ridurre questo valore nelle impostazioni sotto Configurazioni › Ruoli. Qualsiasi file che superi questo limite viene rifiutato dal sistema di archiviazione dei file. I file caricati che non vengono mai condivisi vengono eliminati dopo tre giorni.
3. Allegalo
curl -X PUT https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"media": [{"media_key": "<fields.key>"}]}'
{
"data": {
"items": [{"media_key": "hosts/ca-7e6d5c4b3a2f10/cases/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media/docs/20261002154512_5f4e3d2c1b0a99/20261002154512_5f4e3d2c1b0a99.pdf", "media_id": "20261002154512_5f4e3d2c1b0a99"}],
"currentItemCount": 1
}
}
mediaprende più file contemporaneamente. Ogni file deve essere caricato con un indirizzo relativo allo stesso elemento.- L’opzione “Attaccare” permette di aggiungere file al documento; tuttavia, questi file non vengono mai sostituiti da quelli già presenti nel documento.
- In una posta, è possibile allegare i propri webhook.
add_post_mediaPer ogni file, l’email relativa alla posta contiene il numero di file presenti in quel file.
Dopo aver attaccato
I file vengono elaborati dopo l’attacco dei file stessi: le immagini vengono ridimensionate, i file audio e video vengono preparati per la visualizzazione, mentre i documenti vengono convertiti in formato PDF, con le immagini presenti nelle pagine del documento. files Vengono mantenuti così come sono.
Ogni elemento elencato, come ad esempio GET /posts/<post_id>, indica i file che rientrano nella categoria media.<kind>.items.<media_id>.
| Campo | Cosa contiene |
|---|---|
execution_status | RUNNING… finché non viene elaborato. Poi SUCCEEDED o FAILED |
original | Il file è stato caricato. |
pdf | Un documento convertito in formato PDF, una volta pronto… |
flat | Una copia elettronica, bloccata… Una volta che tutti hanno firmato. |
tag_id, content_type, media_size | Il suo nome, il tipo e le dimensioni in byte. |
Durante il processo di elaborazione di qualsiasi file, l’elemento encoding relativo a quel file viene visualizzato. Un modulo o un documento elettronico non può essere pubblicato fino a quando il documento non è pronto.
Download di un file
Scarica un file da https://privcdn.caseactive.com/, seguito dai suoi original, pdf o flat. Utilizza la tua chiave nello stesso intestazione utilizzato per ogni chiamata.
curl "https://privcdn.caseactive.com/hosts/ca-7e6d5c4b3a2f10/cases/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media/docs/20261002154512_5f4e3d2c1b0a99/20261002154512_5f4e3d2c1b0a99.pdf" \
-H "Authorization: Bearer YOUR_API_KEY" -o repair-estimate.pdf
I controlli riguardanti la chiave sono applicati come per ogni chiamata: include anche l’intero intervallo di indirizzi IP. Inoltre, è possibile scaricare i dati relativi al ruolo del Virtual Assistant da qualsiasi parte del sistema.
Rimozione di un file
DELETE /<item>/media accetta un corpo JSON che contiene i valori media_id e media_group; inoltre, restituisce il valore 200. Nei messaggi inviati tramite webhook, vengono ricevuti i valori delete_post_media. I documenti generati da formulari, firme digitali o note non possono essere eliminati; è necessario eliminare l’elemento stesso.
Esempio: un PDF in un nuovo post
POST /postsCon il post…message. Il file viene pubblicato immediatamente, con una notifica via portale. L’email arriva circa 30 secondi dopo, e in quel momento il sistema conta i file allegati. Quindi, è necessario allegare i file entro quel lasso di tempo.GET /posts/<post_id>/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate.- Caricare il file in
url, con il nomefields. - Con
PUT /posts/<post_id>/mediaefields.key. - Leggi il file
GET /posts/<post_id>fino a quando il valore diexecution_statusnon diventaSUCCEEDEDoFAILED.
Se una chiamata viene rifiutata
| Stato | message | Perché |
|---|---|---|
| 400 | SchemaFieldsException | Un parametro è mancante o è invalido. Ad esempio, potrebbe trattarsi di un tipo di parametro che non è supportato da quel metodo. tag_id Con spazi tra le parole; errors Lo chiama così. media.<n>.media_key, L’upload non è stato trovato. Probabilmente si riferiva a un altro oggetto. /schema/media, Non è stato caricato come… schemas; Questa è anche la risposta quando l’elemento che si sta collegando non esiste. Nessun elemento è stato allegato nella richiesta. |
| 403 | ItemUpdateFailedException | Il file è già allegato, oppure il modulo, la firma elettronica o la nota contiene già il documento richiesto. |
| 403 | ItemAuthorOnlyException | La chiave cercava di associare un file a una posta o a un commento scritto da qualcun altro. |
| 403 | CaseClosedException | Il caso è chiuso. |
| 404 | ItemNotFoundException | L’elemento richiesto non esiste quando si cerca l’indirizzo per il suo caricamento, oppure il file da eliminare non esiste affatto. |
Il processo di caricamento dei file viene eseguito nel formato proprio del repository dei file: EntityTooLarge per i file che superano il limite consentito, e AccessDenied quando l’indirizzo del file scade. Per quanto riguarda il corpo dell’errore fornito dall’API e gli altri codici di errore, si veda la sezione Gestisci gli errori e i codici di stato forniti dall’API.