API docs by Redocly

live-API (1.6.1000-161)

Download OpenAPI specification:

HTTP-Schnittstelle des live-Servers.

Für Anbindungen ist nur der Bereich public freigegeben: Anmeldung per API-Key sowie Aufträge anlegen, lesen, auflisten und ändern. Dieser Teil ist stabil – er wird nur noch erweitert, nichts fällt weg und nichts ändert seine Bedeutung. Alle Endpunkte unter internal dienen der Web-App und den Werkzeugen und können sich ohne Ankündigung ändern.

Konventionen

  • Alle Inhalte sind JSON (content-type: application/json).
  • Zeitpunkte sind Millisekunden seit 1970 (UTC).
  • Fehler kommen als JSON mit festem code (z. B. policy.missing_right), category, status und message. Entscheiden Sie über code, nie über message. 401: Schlüssel fehlt oder ist ungültig. 403: Dem Konto fehlt das Recht.
  • Antworten können Felder enthalten, die hier nicht beschrieben sind; ignorieren Sie unbekannte Felder.

1. Anmelden

Jede Anfrage trägt den 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. 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 (results.<Leistung>.<Feld>).

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 plus 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. Löschen gibt es nicht; storniert wird per Statuswechsel.

Die Feldnamen sind englisch; die Zuordnung zu den Spalten des fsg3-Formats steht bei jedem Feld.

Zu jedem dieser Endpunkte zeigt diese Seite ein vollständiges Beispiel.

public

Die freigegebene, stabile Schnittstelle: Anmeldung per API-Key und Aufträge anlegen, lesen, auflisten und ändern. Sie wird nur noch erweitert.

Aufträge auflisten (FSG, fsg3)

Schritt 4 des Standardablaufs: Aufträge auflisten, jede Zeile in derselben Form wie beim Lesen.

Filter, Sortierung und Seiten lassen sich kombinieren. Die erste Seite liefert nextCursor; dieselbe Anfrage mit cursor=<nextCursor> liefert die Folgeseite, bis nextCursor fehlt.

Beispiel erste Seite: GET /api/dto/fsg3?filter=status%3Dto_confirm&sort=subjectDisplayName&limit=2 mit dem Kopf x-api-key.

Authorizations:
apiKeyAuth
query Parameters
filter
string
Example: filter=status=to_confirm

Filter, wiederholbar: status=<stand>, ref=<aktenzeichen> oder ein Datumsbereich wie modified>=<ms>.

search
string

Freitextsuche (Name, Aktenzeichen, Adresse).

sort
string
Example: sort=subjectDisplayName

Sortierfeld, z. B. ref, subjectDisplayName, status, editedAt, dueDate. Ohne Angabe nach Auftrags-ID.

dir
string
Enum: "asc" "desc"

asc (Vorgabe) oder desc.

limit
integer [ 1 .. 1000 ]
Example: limit=2

Seitengröße (Vorgabe 100, höchstens 1000).

cursor
string

nextCursor der vorigen Seite, unverändert.

offset
integer >= 0

Alternative zum Cursor: Position der Seite.

lifecycle
string

active (Vorgabe), inactive oder all.

Responses

Response samples

Content type
application/json
Example
{
  • "filter": [
    ],
  • "total": 3,
  • "offset": 0,
  • "limit": 2,
  • "returned": 2,
  • "nextCursor": "eyJrIjoiZXlKemIzSjBWbUZzZFdVaU9pSndaWFJ5WVNCaVpXbHpjR2xsYkNJc0ltRnpjMmxuYm0xbGJuUkpaQ0k2SWpObU5tUXlZekZsSW4wIiwibiI6Mn0",
  • "rows": [
    ]
}

Auftrag anlegen (FSG, fsg3)

Schritt 2 des Standardablaufs: einen FSG-Auftrag anlegen. Der Ausführende wird wie beim Import über die PLZ des Schuldners zugeordnet. Die Antwort nennt das Aktenzeichen, unter dem der Auftrag gelesen und geändert wird.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
id
string

Eigene Auftrags-ID (optional). Ein zweites Anlegen mit derselben ID wird abgewiesen.

tenantId
string

Mandant; entfällt, wenn der Key genau einem Mandanten gehört.

clientId
string

Einspeisender; entfällt, wenn der Key zu einem Einspeisenden gehört.

required
object
required
object
object
object
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "3f6d2c1e-7b4a-4c1e-9a53-2b8e0c4d7f10",
  • "tenantId": "tenant-demo1",
  • "clientId": "a403fc5a-0213-485a-95f1-091a5daf51f7",
  • "order": {
    },
  • "subject": {
    },
  • "creditor": {
    }
}

Response samples

Content type
application/json
{
  • "assignmentId": "3f6d2c1e-7b4a-4c1e-9a53-2b8e0c4d7f10",
  • "ref": "100036",
  • "dataVersion": 1790222260000
}

Auftrag lesen, mit Ergebnissen (FSG, fsg3)

Schritt 3 des Standardablaufs: einen Auftrag vollständig lesen – Auftragsdaten, Schuldner, Gläubiger, Status mit Datumswerten und die Ergebnisse je Leistung. Es erscheint nur, was das Konto auch in der App sehen darf.

Authorizations:
apiKeyAuth
path Parameters
ref
required
string
Example: 100036

Aktenzeichen des Auftrags; die Auftrags-ID geht ebenso.

Responses

Response samples

Content type
application/json
{
  • "assignment": {
    }
}

Auftrag ändern (FSG, fsg3)

Schritt 5 des Standardablaufs: einen Auftrag ändern.

Nur die genannten Felder ändern sich, null leert ein Feld, status.status wechselt den Status – sofern das Konto das in der App darf. Der Aufruf gilt ganz oder gar nicht: ein unbekanntes, nicht änderbares oder nicht erlaubtes Feld weist ihn ab, bevor etwas geschrieben wird. Löschen gibt es nicht; storniert wird per Statuswechsel. Die Antwort ist der Auftrag nach der Änderung.

Authorizations:
apiKeyAuth
path Parameters
ref
required
string
Example: 100036

Aktenzeichen des Auftrags; die Auftrags-ID geht ebenso.

Request Body schema: application/json
required
object
object
object
object
property name*
additional property
any

Responses

Request samples

Content type
application/json
Example
{
  • "order": {
    }
}

Response samples

Content type
application/json
{
  • "assignment": {
    },
  • "dataVersion": 1790222290000
}