Centro assistenzaIntegrazioni

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.

ArticoloIndirizzo di caricamentoAllegareRimuovere
Un postGET /posts/<post_id>/drivePUT /posts/<post_id>/mediaDELETE /posts/<post_id>/media
Una nota/commentoGET /notes/<note_id>/drivePUT /notes/<note_id>/mediaDELETE /notes/<note_id>/media
Un compito/obbligoGET /tasks/<task_id>/drivePUT /tasks/<task_id>/mediaDELETE /tasks/<task_id>/media
Un compito per un bambinoGET /subtasks/<subtask_id>/drivePUT /subtasks/<subtask_id>/mediaDELETE /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=schemasPUT /<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 tag PUT /<posts, signs, tasks or subtasks>/<id>/comments/<comment_id>/media per 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

ParametroCosa faNecessarioPredefinito
media_groupIl 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_extensionL’estensione del file è pdf. Deve trattarsi di un’estensione valida; files, invece, può indicare qualsiasi estensione.Sì.–
tag_idIl nome del file viene scritto in caratteri, numeri e trattini, ad esempio repair-estimate.Sì.–
TipoEstensioni
docs e schemasCSV, DOC, DOCX, ODT, PDF, PPT, PPTX, RTF, TXT, XLS, XLSX
imagesBMP, GIF, JPEG, JPG, PNG, SVG, TIFF, WebP
audiosaac, aiff, amr, flac, m4a, mp3, oga, opus, wav, wma… e anche altri formati audio meno comuni.
videosFormati di video meno comuni: 3GP, AVI, FLV, M4V, MKV, MOV, MP4, MPEG, MPG, OGG, WebM, WMV.
filesQualsiasi
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
  }
}
  • media prende 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_media Per 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>.

CampoCosa contiene
execution_statusRUNNING… finché non viene elaborato. Poi SUCCEEDED o FAILED
originalIl file è stato caricato.
pdfUn documento convertito in formato PDF, una volta pronto…
flatUna copia elettronica, bloccata… Una volta che tutti hanno firmato.
tag_id, content_type, media_sizeIl 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

  1. POST /posts Con 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.
  2. GET /posts/<post_id>/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate.
  3. Caricare il file in url, con il nome fields.
  4. Con PUT /posts/<post_id>/media e fields.key.
  5. Leggi il file GET /posts/<post_id> fino a quando il valore di execution_status non diventa SUCCEEDED o FAILED.

Se una chiamata viene rifiutata

StatomessagePerché
400SchemaFieldsExceptionUn 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.
403ItemUpdateFailedExceptionIl file è già allegato, oppure il modulo, la firma elettronica o la nota contiene già il documento richiesto.
403ItemAuthorOnlyExceptionLa chiave cercava di associare un file a una posta o a un commento scritto da qualcun altro.
403CaseClosedExceptionIl caso è chiuso.
404ItemNotFoundExceptionL’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.

Articoli correlati

Comprendere cosa può fare l'APIScopri quali funzioni possono svolgere un tasto di gestione e un tasto hub, perché ogni tasto funge da Assistente Virtuale e dove trovare l'elenco tecnico completo.IntegrazioniAggiungi post e commenti con un tasto hubAggiungi post al feed di un caso, rispondi con commenti e leggili, modificali o eliminali dal tuo software, in qualità di Assistente Virtuale.IntegrazioniInvia firme elettroniche e leggi le firme con una chiave hubCrea una firma elettronica per una pratica utilizzando un modello, scegli chi firma ciascun campo, pubblicala per la firma e scarica la copia protetta una volta che tutti hanno firmato.IntegrazioniGestire gli errori e i codici di stato delle APILeggi il corpo dell'errore, cosa significano i codici 400, 401, 403, 404, 500 e 503 e perché un elemento che la tua chiave non riesce a vedere risponde al codice 404.Integrazioni