HilfezentrumIntegrationen

Für: Administratoren

Dateien mit einem Hub-Schlüssel hochladen und anhängen

Eine Upload-Adresse abrufen, eine Datei hochladen, diese an einen Beitrag, eine Notiz, eine Aufgabe, ein Formular oder eine elektronische Signatur anhängen und die Akten eines Falls herunterladen.

In diesem Artikel10 Abschnitte

Bevor Sie beginnen

Diese Seite beschreibt den Upload von Dateien in ein Fallelement, deren Anhängung sowie deren Abruf mit einem Hub-Key. Die Pfade befinden sich unter https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.

So funktioniert es

Ein Dateiverfahren erfordert drei Schritte: Zuerst wird eine Upload-Adresse für die entsprechende Datei angefordert. Anschließend wird die Datei dort hochgeladen. Danach wird die Datei wiederum an die entsprechende Einheit angehängt.

ArtikelUpload-AdresseBefestigenEntfernen
Eine Nachricht/InformationGET /posts/<post_id>/drivePUT /posts/<post_id>/mediaDELETE /posts/<post_id>/media
Hinweis/AnmerkungGET /notes/<note_id>/drivePUT /notes/<note_id>/mediaDELETE /notes/<note_id>/media
Eine AufgabeGET /tasks/<task_id>/drivePUT /tasks/<task_id>/mediaDELETE /tasks/<task_id>/media
Eine kindliche AufgabeGET /subtasks/<subtask_id>/drivePUT /subtasks/<subtask_id>/mediaDELETE /subtasks/<subtask_id>/media
Ein Dokument in Form von elektronischer Signatur oder Notiz.GET /<forms, signs or notes>/<id>/drive Mit/ohne media_group=schemasPUT /<forms, signs or notes>/<id>/schema/media–
  • Eine Schlüsselkarte kann nur Dateien an die Beiträge anhängen, die vom virtuellen Assistenten erstellt wurden. Sie kann auch an jede Notiz, jeden Aufgabe oder jeden Unterauftrag angehängt werden.
  • Um eine Datei an einen Kommentar anzuhängen, erhalten Sie die Adresse des Kommentars bzw. der Aufgabe mit dem Attribut /drive. Anschließend können Sie die Datei mit PUT /<posts, signs, tasks or subtasks>/<id>/comments/<comment_id>/media versehen. Ein Schlüssel kann nur an seine eigenen Kommentare angehängt werden.
  • Eine elektronische Signatur beinhaltet nur ein einziges Dokument – keine anderen Dateien. Sobald das Dokument bereits gespeichert ist, wird kein weiteres Dokument gespeichert, es sei denn, das erste Dokument konnte nicht korrekt konvertiert werden.

1. Eine Upload-Adresse besorgen

ParameterWas es tutErforderlichStandard
media_groupArt des Files: docs, images, audios, videos oder files – oder schemas für Dokumente von Formularen, e-Signs oder Notizen.Ja.–
media_extensionDie Dateierweiterung ist beispielsweise pdf. Es muss sich um eine gültige Dateierweiterung handeln; files kann jede beliebige Dateierweiterung annehmen.Ja.–
tag_idDer Name des Dateisystems, unter dem die Datei gespeichert wird, kann aus Buchstaben, Zahlen und Bindestrichen bestehen – beispielsweise repair-estimateJa.–
ArtErweiterungen
docs und 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 – sowie weniger verbreitete Audioformate
videos3GP, AVI, FLV, M4V, MKV, MOV, MP4, MPEG, MPG, OGG, WebM, WMV – sowie weitere, seltener verwendete Videoformate
filesJedes
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"

Es beantwortet die Frage. url, Die Adresse, die geladen werden soll. fields, Die Felder, die zusammen mit dem Datei-Datein gesendet werden sollen. fields.key Das ist der Ort, an dem die Datei gespeichert werden wird. Die Adresse gilt für eine Stunde.

2. Laden Sie die Datei hoch.

Senden Sie eine… multipart/form-data Posten an… url, Mit jedem Eintrag in… fields Wenn das so ist, dann ist das Date am Ende angeordnet. file. fields Hält eine leere Stelle bereit. Content-Type: Füllen Sie das Feld mit dem Typ des Dateisystems aus – beispielsweise: application/pdf, Anstatt eine zweite Nachricht zu senden, geht dieser Anruf direkt zum Dateispeicher – nicht an die API. Daher benötigt es keine Schlüsselwörter für den Übertragungsvorgang.

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"

Senden Sie die Einträge von fields zusammen mit --form-string – nicht mit -F. Einige der Einträge beginnen mit <. -F wird dabei als Datei interpretiert.

Es wird die Frage 201 beantwortet. Das größte Dateiformat ist die maximale Größe, die für diese Rolle vorgesehen ist – standardmäßig 5.000 MB. Ein Administrator kann diese Grenze unter Settings › Roles reduzieren. Eine Datei, die die maximale Größe überschreitet, wird vom Dateispeicher abgelehnt. Eine hochgeladene Datei, die nie angehängt wird, wird nach drei Tagen gelöscht.

3. Befestigen Sie es.

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 nimmt mehrere Dateien auf einmal auf. Jede dieser Dateien muss mit einer Adresse versehen sein, die zur gleichen Einheit gehört.
  • Das Hinzufügen von Dateien bedeutet lediglich, dass diese angehängt werden – sie werden dabei nicht ersetzt.
  • Man kann eine Nachricht senden, wobei dabei die Webhooks übertragen werden. add_post_media Für jeden Dateinamen gibt es eine entsprechende E-Mail mit Angaben zu den zugehörigen Dateien.

Nach dem Anbringen

Die Dateien werden erst nach dem Anhängen bearbeitet: Die Bilder werden angepasst, Audio- und Video-Inhalte werden aufbereitet, damit sie abgespielt werden können. Die Dokumente werden außerdem in PDF-Format umgewandelt, wobei die Seitenbilder ebenfalls mit einbezogen werden. Dateien der Art files bleiben unverändert.

Die Anzahl der gelesenen Elemente, wie zum Beispiel GET /posts/<post_id>, zeigt die Dateien unter media.<kind>.items.<media_id> an.

FeldWas es enthält
execution_statusRUNNING Während es noch verarbeitet wird… SUCCEEDED Oder FAILED
originalDas angehängte Dokument.
pdfEin Dokument, das in PDF-Format umgewandelt wurde – jetzt bereit.
flatDie gesicherte Kopie des elektronischen Dokuments – sobald alle ihre Unterschriften abgegeben haben.
tag_id, content_type, media_sizeSein Name, seine Art und seine Größe in Bytes

Solange ein Datei noch verarbeitet wird, wird die entsprechende Einheit encoding als „verarbeitet“ angezeigt. Eine Form oder elektronische Signatur kann erst veröffentlicht werden, wenn das Dokument fertig ist.

Herunterladen einer Datei

Laden Sie ein Datei von https://privcdn.caseactive.com/ ab – zusammen mit deren original, pdf oder flat. Verwenden Sie dabei Ihre Schlüsselwerte im selben Header wie bei jeder anderen Anfrage.

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

Die Überprüfungen bezüglich der Schlüsselwerte werden genauso durchgeführt wie bei jeder Anrufanrufung – einschließlich des IP-Bereichs des Schlüssels. Zudem kann der Virtual Assistant aus jeder beliebigen Region Informationen abrufen.

Entfernen einer Datei

DELETE /<item>/media nimmt einen JSON-Body entgegen, in dem die Eigenschaften media_id und media_group enthalten sind. Als Antwort gibt es dann 200. Bei einer Post werden die Webhooks über delete_post_media informiert. Dokumente, die aus Formularen, e-Signs oder Notizen stammen, können nicht gelöscht werden – diese müssen stattdessen entfernt werden.

Beispiel: eine PDF-Datei in einem neuen Beitrag

  1. POST /posts Mit dem Posten… message. Es wird sofort veröffentlicht – zusammen mit einer Benachrichtigung über das Portal. Die E-Mail erreicht die Adressaten etwa 30 Sekunden später. In dieser Zeit sollten die angehängten Dateien auch noch bereitgestellt werden.
  2. GET /posts/<post_id>/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate.
  3. Laden Sie das Datei in den Ordner url mit dem Pfad fields hoch.
  4. Mit PUT /posts/<post_id>/media und fields.key.
  5. Lesen Sie den Inhalt von GET /posts/<post_id> bis der Inhalt des Dateispezifischen Bereichs execution_status auf den Wert SUCCEEDED oder FAILED kommt.

Wenn ein Anruf abgelehnt wird

StatusmessageWarum
400SchemaFieldsExceptionEs fehlt ein Parameter oder dieser ist ungültig – beispielsweise handelt es sich um eine Erweiterung, die nicht akzeptiert wird, oder um ein tag_id-Element mit Leerzeichen. Das errors-Element bezeichnet dabei den Ort, an dem das Element gespeichert werden soll. Bei media.<n>.media_key wurde das Element nicht hochgeladen; es handelte sich vielmehr um ein anderes Element. Bei /schema/media wurde das Element nicht als schemas hochgeladen. Dies gilt auch dann, wenn das zu übertragende Element nicht existiert. In der Anfrage wird nichts übertragen.
403ItemUpdateFailedExceptionDas Dokument ist bereits angehängt worden – oder der Formular- oder E-Verfahren-Vorgang wurde bereits abgeschlossen.
403ItemAuthorOnlyExceptionDer Benutzer versuchte, eine Datei an einen Beitrag oder einen Kommentar zu anhängen, den jemand anders geschrieben hatte.
403CaseClosedExceptionDer Fall ist abgeschlossen.
404ItemNotFoundExceptionDas Produkt existiert nicht, wenn man nach seiner Upload-Adresse fragt. Ebenso existiert das zu löschende Datei nicht.

Die Übertragung der Datei erfolgt im Format, das von dem Dateispeicher verwendet wird: EntityTooLarge für Dateien, die die maximale Größe überschreiten, und AccessDenied, wenn die Zugriffsberechtigung abgelaufen ist. Für den Fehlermeldungsinhalt der API sowie für die restlichen Codewerte siehe Verarbeitung von API-Fehlern und Statuscodes.

Verwandte Artikel

Verstehen Sie, was die API leisten kann.Erfahren Sie, welche Funktionen eine Verwaltungstaste und eine Hub-Taste jeweils haben, warum jede Taste als virtueller Assistent fungiert und wo Sie die vollständige technische Auflistung finden.IntegrationenFüge Beiträge und Kommentare mit einem Hub-Schlüssel hinzu.Fügen Sie Beiträge zum Feed eines Falls hinzu, antworten Sie mit Kommentaren und lesen, bearbeiten oder löschen Sie diese über Ihre eigene Software als virtueller Assistent.IntegrationenMit einem Hub-Schlüssel können Sie elektronische Signaturen senden und lesen.Erstellen Sie eine elektronische Signatur für einen Fall anhand einer Vorlage, wählen Sie aus, wer welches Feld unterschreibt, veröffentlichen Sie ihn zur Unterzeichnung und laden Sie die gesperrte Kopie herunter, sobald alle unterschrieben haben.IntegrationenAPI-Fehler und Statuscodes behandelnLesen Sie den Fehlertext, was 400, 401, 403, 404, 500 und 503 bedeuten und warum ein Element, dessen Schlüssel nicht angezeigt werden kann, 404.Integrationen