Ressource: addresses #

Kunden- und Interessenten-Adressen der EULANDA-Tabelle Adresse. Die Neuanlage läuft serverseitig über die EULANDA-Prozedur cn_AdNew und übernimmt damit die Vorlagen-Adresse .MUSTER (Anrede, Vorbelegungen, Merkmale), bevor die übergebenen Felder gesetzt werden.

Endpunkte #

Methode	Pfad	Scope	Zweck
GET	`/api/v1/addresses`	`addresses:read`	Liste mit Paging, Filtern, `changedSince`, `categoryAnd/Or/Not`
GET	`/api/v1/addresses/categories`	`addresses:read`	Merkmalbaum für den Merkmal-Filter, siehe Merkmale
GET	`/api/v1/addresses/{id}/categories`	`addresses:read`	Merkmale einer Adresse
GET	`/api/v1/addresses/{id}/service-articles`	`service-articles:read`	Geräte des Kunden, siehe Serviceartikel
PUT/PATCH	`/api/v1/addresses/{id}/categories`	`addresses:write`	Merkmal-Zuordnung ersetzen bzw. ändern
GET	`/api/v1/addresses/ids`	`addresses:read`	Schlüsselliste für den Lösch-Abgleich
GET	`/api/v1/addresses/{id}`	`addresses:read`	Einzelne Adresse über die Id
GET	`/api/v1/addresses/by-match/{match}`	`addresses:read`	Einzelne Adresse über den Matchcode
POST	`/api/v1/addresses`	`addresses:write`	Adresse anlegen (`cn_AdNew` + Felder)
PATCH	`/api/v1/addresses/{id}`	`addresses:write`	Felder ändern (partiell)
DELETE	`/api/v1/addresses/{id}`	`addresses:write`	Löschen, nur wenn unbenutzt (`cnf_AdCanDelete`)

Belege werden nie über DELETE entfernt; bei Adressen ist DELETE erlaubt, solange keine Belege oder Bewegungsdaten auf die Adresse verweisen - sonst antwortet die API mit 409 ADDRESS_IN_USE. Die Vorlage .MUSTER ist geschützt (409 ADDRESS_TEMPLATE_PROTECTED).

Felder (Glossar Entwurf) #

API-Feld	DB-Spalte	Typ	Schreibbar
`id`	`ID`	int	nein
`uid`	`uid`	guid	nein
`match`	`Match`	string	ja (wird über `cnf_AdUniqueMatch` eindeutig gemacht); nur Großbuchstaben, Ziffern und dateinamen-sichere Zeichen, Umlaute transliteriert (Ö -> OE) - als `pattern`/`maxLength` auch in `openapi.json`
`name`	`Name1`	string	ja
`name2` .. `name4`	`Name2` .. `Name4`	string	ja
`street`	`Strasse`	string	ja
`poBox`	`Postfach`	string	ja
`zip`	`PLZ`	string	ja
`city`	`Ort`	string	ja
`country`	`Land`	string	ja (Format je nach Mandanten-Einstellung KFZ oder ISO)
`state`	`Provinz`	string	ja
`phone`	`Tel`	string	ja
`fax`	`Fax`	string	ja
`mobile`	`Auto`	string	ja
`email`	`EMail`	string	ja
`website`	`Homepage`	string	ja
`vatId`	`UstId`	string	ja
`taxNumber`	`SteuerNr`	string	ja
`gln`	`ILN`	string	ja
`salutation`	`Anrede`	string	ja
`group`	`AdresseGr`	string	ja
`language`	`Sprache`	string	ja
`iban` / `bic` / `accountHolder`	`BankIBAN` / `BankBIC` / `BankKontoinhaber`	string	ja
`peppolId`	`PeppolId`	string	ja
`isCustomer` / `isSupplier`	`DebitorFlg` / `KreditorFlg`	bool	nein
`createdAt` / `changedAt`	`CreateDate` / `ChangeDate`	datetime	nein

Beispiele #

Liste mit Feld-Auswahl:

$h = @{ Authorization = "Bearer $key" }
Invoke-RestMethod 'http://localhost:8100/api/v1/addresses?limit=3&fields=id,match,city' -Headers $h

curl.exe -H "Authorization: Bearer %KEY%" "http://localhost:8100/api/v1/addresses?limit=3&fields=id,match,city"

{
  "items": [
    { "id": 2, "match": "EISENHANDLUNG", "city": "Wiesbaden" },
    { "id": 3, "match": "MUSTERMANN", "city": "Steinhausen" }
  ],
  "total": 9, "limit": 3, "offset": 0
}

Anlegen:

$headers = @{ Authorization = "Bearer $key" }
$body = @{
    name    = 'REST Testkunde GmbH'
    match   = 'REST-TEST'
    street  = 'Musterweg 1'
    zip     = '63741'
    city    = 'Aschaffenburg'
    country = 'DE'
    email   = 'test@example.com'
} | ConvertTo-Json

$created = Invoke-RestMethod -Uri 'http://localhost:8100/api/v1/addresses' `
    -Method Post -Headers $headers -ContentType 'application/json' -Body $body
$created.id   # neue Adress-Id

curl.exe -X POST -H "Authorization: Bearer %KEY%" -H "Content-Type: application/json" -d "{ \"name\": \"REST Testkunde GmbH\", \"match\": \"REST-TEST\", \"city\": \"Aschaffenburg\" }" "http://localhost:8100/api/v1/addresses"

Ändern:

$patch = @{ city = 'Mainz'; phone = '06131 123456' } | ConvertTo-Json
Invoke-RestMethod 'http://localhost:8100/api/v1/addresses/287' `
    -Method Patch -Headers $headers -ContentType 'application/json' -Body $patch

curl.exe -X PATCH -H "Authorization: Bearer %KEY%" -H "Content-Type: application/json" -d "{ \"city\": \"Mainz\", \"phone\": \"06131 123456\" }" "http://localhost:8100/api/v1/addresses/287"

Delta-Sync:

$delta = Invoke-RestMethod -Headers $headers -Uri `
    'http://localhost:8100/api/v1/addresses?changedSince=2026-07-18T06:00:00&fields=id,match,changedAt'
# danach: GET /api/v1/addresses/ids und lokal abgleichen, was entfernt wurde

curl.exe -H "Authorization: Bearer %KEY%" "http://localhost:8100/api/v1/addresses?changedSince=2026-07-18T06:00:00&fields=id,match,changedAt"
curl.exe -H "Authorization: Bearer %KEY%" "http://localhost:8100/api/v1/addresses/ids"

Fehlercodes dieser Ressource #

HTTP	Code	Bedeutung
404	`NOT_FOUND`	Keine Adresse zum Schlüssel
409	`ADDRESS_IN_USE`	Löschen abgelehnt, Adresse wird referenziert
409	`ADDRESS_TEMPLATE_PROTECTED`	`.MUSTER` darf nicht geändert oder gelöscht werden
422	`VALIDATION_FIELD_UNKNOWN`	Unbekanntes Feld im Body
422	`VALIDATION_FIELD_READONLY`	Schreibgeschütztes Feld im Body
422	`VALIDATION_NO_FIELDS`	Body ohne schreibbare Felder