API DOCS

SCHNELLSTART

In drei Schritten zum ersten Auftrag aus Ihrem System.

1. Im Portal unter Einstellungen → API einen Schlüssel erstellen und sicher ablegen – er wird nur einmal angezeigt.
2. Auftrag anlegen (Beispiel unten) – die Antwort enthält die job_id.
3. Optional einen Webhook anlegen: Doclution meldet dann Abschluss, Fotos und Bericht von selbst.

curl -X POST "https://doclution.de/api_jobs.php?action=create" \
  -H "Authorization: Bearer dlk_DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference":"LS-2026-10045","users":["maxmuster"],"requirements":[{"label":"Lieferschein","type":"dokument","count":1}]}'

AUTHENTIFIZIERUNG

Jeder Aufruf braucht einen gültigen, aktiven und nicht abgelaufenen API-Schlüssel. Schlüssel beginnen mit dlk_ und gehören fest zu einer Firma – Sie sehen und ändern ausschließlich Daten Ihrer eigenen Firma. Doclution speichert nur einen Fingerabdruck (SHA-256) des Schlüssels; ein verlorener Schlüssel kann nicht wiederhergestellt, nur ersetzt werden.

Rechte je Schlüssel

LIMITS

Abfrage-Limit je API-Schlüssel und Kalenderstunde (z. B. 14:00–14:59). Jede Antwort nach erfolgreicher Anmeldung trägt den aktuellen Stand.

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187

{"success":false,"error":"Zu viele Anfragen: hoechstens 200 pro Stunde und API-Schluessel.","retry_after":1091}

Tipp: Statt regelmäßig abzufragen, lassen Sie sich per Webhook benachrichtigen und holen nur die geänderten Aufträge (updated_since).

ANTWORTEN & FEHLER

Anfragen gehen an https://doclution.de/api_jobs.php, die Aktion steht im Parameter action. Daten für POST dürfen als JSON (Content-Type: application/json) oder als Formular (application/x-www-form-urlencoded) kommen; beides wird zusammengeführt. id darf bei update, complete und delete auch in der Adresse stehen.

{ "success": true, … }

{ "success": false, "error": "Auftrag nicht gefunden." }

Zeitangaben sind Ortszeit Deutschland (Europe/Berlin) im Format JJJJ-MM-TT hh:mm:ss. Zahlen aus Summen (z. B. total_required) kommen als Text. Die Ausgabe ist eingerückt (Pretty-Print) und UTF-8.

AUFTRÄGE AUFLISTEN

Paginierte Liste der Aufträge Ihrer Firma (ohne Papierkorb), neueste zuerst. Ohne action liefert ein GET ebenfalls die Liste.

curl "https://doclution.de/api_jobs.php?action=list&status=open&limit=50&updated_since=2026-10-26T08:00:00%2B01:00" \
  -H "Authorization: Bearer dlk_DEIN_API_KEY"

{
    "success": true,
    "total": 84,
    "limit": 50,
    "offset": 0,
    "jobs": [
        {
            "id": 42,
            "job_reference": "LS-2026-10045",
            "status": "open",
            "job_comment": "Bitte Nummernschild fotografieren",
            "created_at": "2026-10-26 09:30:00",
            "updated_at": null,
            "deleted_at": null,
            "total_required": "6",
            "total_photos": 4,
            "assigned_users": "maxmuster, annaschmidt"
        }
    ]
}

AUFTRAG ABRUFEN

Ein Auftrag mit allen Feldern, Anforderungen, zugewiesenen Mitarbeitern und Fotos.

{
    "success": true,
    "job": {
        "id": 42,
        "job_reference": "LS-2026-10045",
        "status": "completed",
        "job_comment": "Bitte Nummernschild fotografieren",
        "customer_name": "Muster GmbH",
        "due_date": "2026-10-27",
        "template_id": 7,
        "created_at": "2026-10-26 09:30:00",
        "updated_at": "2026-10-26 11:25:12",
        "completed_at": "2026-10-26 11:25:12",
        "deleted_at": null,
        "…": "weitere Auftragsfelder",
        "requirements": [
            { "label_name": "Lieferschein", "photo_type": "dokument", "req_count": 1 }
        ],
        "assigned_users": [
            { "id": 7, "username": "maxmuster" }
        ],
        "photos": [
            {
                "id": 301,
                "file_path": "uploads/company_12/…/foto.jpg",
                "label_name": "Lieferschein",
                "photo_type": "dokument",
                "captured_at": "2026-10-26 11:20:00",
                "lat": "51.48", "lng": "11.97",
                "download_url": "https://doclution.de/api_jobs.php?action=photo&id=301"
            }
        ]
    }
}

{ "success": false, "error": "id fehlt." }
{ "success": false, "error": "Auftrag nicht gefunden." }

FOTO HERUNTERLADEN

Liefert die Bilddatei selbst (kein JSON) – mit demselben API-Schlüssel im Header.

curl -o foto_301.jpg "https://doclution.de/api_jobs.php?action=photo&id=301" \
  -H "Authorization: Bearer dlk_DEIN_API_KEY"

BERICHT-PDF

Neu. Liefert einen signierten Download-Link auf den PDF-Bericht – derselbe Weg wie der Bericht-Link in den Abschluss-Mails. Der Link ist 15 Minuten gültig und braucht keinen Schlüssel; holen Sie ihn deshalb erst unmittelbar vor dem Download und geben Sie ihn nicht weiter.

{
    "success": true,
    "job_id": 42,
    "reference": "LS-2026-10045",
    "status": "completed",
    "report_url": "https://doclution.de/report_download.php?t=…",
    "expires_in": 900,
    "expires_at": "2026-10-26T11:40:12+01:00"
}

URL=$(curl -s "https://doclution.de/api_jobs.php?action=report&id=42" -H "Authorization: Bearer dlk_DEIN_API_KEY" | jq -r .report_url)
curl -o bericht_42.pdf "$URL"

AUFTRAG ANLEGEN

Legt einen offenen Auftrag an, weist optional Mitarbeiter zu und definiert Foto-Anforderungen und Datenfelder. Schreibrecht nötig.

{
  "reference": "LS-2026-10045",
  "comment": "Bitte Nummernschild fotografieren",
  "users": ["maxmuster", 12],
  "requirements": [
    { "label": "Lieferschein", "type": "dokument", "count": 1 },
    { "label": "Ladung",       "type": "ladung",   "count": 4 },
    { "label": "Kilometerstand", "type": "feld" }
  ]
}

{
    "success": true,
    "message": "Auftrag erstellt.",
    "job_id": 42,
    "reference": "LS-2026-10045"
}

400 { "success": false, "error": "reference fehlt." }
409 { "success": false, "error": "Referenz 'LS-2026-10045' existiert bereits." }
503 { "success": false, "retry": true, "error_code": "TRY_AGAIN", "error": "Datenbank gerade ausgelastet - bitte erneut senden." }
500 { "success": false, "error": "Fehler beim Erstellen: …" }

AUFTRAG BEARBEITEN

Ändert einzelne Felder; nicht übergebene Felder bleiben, wie sie sind. Schreibrecht nötig.

{ "success": true, "message": "Auftrag aktualisiert.", "job_id": 42 }

AUFTRAG ABSCHLIEẞEN

Setzt den Status auf completed und den Fertig-Zeitpunkt. Anders als der Abschluss in der App werden dabei keine Pflichtfotos geprüft und keine Bericht-Mail verschickt. Schreibrecht nötig.

{ "success": true, "message": "Auftrag abgeschlossen.", "job_id": 42 }

AUFTRAG LÖSCHEN

Verschiebt einen Auftrag in den Papierkorb (wiederherstellbar im Portal). Per POST ?action=delete oder HTTP DELETE. Schreibrecht nötig.

{ "success": true, "message": "Auftrag in Papierkorb verschoben.", "job_id": 42 }

NUTZER ABRUFEN

Alle aktiven App-Nutzer (Rolle Mitarbeiter) – zum Befüllen von users beim Anlegen. Bewusst nur ID und Benutzername, keine Mailadressen.

{
    "success": true,
    "users": [
        { "id": 7,  "username": "maxmuster" },
        { "id": 12, "username": "annaschmidt" }
    ]
}

SELBSTAUSKUNFT

GET ?action=docs liefert eine kurze maschinenlesbare Übersicht der Aktionen (Name, Methode, Parameter). Vollständig und aktuell ist die OpenAPI-Datei.

VERLADE-XML ABHOLEN

Für das Modul Paletten-Scan: Ihre Warenwirtschaft holt die erzeugten XML-Dateien ab, statt auf die Mail zu warten. Adresse https://doclution.de/api_pallet_xml.php, gleiche Anmeldung und Limits. Benötigt zusätzlich das Modul Paletten-Scan im Tarif (sonst 403).

Warum getrennt? Wer beim Laden abstürzt, bekommt die Datei beim nächsten Lauf erneut – erst die Quittung nimmt sie aus der Liste.

WEBHOOKS

Doclution schickt bei jedem Ereignis einen HTTPS-POST mit JSON an Ihre Adresse – innerhalb etwa einer Minute. Anlegen im Portal unter Einstellungen → API → Webhooks: Adresse eintragen, Ereignisse wählen, das angezeigte Signatur-Geheimnis (whsec_…, nur einmal sichtbar) in Ihrem System hinterlegen. Mit „Test senden" kommt sofort ein test.ping.

Ereignisse

Nutzlast

Bewusst schlank: IDs, Auftragsnummer, Status und Links zur API – keine Fotos, Namen oder Mailadressen. Details holen Sie bei Bedarf per API.

POST /doclution/webhook HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: Doclution-Webhooks/1.0
X-Doclution-Event: job.completed
X-Doclution-Delivery: 81723
X-Doclution-Attempt: 1
X-Doclution-Signature: t=1793015112,v1=5d41402abc4b2a76b9719d911017c592…

{
  "id": "evt_9f3c2a7d1e5b4c8a6f0e1d2c",
  "type": "job.completed",
  "created": "2026-10-26T10:25:12Z",
  "api_version": "2026-10-26",
  "data": {
    "job": {
      "id": 42,
      "reference": "LS-2026-10045",
      "status": "completed",
      "previous_status": "open",
      "template_id": 7,
      "due_date": "2026-10-27",
      "created_at": "2026-10-26 09:30:00",
      "updated_at": "2026-10-26 11:25:12",
      "completed_at": "2026-10-26 11:25:12"
    },
    "links": {
      "job": "https://doclution.de/api_jobs.php?action=get&id=42",
      "report": "https://doclution.de/api_jobs.php?action=report&id=42"
    }
  }
}

{
  "photo": { "id": 301, "job_id": 42, "photo_type": "dokument", "label": "Lieferschein",
             "group": "", "unit_index": 0, "captured_at": "2026-10-26 11:20:00", "storage": "doclution" },
  "job":   { "id": 42, "reference": "LS-2026-10045", "status": "open" },
  "links": { "photo": "https://doclution.de/api_jobs.php?action=photo&id=301",
             "job":   "https://doclution.de/api_jobs.php?action=get&id=42" }
}

Bei job.created steht in job.source, woher der Auftrag kommt (portal, app, leitstand, nachtrag, api); Folge- und Ergänzungsaufträge tragen parent_job_id. Neue Felder können hinzukommen – bitte unbekannte Felder ignorieren.

Antwort, Wiederholungen, Abschalten

• Antworten Sie innerhalb von 10 Sekunden mit einem 2xx-Status. Verarbeiten Sie aufwendige Dinge danach (Warteschlange).
• Alles andere (Timeout, Verbindungsfehler, 3xx, 4xx, 5xx) gilt als Fehlschlag. Weiterleitungen werden nicht verfolgt.
• Neue Versuche nach 1 min, 5 min, 30 min, 2 h und 12 h – danach wird die Meldung aufgegeben. X-Doclution-Attempt zählt mit.
• Nach 20 Fehlschlägen in Folge schaltet Doclution den Webhook ab und schreibt dem Manager eine Mail. Wieder einschalten im Portal.
• Die Reihenfolge ist nicht garantiert, und eine Meldung kann (selten) doppelt kommen: Entdoppeln Sie über id (Ereignis) bzw. X-Doclution-Delivery und werten Sie Status über created/updated_at aus.
• Das Protokoll der letzten Zustellungen (mit Nutzlast und Antwort) sehen Sie 30 Tage lang im Portal.

Anforderungen an die Adresse

• Nur https:// mit gültigem Zertifikat, Port 443 oder 8443, ohne Zugangsdaten in der Adresse.
• Keine internen Ziele: Doclution löst den Namen auf und lehnt private, lokale und reservierte Adressen ab (z. B. 10.x, 192.168.x, 127.x, 169.254.x, ::1, fc00::/7) – beim Anlegen und vor jeder Zustellung.
• Höchstens 10 Webhooks je Firma.

SIGNATUR PRÜFEN

Jede Meldung trägt X-Doclution-Signature: t=<Unix-Zeit>,v1=<hex>. v1 ist HMAC-SHA256 mit Ihrem Geheimnis über <t>.<roher Body>. Prüfen Sie immer gegen den unveränderten Body (nicht neu serialisieren), vergleichen Sie zeitkonstant und lehnen Sie Zeitstempel ab, die mehr als 5 Minuten abweichen (Schutz gegen Wiederholung).

<?php
$geheim = getenv('DOCLUTION_WEBHOOK_SECRET');          // whsec_…
$body   = file_get_contents('php://input');           // roher Body!
$kopf   = $_SERVER['HTTP_X_DOCLUTION_SIGNATURE'] ?? '';

if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $kopf, $m)
    || abs(time() - (int)$m[1]) > 300
    || !hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $geheim), $m[2])) {
    http_response_code(401);
    exit('Signatur ungueltig');
}

$ereignis = json_decode($body, true);
// Doppelte Zustellung erkennen: $ereignis['id'] merken
http_response_code(200);
echo 'ok';
// … danach verarbeiten, z. B. Auftrag per API nachladen

const express = require('express');
const crypto  = require('crypto');
const app = express();
const GEHEIM = process.env.DOCLUTION_WEBHOOK_SECRET;   // whsec_…

// express.raw: Body als Buffer behalten (nicht express.json!)
app.post('/doclution/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(req.get('X-Doclution-Signature') || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return res.sendStatus(401);
  const soll = crypto.createHmac('sha256', GEHEIM).update(m[1] + '.').update(req.body).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(soll, 'hex'), Buffer.from(m[2], 'hex'))) return res.sendStatus(401);

  const ereignis = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(200);                 // sofort bestätigen …
  verarbeite(ereignis);                // … dann verarbeiten
});
app.listen(3000);

using System.Security.Cryptography;
using System.Text;
using System.Text.RegularExpressions;

var app = WebApplication.Create(args);
var geheim = Environment.GetEnvironmentVariable("DOCLUTION_WEBHOOK_SECRET")!; // whsec_…

app.MapPost("/doclution/webhook", async (HttpRequest req) =>
{
    using var leser = new StreamReader(req.Body, Encoding.UTF8);
    var body = await leser.ReadToEndAsync();                       // roher Body
    var m = Regex.Match(req.Headers["X-Doclution-Signature"].ToString(), "^t=(\\d+),v1=([0-9a-f]{64})$");
    if (!m.Success) return Results.Unauthorized();
    var t = long.Parse(m.Groups[1].Value);
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > 300) return Results.Unauthorized();

    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(geheim));
    var soll = hmac.ComputeHash(Encoding.UTF8.GetBytes($"{t}.{body}"));
    var ist  = Convert.FromHexString(m.Groups[2].Value);
    if (!CryptographicOperations.FixedTimeEquals(soll, ist)) return Results.Unauthorized();

    // Ereignis verarbeiten (z. B. in eine Warteschlange legen)
    return Results.Ok();
});
app.Run();

FEHLERCODES

Fehler haben immer "success": false und einen lesbaren Text in "error".

CODE-BEISPIELE

Auftrag anlegen und geänderte Aufträge abholen.

$ch = curl_init('https://doclution.de/api_jobs.php?action=create');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer dlk_DEIN_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'reference'    => 'LS-2026-10045',
        'users'        => ['maxmuster'],
        'requirements' => [['label' => 'Lieferschein', 'type' => 'dokument', 'count' => 1]],
    ]),
]);
$antwort = json_decode(curl_exec($ch), true);
if (!empty($antwort['success'])) echo 'Auftrag-ID: ' . $antwort['job_id'];

const res = await fetch('https://doclution.de/api_jobs.php?action=list&updated_since=' + encodeURIComponent(letzterAbgleich), {
  headers: { 'Authorization': 'Bearer dlk_DEIN_API_KEY' },
});
const daten = await res.json();
for (const auftrag of daten.jobs) console.log(auftrag.job_reference, auftrag.status);

import requests

r = requests.post(
    "https://doclution.de/api_jobs.php",
    params={"action": "create"},
    headers={"Authorization": "Bearer dlk_DEIN_API_KEY"},
    json={"reference": "LS-2026-10045", "users": ["maxmuster"],
          "requirements": [{"label": "Lieferschein", "type": "dokument", "count": 1}]},
    timeout=30,
)
print(r.status_code, r.json())

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", "dlk_DEIN_API_KEY");
var antwort = await http.PostAsJsonAsync("https://doclution.de/api_jobs.php?action=create", new {
    reference = "LS-2026-10045",
    users = new[] { "maxmuster" },
    requirements = new[] { new { label = "Lieferschein", type = "dokument", count = 1 } }
});
Console.WriteLine(await antwort.Content.ReadAsStringAsync());

OPENAPI

Die vollständige Beschreibung als OpenAPI 3.1 – zum Import in Postman, Insomnia, Swagger UI oder zur Code-Erzeugung.

CHANGELOG

• 26.10.2026 – Webhooks (job.created, job.updated, job.completed, job.reopened, photo.uploaded, report.ready) mit HMAC-Signatur und Wiederholungen. Neu: action=report (Bericht-PDF), Filter updated_since und reference in list, Nur-Lesen-Schlüssel. Behoben: list antwortete mit HTTP 500; Benutzer-IDs in users werden jetzt gegen die eigene Firma geprüft. OpenAPI-Datei.
• 10.10.2026 – Schlüssel nur noch als Fingerabdruck gespeichert, Limit 200 Anfragen/Stunde mit X-RateLimit-*, Fotos über action=photo statt direkter Datei-Adressen, ?api_key= als veraltet markiert.
• 26.09.2026 – template_id beim Anlegen: automatische Auftragsnummer aus dem Nummernkreis der Vorlage.
• v1.0 – Aufträge auflisten, abrufen, anlegen, bearbeiten, abschließen, löschen; Nutzer abrufen.