API-Beschreibung#

Über eine REST-API greifen Sie programmatisch auf Ihre Aufträge zu: anmelden, Aufträge anlegen, lesen, auflisten und ändern. Die vollständige Beschreibung mit Leitfaden, Erklärungen und einem Beispiel je Endpunkt wird bei jedem Bau dieser Seite aus der OpenAPI-Beschreibung des Servers erzeugt:

Beschrieben ist nur der freigegebene, stabile Teil der Schnittstelle. Er wird nur noch erweitert: Nichts fällt weg, nichts ändert seine Bedeutung. Alle übrigen Endpunkte des Servers dienen der Web-App und den Werkzeugen und können sich ohne Ankündigung ändern — bauen Sie darauf keine Anbindung.

Der Ablauf in Kürze#

1. Anmelden. Jede Anfrage trägt einen API-Key im Kopf: x-api-key: live_api_…. Den Key stellt ein Admin für ein Konto aus; er wird nur einmal angezeigt und handelt mit den Rechten dieses Kontos.
2. Auftrag anlegen: POST /api/dto/fsg3 mit order, subject und creditor. In order sind neben den Leistungen (serviceIds) die Aktenzeichen, die Auftragsart, die Forderungsbeträge und die Bankverbindung Pflicht; fehlt etwas, wird nichts angelegt, und die Antwort (validation.fsg3_create_invalid) nennt alle fehlenden Felder auf einmal. Der Ausführende wird über die PLZ des Schuldners zugeordnet. Die Antwort nennt assignmentId und das Aktenzeichen ref.
3. Auftrag lesen: GET /api/dto/fsg3/{ref} — vollständig, mit Status, Datumswerten und Ergebnissen je Leistung.
4. Aufträge auflisten: GET /api/dto/fsg3 mit Filter (filter=status=pending), Suche (search=), Sortierung (sort=subjectDisplayName&dir=asc) und Seitengröße (limit=). Solange die Antwort nextCursor trägt, liefert dieselbe Anfrage mit cursor=<nextCursor> die Folgeseite.
5. Auftrag ändern: PATCH /api/dto/fsg3/{ref} mit den zu ändernden Feldern. Nicht genannte Felder bleiben, null leert ein Feld, { "status": { "status": "cancelled" } } wechselt den Status. Der Aufruf gilt ganz oder gar nicht. Löschen gibt es nicht; storniert wird per Statuswechsel.

Die Feldnamen sind englisch (subject.firstName, subject.postalCode, order.creditorReference …); die Zuordnung zu den Spalten des fsg3-Formats steht in der Beschreibung bei jedem Feld. Fehler kommen als JSON mit festem code; entscheiden Sie über code, nie über message.

Beispiel mit curl#

KEY=live_api_…   # Ihr API-Key
URL=https://<ihr-server>

# anlegen
curl -s -X POST -H "x-api-key: $KEY" -H "content-type: application/json" \
  "$URL/api/dto/fsg3" -d '{
    "order":    { "creditorReference": "GL-2026-0815", "clientReference": "AZ-2026-0815",
                  "serviceIds": ["AD340"], "typeLabel": "std", "showVatToSubject": false,
                  "principalClaim": 1200.00, "costs": 150.00, "interest": 50.00,
                  "payments": 0, "totalClaim": 1400.00, "dailyInterest": 0.10,
                  "bankAccountHolder": "Gläubiger GmbH", "bankBic": "DEMODEBBXXX",
                  "bankIban": "DE14500105170032493100" },
    "subject":  { "firstName": "Petra", "name1": "Beispiel", "street": "Musterweg 1",
                  "postalCode": "33106", "city": "Paderborn" },
    "creditor": { "name1": "Gläubiger GmbH", "street": "Gläubigerweg 1",
                  "postalCode": "33613", "city": "Bielefeld" }
  }' | jq
# {
#   "assignmentId": "c7baaea0-5c80-43d9-9a39-1473453a2cc0",
#   "ref": "100050",
#   "dataVersion": 1791436059397
# }

# lesen (ref aus der Antwort)
curl -s -H "x-api-key: $KEY" "$URL/api/dto/fsg3/<ref>" | jq

# auflisten, erste Seite
curl -s -H "x-api-key: $KEY" "$URL/api/dto/fsg3?filter=status%3Dto_confirm&limit=10" | jq

# ändern: stornieren
curl -s -X PATCH -H "x-api-key: $KEY" -H "content-type: application/json" \
  "$URL/api/dto/fsg3/<ref>" -d '{ "status": { "status": "cancelled" } }' | jq

Datenaustausch per Datei (FSG1/FSG2/FSG3)#

Für den Austausch ganzer Bestände per Datei ist der CLI livectl der empfohlene Weg (siehe Aufträge und Download):

livectl assignments import auftraege.csv --tenant-id <mandant> --dto fsg1
livectl assignments import status.csv    --tenant-id <mandant> --dto fsg2
livectl assignments --dto fsg3 -f csv > auftraege.csv