API-Beschreibung#

Über eine REST-API können Sie synchron auf den Server zugreifen. Die API ist unter /api erreichbar.

Da der Server mit Mehr-Faktor-Authentifizierung abgesichert ist, benötigen Sie für den Zugriff einen API-Key: livectl login erzeugt einen langlebigen Schlüssel (live_api_…) und speichert ihn in der lokalen livectl-Konfiguration. Anders als kurzlebige Session-Token bleibt der Key gültig, bis er zurückgezogen wird; im HTTP-Header wird er mit dem Schema ApiKey gesendet.

Der empfohlene Weg für Import und Export ist der CLI livectl (siehe Aufträge und Download). Die REST-API ist für den direkten, programmatischen Zugriff gedacht.

API-Key erzeugen#

Den Key legen Sie einmalig per Login an und lesen ihn danach über livectl aus:

# einmalig: Login (Registrierungstoken), erzeugt und speichert den API-Key
livectl login

# gespeicherten API-Key ausgeben (für Skripte)
TOKEN=$(livectl bearer)

livectl login gibt den Key nicht auf stdout aus — für Skripte nutzen Sie immer livectl bearer.

curl#

curl -H "Authorization: ApiKey $(livectl bearer)" https://app.inkasso.live/api/status -s | jq

In Einzelschritten:

TOKEN=$(livectl bearer)
curl -H "Authorization: ApiKey $TOKEN" https://app.inkasso.live/api/status -s | jq
curl -H "Authorization: ApiKey $TOKEN" https://app.inkasso.live/admin/right -s | jq

Hinzufügen eines Auftragstypen:

TOKEN=$(livectl bearer)
curl -H "Authorization: ApiKey $TOKEN" https://app.inkasso.live/api/assignment-type -s \
  | jq '. += [{"id":"neu","Name":"Neue Auftragsart"}]' \
  | curl -X POST -H "Authorization: ApiKey $TOKEN" -H "Content-Type: application/json" -d @- https://app.inkasso.live/api/assignment-type/import

Datenimport (FSG1/FSG2/FSG3)#

Der Datenaustausch für Aufträge läuft über die generische Import-Schnittstelle mit dem jeweiligen DTO (fsg1 = Neuaufträge, fsg2 = Statusänderungen, fsg3 = Aufträge/Export). Der einfachste und empfohlene Weg ist der CLI:

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

Feste Endpunkte wie /api/fsg1, /api/fsg2 oder /api/fsg3 sind in 1.5 nicht der zugesicherte Zugang. Nutzen Sie für den programmatischen Import die generische Import-Schnittstelle mit dem passenden DTO. Brauchen Sie einen konkreten REST-Endpunkt, sprechen Sie uns an — die genaue Route klären wir auf Anfrage.

Python-Beispiel#

Ggf. muss noch requests installiert werden:

python3 -m venv ~/venv-test
source ~/venv-test/bin/activate
pip install requests

Dann das script aufrufen:

TOKEN=$(livectl bearer) && python3 test.py $TOKEN

import requests
import json
import sys

def main(token):
    url_get = "https://app.inkasso.live/api/assignment-type"
    url_post = "https://app.inkasso.live/api/assignment-type/import"
    headers = {
        "Authorization": f"ApiKey {token}",
        "Content-Type": "application/json"
    }

    # GET
    resp = requests.get(url_get, headers={"Authorization": f"ApiKey {token}"})
    if not resp.ok:
        print(f"GET fehlgeschlagen: {resp.status_code} {resp.text}", file=sys.stderr)
        sys.exit(1)

    try:
        data = resp.json()
    except Exception as e:
        print(f"Fehler beim Parsen des JSON: {e}", file=sys.stderr)
        sys.exit(2)

    # Erweitern
    data.append({"id": "neu", "Name": "Neue Auftragsart"})

    # POST
    resp2 = requests.post(url_post, headers=headers, data=json.dumps(data))
    if not resp2.ok:
        print(f"POST fehlgeschlagen: {resp2.status_code} {resp2.text}", file=sys.stderr)
        sys.exit(3)

    print(resp2.text)

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print(f"Usage: {sys.argv[0]} <api-key>", file=sys.stderr)
        sys.exit(4)
    main(sys.argv[1])