REST-API HomeId

Basis-URL (Produktion):

https://homeid.arvelos-service.de/api

Pfadparameter {carrierId}: ITU-Code Ihrer Organisation.
Auth: Header accessToken (Token aus Carrier → Allgemein).
Vertrag: OpenAPI CustomerRequest.yaml, live unter /v3/api-docs bzw. Swagger UI.

Platzhalter: $TOKEN, $CARRIER, $REQUEST_ID.

Anfrage anlegen

POST /api/homeId/{carrierId} → 201

curl -sS -X POST "https://homeid.arvelos-service.de/api/homeId/$CARRIER" \
  -H "Content-Type: application/json" \
  -H "accessToken: $TOKEN" \
  -d '{
    "ekp": "DEU.FIRMA",
    "lineId": "L-10001",
    "name": "Max Mustermann",
    "email": "kunde@example.org",
    "address": "Musterweg 1, 12345 Musterstadt",
    "mobile": "",
    "technologyId": "",
    "customMap": { "vertrag": "V-42" }
  }'

ekp muss einer konfigurierten EKP-Id entsprechen. technologyId leer = Standardvariante. homeId im Body wird verworfen. customMap ist opaque (nicht auf der Kundenseite). Pflicht für den Mailversand: syntaktisch gültige E-Mail.

Antwort enthält requestId und requestStatus: OPEN.

Listen / lesen

# optional ?lineId=
curl -sS "https://homeid.arvelos-service.de/api/homeId/$CARRIER?lineId=L-10001" \
  -H "accessToken: $TOKEN"

curl -sS "https://homeid.arvelos-service.de/api/homeId/$CARRIER/$REQUEST_ID" \
  -H "accessToken: $TOKEN"

Unbekannte Id: 404.

Ergebnisse abholen (Polling)

GET /api/homeId/{carrierId}/getHomeIds

Liefert DONE und noch nicht closed.
?mark=true setzt die gelieferten Sätze auf CLOSED (exactly-once-Abholung für das Fachsystem).

curl -sS "https://homeid.arvelos-service.de/api/homeId/$CARRIER/getHomeIds?mark=true" \
  -H "accessToken: $TOKEN"

Schließen / löschen

curl -sS -X POST "https://homeid.arvelos-service.de/api/homeId/$CARRIER/$REQUEST_ID/setClosed" \
  -H "accessToken: $TOKEN"

curl -sS -X DELETE "https://homeid.arvelos-service.de/api/homeId/$CARRIER/$REQUEST_ID" \
  -H "accessToken: $TOKEN"

DELETE → 204; unbekannt → 404.

Status und Fehlercodes

failureCode: OK | CANNOT_FIND | UNREADABLE | INACCESSIBLE | OTHER (+ failureText).

Ungültiges Token / unbekannter Carrier: fachlicher Fehler (Bad/Unknown carrier), keine Browser-Anmeldung auf /api/**.

Bounce-Webhook

POST /api/bounceListener ist der Inbound-Hook des Mail-Providers (Postmark), nicht für Ihr Fachsystem. Ein Bounce setzt die Anfrage auf FAILED.