Dokumente

Die Dokumente-Ressource bietet vollständige CRUD-Operationen zur Verwaltung von Dokumenten in Sonar.

Dokumente auflisten

Ruft eine paginierte Liste von Dokumenten mit optionalen Filtern ab.

Endpunkt: GET /api/sdk/v1/documents

Parameter (ListDocumentsParams)

Parameter	Typ	Erforderlich	Standard	Beschreibung
page	number	Nein	1	Seitennummer (Minimum: 1)
limit	number	Nein	20	Einträge pro Seite (Minimum: 1, Maximum: 100)
classification	DocumentClassification	Nein	—	Filtern nach: 'generated', 'uploaded' oder 'signed'
isSigned	boolean	Nein	—	Nach Signaturstatus filtern
type	string	Nein	—	Nach MIME-Typ filtern (z.B. 'application/pdf')
uploadFrom	DocumentUploadSource	Nein	—	Nach Upload-Quelle filtern
sessionId	string	Nein	—	Nach Sitzungs-ID filtern (MongoDB ObjectId)
fromDate	string | Date	Nein	—	Dokumente ab diesem Datum filtern (ISO 8601)
toDate	string | Date	Nein	—	Dokumente bis zu diesem Datum filtern (ISO 8601)

Antwort (ListDocumentsResponse)

Feld	Typ	Beschreibung
docs	Document[]	Array von Dokumentobjekten
totalDocs	number	Gesamtanzahl der übereinstimmenden Dokumente
limit	number	Einträge pro Seite
totalPages	number	Gesamtanzahl der Seiten
page	number	Aktuelle Seitennummer
pagingCounter	number	Seriennummer des ersten Dokuments auf dieser Seite
hasPrevPage	boolean	Ob eine vorherige Seite existiert
hasNextPage	boolean	Ob eine nächste Seite existiert
prevPage	number | null	Vorherige Seitennummer oder null
nextPage	number | null	Nächste Seitennummer oder null

Beispiel

// Einfache Auflistung
const response = await sdk.documents.list();
console.log(response.docs);       // Document[]
console.log(response.totalDocs);  // Gesamtanzahl

// Mit Filtern
const signedPDFs = await sdk.documents.list({
  page: 1,
  limit: 50,
  classification: 'signed',
  isSigned: true,
  type: 'application/pdf',
  fromDate: '2025-01-01T00:00:00Z',
  toDate: new Date(),
});

// Paginierungsschleife
let page = 1;
let hasMore = true;
while (hasMore) {
  const result = await sdk.documents.list({ page, limit: 100 });
  console.log(`Seite ${page}: ${result.docs.length} Dokumente`);
  hasMore = result.hasNextPage;
  page++;
}

---

Ein Dokument abrufen

Ruft ein einzelnes Dokument anhand seiner ID ab.

Endpunkt: GET /api/sdk/v1/documents/:id

Parameter	Typ	Erforderlich	Beschreibung
documentId	string	Ja	Die Dokumentkennung

Gibt zurück: Document-Objekt Wirft: DocumentNotFoundError, wenn das Dokument nicht existiert.

try {
  const doc = await sdk.documents.get('doc_abc123');
  console.log(doc.name);       // "contract.pdf"
  console.log(doc.isSigned);   // true
  console.log(doc.extension);  // "pdf"
  console.log(doc.size);       // "245632"
} catch (err) {
  if (err instanceof DocumentNotFoundError) {
    console.log(`Dokument ${err.documentId} nicht gefunden`);
  }
}

---

Ein Dokument herunterladen

Lädt den binären Dateiinhalt eines Dokuments herunter.

Endpunkt: GET /api/sdk/v1/documents/:id/download

Parameter	Typ	Erforderlich	Beschreibung
documentId	string	Ja	Die Dokumentkennung

Antwort (DownloadResponse)

Feld	Typ	Beschreibung
data	ArrayBuffer	Die rohen Dateidaten
contentType	string	MIME-Typ (z.B. 'application/pdf')
filename	string	Originaler Dateiname vom Server
size	number	Größe in Bytes

import { writeFileSync } from 'fs';

const { data, filename, contentType, size } = await sdk.documents.download('doc_abc123');

// Auf Festplatte speichern
writeFileSync(`./${filename}`, Buffer.from(data));
console.log(`Heruntergeladen: ${filename} (${size} Bytes, ${contentType})`);

---

Ein Dokument hochladen

Lädt ein neues Dokument in Sonar hoch. Das SDK übernimmt die multipart/form-data-Kodierung automatisch.

Endpunkt: POST /api/sdk/v1/documents/upload

Parameter (UploadDocumentParams)

Parameter	Typ	Erforderlich	Standard	Beschreibung
file	Buffer | Blob | NodeJS.ReadableStream	Ja	—	Die hochzuladenden Dateidaten
filename	string	Nein	—	Originaler Dateiname
contentType	string	Nein	application/octet-stream	MIME-Typ der Datei
name	string	Nein	—	Anzeigename für das Dokument
uploadFrom	DocumentUploadSource	Nein	'user-documents'	Quelle/Kontext des Uploads
identity	string	Nein	—	Identitätsstring für den Uploader
classification	DocumentClassification	Nein	'uploaded'	Dokumentklassifizierungskategorie

Upload-Quellwerte (DocumentUploadSource)

Wert	Beschreibung
'session-chat'	Während einer Chat-Sitzung hochgeladen
'session-call'	Während einer Anrufsitzung hochgeladen
'user-documents'	Aus der Benutzerdokumentverwaltung hochgeladen
'session-recording'	Aus einer Sitzungsaufnahme
'queue-documents'	Aus einer Warteschlangen-/Verarbeitungspipeline
'application-settings-appearance'	Anwendungseinstellungen-Upload

Dateieingabetypen

Das SDK unterstützt drei Eingabetypen für den file-Parameter:

1. Buffer (Node.js) — Wird mit dem angegebenen contentType in Blob konvertiert
2. Blob (Browser/Node.js 18+) — Wird direkt verwendet
3. ReadableStream (Node.js) — Chunks werden gesammelt, zusammengefügt und als Blob verpackt

Gibt zurück: Document-Objekt (das neu erstellte Dokument)

import { readFileSync, createReadStream } from 'fs';

// Upload aus Buffer
const buffer = readFileSync('./contract.pdf');
const doc = await sdk.documents.upload({
  file: buffer,
  filename: 'contract.pdf',
  contentType: 'application/pdf',
  name: 'Q1 Vertrag',
  uploadFrom: 'user-documents',
  classification: 'uploaded',
});
console.log(`Hochgeladen: ${doc.id} — ${doc.name}`);

// Upload aus ReadableStream
const stream = createReadStream('./report.xlsx');
const doc2 = await sdk.documents.upload({
  file: stream,
  filename: 'report.xlsx',
  contentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
  classification: 'generated',
});

// Upload aus Blob (Browser-Umgebung)
const blob = new Blob([arrayBuffer], { type: 'application/pdf' });
const doc3 = await sdk.documents.upload({
  file: blob,
  filename: 'scan.pdf',
});

---

Ein Dokument löschen

Löscht ein Dokument dauerhaft anhand seiner ID. Diese Aktion kann nicht rückgängig gemacht werden.

Endpunkt: DELETE /api/sdk/v1/documents/:id

Parameter	Typ	Erforderlich	Beschreibung
documentId	string	Ja	Die Dokumentkennung

Gibt zurück: DeleteDocumentResponse mit { documentId: string } Wirft: ValidationError, wenn documentId leer ist. DocumentNotFoundError, wenn das Dokument nicht existiert. Erforderlicher Bereich: documents:{classification}:delete

// Ein einzelnes Dokument löschen
const { documentId } = await sdk.documents.delete('doc_abc123');
console.log(`Gelöscht: ${documentId}`);

// Mit Fehlerbehandlung
try {
  await sdk.documents.delete('doc_abc123');
} catch (err) {
  if (err instanceof DocumentNotFoundError) {
    console.log(`Dokument ${err.documentId} nicht gefunden`);
  }
}

---

Batch-Löschung von Dokumenten

Löscht mehrere Dokumente in einer einzelnen Anfrage.

Endpunkt: POST /api/sdk/v1/documents/delete

Parameter (BatchDeleteParams)

Parameter	Typ	Erforderlich	Beschreibung
documentIds	string[]	Ja	Array von Dokument-IDs zum Löschen (Min.: 1, Max.: 500)

Clientseitige Validierung:

• Wirft ValidationError, wenn documentIds leer ist
• Wirft ValidationError, wenn documentIds mehr als 500 Einträge hat

Antwort (BatchDeleteResponse)

Feld	Typ	Beschreibung
deleted	number	Anzahl erfolgreich gelöschter Dokumente
failed	number	Anzahl fehlgeschlagener Löschungen
total	number	Gesamtanzahl der Dokumente in der Anfrage

const result = await sdk.documents.batchDelete({
  documentIds: ['doc_001', 'doc_002', 'doc_003'],
});
console.log(`${result.deleted} von ${result.total} gelöscht`);

if (result.failed > 0) {
  console.warn(`${result.failed} Dokumente konnten nicht gelöscht werden`);
}

---

Vorsignierte Download-URL abrufen

Generiert eine temporäre vorsignierte URL zum Herunterladen eines Dokuments.

Endpunkt: GET /api/sdk/v1/documents/:id/download-url

Parameter	Typ	Erforderlich	Beschreibung
documentId	string	Ja	Die Dokumentkennung

Abfrageparameter (DownloadUrlParams)

Parameter	Typ	Erforderlich	Standard	Beschreibung
expiresIn	number	Nein	300	URL-Ablauf in Sekunden (Min.: 60, Max.: 3600)

Antwort (DownloadUrlResponse)

Feld	Typ	Beschreibung
documentId	string	Die Dokumentkennung
name	string	Dokumentname
url	string	Vorsignierte Download-URL
expiresIn	number	URL-Ablaufzeit in Sekunden

// Download-URL mit Standard-Ablauf abrufen (300s)
const { url, expiresIn } = await sdk.documents.getDownloadUrl('doc_abc123');
console.log(`Download unter: ${url} (läuft in ${expiresIn}s ab)`);

// URL mit benutzerdefiniertem Ablauf abrufen (10 Minuten)
const { url: longUrl } = await sdk.documents.getDownloadUrl('doc_abc123', {
  expiresIn: 600,
});

// Client zur Download-URL weiterleiten (Express)
app.get('/download/:id', async (req, res) => {
  const { url } = await sdk.documents.getDownloadUrl(req.params.id, {
    expiresIn: 120,
  });
  res.redirect(url);
});

---

Dokumente als ZIP exportieren

Exportiert mehrere Dokumente gebündelt in einem einzelnen ZIP-Archiv.

Endpunkt: POST /api/sdk/v1/documents/export

Parameter (ExportDocumentsParams)

Parameter	Typ	Erforderlich	Beschreibung
documentIds	string[]	Ja	Array von Dokument-IDs zum Exportieren (Min.: 1, Max.: 500)

Clientseitige Validierung:

• Wirft ValidationError, wenn documentIds leer ist
• Wirft ValidationError, wenn documentIds mehr als 500 Einträge hat

Gibt zurück: DownloadResponse mit data (ArrayBuffer), contentType ('application/zip'), filename und size.

import { writeFileSync } from 'fs';

const { data, filename, size } = await sdk.documents.export({
  documentIds: ['doc_001', 'doc_002', 'doc_003'],
});

writeFileSync(`./${filename}`, Buffer.from(data));
console.log(`Exportiert: ${filename} (${size} Bytes)`);