Datenablage: Dateien von Drittsystemen empfangen

Gilt ab Work7 0.2.1 · Stand 15.09.2026

Mit der Datenablage senden externe Systeme (zum Beispiel ERP-, Branchen- oder Buchhaltungssoftware) Datei-Exporte direkt an Work7. Work7 legt jede Lieferung unverändert ab und protokolliert sie mit Größe, Prüfsumme und Empfangszeit. Die Übernahme der Inhalte in Work7-Daten folgt später je Anbindung.

Modul: Datenablage (int.inbound, setzt Public API & Webhooks voraus) · Scopes: int.inbound:write zum Senden, int.inbound:read für das Protokoll

Voraussetzung

Die Module Public API & Webhooks und Datenablage müssen für den Betrieb freigeschaltet sein (im Paket Komplett+ enthalten). Den Schlüssel legt ein Administrator unter Einstellungen › Integrationen › API & Webhooks an und hakt den Scope int.inbound:write an. Der Schlüssel gehört genau einem Betrieb, alle Lieferungen landen dort.

Datei senden

Die Datei ist der komplette Request-Body. Jedes Format ist erlaubt: JSON, CSV, XML, ZIP, SQL-Dump, Binärdaten. Bitte die Datei direkt als Body senden, nicht als multipart/form-data, sonst wird das Formular-Gerüst mit abgelegt.

Parameter	Pflicht	Bedeutung
source	ja	Kennung des liefernden Systems, zum Beispiel kplus. Kleinbuchstaben, Ziffern, - und _, höchstens 40 Zeichen.
filename	nein	Dateiname für die Ablage. Alternativ Header X-Filename. Pfadanteile werden entfernt, Sonderzeichen ersetzt, höchstens 120 Zeichen. Ohne Angabe: upload.bin.
batch	nein	Kennung einer Lieferung, die aus mehreren Dateien besteht, höchstens 100 Zeichen.
part	nein	Teil innerhalb der Lieferung, zum Beispiel 1/3, höchstens 100 Zeichen.

curl

curl -X POST "https://app.work7.net/api/v1/inbound?source=kplus&filename=export-2026-09-15.zip" \
  -H "Authorization: Bearer $WORK7_API_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @export-2026-09-15.zip

JavaScript

// Node.js 18+: Datei gestreamt senden, ohne sie komplett in den Speicher zu laden
import fs from 'node:fs'

const res = await fetch('https://app.work7.net/api/v1/inbound?source=kplus&filename=export.zip', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WORK7_API_KEY}`,
    'Content-Type': 'application/zip',
    'Content-Length': String(fs.statSync('./export.zip').size),
  },
  body: fs.createReadStream('./export.zip'),
  duplex: 'half', // Pflicht bei Stream-Body in Node
})
if (res.status !== 201) throw new Error(`HTTP ${res.status}: ${await res.text()}`)
const { data } = await res.json()
console.log('Abgelegt:', data.id, data.size_bytes, data.sha256)

PHP

<?php
// Datei gestreamt senden (CURLOPT_UPLOAD liest aus dem Datei-Handle)
$file = '/pfad/zu/export.zip';
$fp = fopen($file, 'rb');
$ch = curl_init('https://app.work7.net/api/v1/inbound?' . http_build_query([
    'source' => 'kplus',
    'filename' => basename($file),
]));
curl_setopt_array($ch, [
    CURLOPT_UPLOAD => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_INFILE => $fp,
    CURLOPT_INFILESIZE => filesize($file),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WORK7_API_KEY'),
        'Content-Type: application/zip',
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
fclose($fp);
if ($status !== 201) {
    throw new RuntimeException("Upload fehlgeschlagen: HTTP $status $body");
}
$data = json_decode($body, true)['data'];
echo 'Abgelegt: ', $data['id'], ' SHA-256: ', $data['sha256'], PHP_EOL;

Antwort 201 Created:

{
  "data": {
    "id": 42,
    "source": "kplus",
    "filename": "export-2026-09-15.zip",
    "content_type": "application/zip",
    "size_bytes": 1048576,
    "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "batch": null,
    "part": null,
    "received_at": "2026-09-15T12:30:00.000Z"
  }
}

Große Bestände in Teilen senden

Eine einzelne Anfrage darf höchstens 2048 MB groß sein. Größere Bestände teilst du auf, zum Beispiel eine Datei je Tabelle oder ein Archiv in mehreren Stücken, und hältst sie über batch und part zusammen. Die Teile bitte nacheinander oder mit wenigen parallelen Verbindungen senden.

BATCH="vollbestand-2026-09-15"
for i in 1 2 3; do
  curl -X POST "https://app.work7.net/api/v1/inbound?source=kplus&batch=$BATCH&part=$i%2F3&filename=export.part$i" \
    -H "Authorization: Bearer $WORK7_API_KEY" \
    -H "Content-Type: application/octet-stream" \
    --data-binary @"export.part$i" || exit 1
done

Jede Anfrage liefert ihre eigene id und Prüfsumme. Schlägt ein Teil fehl, sendest du nur diesen Teil erneut.

Protokoll abfragen

GET /inbound listet alle Lieferungen des Betriebs, neueste zuerst. Paginierung über limit (höchstens 200, Standard 50) und offset, Filter nach Quelle über source. Braucht int.inbound:read; ein Schlüssel mit int.inbound:write darf das ebenfalls.

curl "https://app.work7.net/api/v1/inbound?source=kplus&limit=20" \
  -H "Authorization: Bearer $WORK7_API_KEY"

{
  "data": [
    {
      "id": 42,
      "source": "kplus",
      "filename": "export-2026-09-15.zip",
      "content_type": "application/zip",
      "size_bytes": 1048576,
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "batch": null,
      "part": null,
      "received_at": "2026-09-15T12:30:00.000Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 1, "hasMore": false }
}

Vollständigkeit prüfen

sha256 ist die SHA-256-Prüfsumme der Bytes, die Work7 abgelegt hat (Hex). Stimmt sie mit der Prüfsumme der gesendeten Datei überein, ist die Lieferung vollständig angekommen.

sha256sum export-2026-09-15.zip        # Linux
shasum -a 256 export-2026-09-15.zip    # macOS
certutil -hashfile export-2026-09-15.zip SHA256   # Windows

Limits und Fehler

• Größe: höchstens 2048 MB je Anfrage.
• Schlüssel: 600 Anfragen pro Minute.
• Je Client-IP: höchstens 10 gleichzeitige Verbindungen und 120 Anfragen pro Minute. Darüber antwortet der Server mit 503 ohne JSON-Body.

HTTP	error	Bedeutung
400	validation_error	source fehlt oder ist ungültig, Body ist leer, batch/part zu lang
401	unauthorized	Schlüssel fehlt, ist ungültig oder widerrufen
403	insufficient_scope	Schlüssel hat den Scope int.inbound:write bzw. int.inbound:read nicht
403	module_disabled	Public API (int.api) oder Datenablage (int.inbound) ist für den Betrieb nicht freigeschaltet
413	payload_too_large	Datei größer als erlaubt; details.maxBytes nennt das Limit
429	rate_limited	Zu viele Anfragen mit diesem Schlüssel; Retry-After abwarten
503	–	Zu viele Verbindungen oder Anfragen von derselben IP

Beispiele:

{ "error": "validation_error", "message": "source ist Pflicht (a-z, 0-9, - und _, max. 40 Zeichen), z. B. ?source=kplus." }

{
  "error": "payload_too_large",
  "message": "Datei zu groß (max. 2048 MB). Größere Bestände in Teilen mit batch/part senden.",
  "details": { "maxBytes": 2147483648 }
}

Was mit den Dateien passiert

Work7 legt jede Lieferung unverändert in einem privaten Speicher ab, getrennt nach Betrieb und Quelle. Es gibt keinen öffentlichen Link auf die Dateien. Die Auswertung, also das Übernehmen von Kontakten, Projekten oder Artikeln in Work7, richtet Work7 später je Anbindung ein. Bis dahin bleiben die Lieferungen unverarbeitet im Protokoll.

Wie es weitergeht

• Authentifizierung und Scopes: Schlüssel anlegen und widerrufen.
• Fehler und Limits: Fehlerformat und Rate-Limit der gesamten API.
• API-Referenz: alle Endpunkte interaktiv.