Dokumente

Übersicht

Ein Dokument ist eine Datei (PDF, JPG, DOCX, …) mit Metadaten — Dateiname, Kategorie, Datum, Ordner, und einer optionalen FK-Bindung an einen Vertrag (vid) oder Schaden (schaden). In der API geht es standardmäßig um die Metadaten. Der Datei-Inhalt kommt opt-in als base64-codierter String über ?with_base64=true mit (kleinere Files) oder binär über /v3/documents/{id}/download beziehungsweise /content.

Das Dokument hat eine global eindeutige id — alle CRUD-Operationen laufen daher top-level über /v3/documents/{id}, ohne Detour über den Customer:

1. Top-Level Full-CRUD — /v3/documents (List, Create) und /v3/documents/{id} (Read, Update, Delete). Für globale Dokumenten-Searches, Storage-Audits, Compliance-Reports.
2. Parent-scoped Listing + Create — GET /v3/customers/{kid}/documents und POST /v3/customers/{kid}/documents. Path-kid ist Source-of-Truth; Body darf kein kid-Feld tragen (sonst 400 body_kid_forbidden).

Beide Patterns nutzen denselben Scope v3:documents:* — Dokumente haben eine eigene Scope-Familie, weil sie quer durch alle CRM-Objekte hängen können (Customers, Verträge, Schäden, Aktivitäten, …) und unabhängige Berechtigung brauchen.

Scopes

Auth-Mechanik siehe Authentifizierung↗. Vollständige Scope-Referenz: Scopes↗.

Pagination & Limits

Standard wie bei Customers↗. Beachte: Dokumente-Listen können in größeren Orgs sehr groß werden (mehrere zehntausend Einträge) — mit ?limit=5000 und page-Loop arbeiten.

Schema

Die Doku zeigt die echten DB-Spalten der crm_dokumente-Tabelle — Field-Namen sind kein abstrahiertes Public-API-Vertragsmodell. Bei Implementierung gegen diese API: rechne mit den hier gezeigten Schlüsseln.

DB-Tabelle: crm_dokumente. Es gibt keine separate kategorie-Spalte; Documents werden ueber ordner (Folder-ID) sowie die FKs vid/schaden kategorisiert. ext_*/bipro_* Felder sind read-only Metadaten aus externen Quellen (BiPro-Imports, Inbox-Pipelines).

{
  "id": 33001,
  "kid": 12345,                       // Customer-ID (Owner)
  "name": "Police_KFZ_2024.pdf",      // Dateiname inkl. Extension
  "extension": "pdf",                 // ohne führenden Punkt
  "size": 245678,                     // Größe in Bytes (integer)
  "datum": "2024-01-15",              // Dokument-Datum (separat von insert_datum)
  "ordner": 5001,                     // Ordner-ID (interne Folder-Struktur)
  "vid": 90001,                       // FK auf Vertrag (null wenn kein Vertrag)
  "schaden": null,                    // FK auf Schaden (null wenn kein Schaden)
  "nr": 4711,                         // optionale interne Dokument-Nummer (integer)
  "url": "12345/2024/police.pdf",     // S3-Path (bei aws=1) oder Datei-Pfad (legacy)
  "dir": "/uploads",                  // S3-Prefix bzw. Verzeichnis
  "aws": 1,                           // 1 = auf S3, 0 = legacy file-storage (smallint)
  "kundenportal": 0,
  "is_eml": 0,
  "protect": 0,
  "has_error": 0,
  "ai_status": 0,                     // KI-Pipeline Status
  "insert_datum": "2024-01-16 08:42:00",
  "edit_datum":   "2024-01-16 08:42:00"
}

{
  // … alle Metadaten-Felder wie oben, plus:
  "content_type": "application/pdf",  // aus extension abgeleitet (kein eigener DB-Eintrag)
  "base64": "JVBERi0xLjQKJeLjz9MK…"   // Datei-Inhalt base64-kodiert
}

{
  // … Metadaten, plus:
  "base64": null,
  "base64_error": "s3_get_failed",          // oder anderer Fehler-Code
  "base64_error_message": "NoSuchKey: …"    // optional
}

{
  // crm_dokumente exposes minimal fields-meta — most columns are auto-
  // managed (ext_*, bipro_*, ai_status, etc.). Clients drive the
  // user-facing UX with `name`, `extension`, `datum`, `ordner`, plus
  // optional foreign keys `vid` (Vertrag) and `schaden`.
  "fields": {
    "name":      { "label": "Dateiname",     "data_type": "string", "select_fields_name": null },
    "extension": { "label": "Erweiterung",   "data_type": "string", "select_fields_name": null },
    "datum":     { "label": "Dokumentdatum", "data_type": "date",   "data_format": "0000-00-00" },
    "ordner":    { "label": "Ordner",        "data_type": "number" }
  }
}

Endpoints

Dokumente abfragen

Liefert paginierte Liste aller Dokumente deiner Organisation, optional gefiltert.

Query-Parameter: page (Default 1), limit (Default 50, Max 5000), kid, vid (Vertrags-Filter), schaden (Schaden-Filter), ordner (Folder-Filter), with_schema (Default false, opt-in). Die Liste liefert nur Metadaten — kein base64-Feld, weil die Antwort sonst extrem groß würde. Eine kategorie-Spalte gibt es nicht — fuer Kategorisierung den ordner-Filter bzw. die FKs vid/schaden nutzen.

# Alle Dokumente an einem Vertrag
curl "https://www.api.i-planner.app/v3/documents?vid=90001" \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

# Alle Dokumente an einem Schadensfall
curl "https://www.api.i-planner.app/v3/documents?schaden=22" \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

Einzelnes Dokument abrufen

Liefert ein einzelnes Dokument. Standardmäßig nur Metadaten. Mit ?with_base64=true zusätzlich der Datei-Inhalt als base64-Feld.

Query-Parameter: with_schema (Default false), with_base64 (Default false), file (true/1 liefert den Inhalt binär als Download).

curl "https://www.api.i-planner.app/v3/documents/33001?with_base64=true" \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" | jq '.'

const doc = await $fetch(`https://www.api.i-planner.app/v3/documents/${id}?with_base64=true`, {
  headers: { Authorization: `Bearer ${process.env.IPLANNER_API_TOKEN}` },
})
if (doc.base64_error) throw new Error(doc.base64_error_message || doc.base64_error)
const buffer = Buffer.from(doc.base64, 'base64')
fs.writeFileSync(doc.name, buffer)

Für einen binären Abruf stehen zwei explizite Pfade bereit:

• GET /v3/documents/<id>/download — Content-Disposition: attachment
• GET /v3/documents/<id>/content — Content-Disposition: inline

Beide liefern dieselben Datei-Bytes wie GET /v3/documents/<id>?file=true.

Dokument top-level anlegen

Customer-kid darf optional im Body stehen. Die Datei-Bytes gehen als base64-codierter String im Body-Feld base64 (oder file als Alias) mit.

Body-Felder:

curl -X POST 'https://www.api.i-planner.app/v3/documents' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kid": 12345,
    "name": "Vertragsanlage.pdf",
    "extension": "pdf",
    "ordner": 5001,
    "vid": 90001,
    "datum": "2024-01-15",
    "base64": "JVBERi0xLjQKJeLjz9MK…"
  }'

Dokument am Kunden anlegen

Upload an einem Customer. kid im Pfad ist Source-of-Truth; Body darf kein kid tragen.

Dokumente eines Kunden listen

Dokument an einem CRM-Objekt anhängen

Dokumente lassen sich nur dann direkt an einem CRM-Objekt hochladen, wenn crm_dokumente eine durchsetzbare Fremdschlüssel-Spalte für die Ziel-Section besitzt:

Body — identisch zu POST /v3/documents↓, abzüglich kid (das aus dem Parent abgeleitet wird), vid/schaden (werden beim direkten FK automatisch gesetzt) und base64 Pflicht.

Ordner-Baum eines Parents abfragen

Liefert die komplette Ordnerstruktur des Parents (Customer, Produktpartner oder Benutzer) als flache Liste. parent_id bildet darin die Hierarchie ab. Das ist praktisch für UI-Picker beim Upload — der ordner-Wert im POST-Body wird über diese Liste aufgelöst.

Für einen gezielten Upload zuerst den Ordnerbaum dieses Parents lesen und dann die zurückgegebene id als ordner im Dokument-POST verwenden. Dieselbe Ownership-Prüfung greift auch beim späteren Verschieben per Dokument-PATCH.

Keine Query-Parameter, keine Pagination — der Baum wird komplett geliefert. Scope: v3:documents:read.

{
  "items": [
    { "id": 5001, "name": "Verträge",          "parent_id": null, "kid": 12345 },
    { "id": 5002, "name": "Krankenversicherung","parent_id": 5001, "kid": 12345 },
    { "id": 5003, "name": "KFZ",               "parent_id": 5001, "kid": 12345 },
    { "id": 5010, "name": "Korrespondenz",     "parent_id": null, "kid": 12345 }
  ]
}

parent_id: null markiert Top-Level-Ordner; alle anderen verweisen per parent_id auf den Parent-Ordner. Anti-Recursion ist serverseitig garantiert.

Ordner anlegen

Legt einen neuen Ordner unter dem Parent (Customer/Produktpartner/Benutzer) an. Scope v3:documents:write.

Body

• name (string, required) — Anzeigename des Ordners.
• parent_id (int, optional) — Existierender Ordner unter dem Parent. Default = Standard-Ordner „Dokumente" des Parents (automatisch beim Anlegen des Customers/Produktpartners/Benutzers angelegt). parent_id=0 wird ebenfalls auf den Standard-Ordner gemappt — Frontend rendert nur Ordner die unter dem Standard-Ordner hängen.
• datum (date, optional) — Anlagedatum (display only).
• kundenportal (0|1, optional) — Sichtbar im Kundenportal.
• protect (0|1, optional) — Schützt vor DELETE (Server gibt 403 folder_protected).

Anti-Recursion + Ownership: parent_id muss zum selben Parent (kid) gehören, sonst 400 invalid_parent_id. Self-Parent (parent_id = id) wird beim PATCH abgelehnt. Server pflegt die crm_dokumente_ordner_closure-Tabelle mit (Self-Row + Ancestor-Chain) — neue Ordner sind im Frontend sofort sichtbar.

Ordner umbenennen / verschieben

PATCH-Semantik. Ändert name, parent_id, kundenportal, protect, datum. Wechsel von parent_id rebuilds Closure-Edges automatisch.

Ordner löschen

Hard-Delete. Folge-Effekte automatisch:

• Sub-Folder verlieren ihren parent_id (werden Root unter „Dokumente").
• Dokumente im Ordner werden auf ordner=0 zurückgesetzt (= unsortiert), nicht gelöscht.
• Geschützte Ordner (protect=1) werden mit 403 folder_protected abgelehnt.

Dokument aktualisieren

PATCH-Semantik. Aktualisiert nur die Metadaten — Datei-Inhalt selbst ist nach Upload unveränderlich (Versions-Logik im UI).

Audit-Log Sonderfall — DOCUMENTS_MOVE: PATCH mit ordner=<neue-id> erzeugt KEINEN generischen FIELDS_UPDATE-Eintrag mit IDs, sondern einen DOCUMENTS_MOVE-Eintrag mit:

• field = Dokument-Name
• previous_value = alter Ordner-Name
• current_value = neuer Ordner-Name
• foreign_section = directories, foreign_section_id = neue Ordner-ID
• foreign_section_value = <span class="log-foreign">…neuer Ordner…</span>

Andere Felder werden weiter als FIELDS_UPDATE geloggt.

Dokument löschen

Soft-Delete, idempotent. Volle Error-Tabelle in Fehler↗.

Annotations

Comments, Followers und Tags hängen top-level am Dokument:

/v3/documents/<id>/comments[/<rid>]
/v3/documents/<id>/followers[/<rid>]
/v3/documents/<id>/tags[/<rid>]