---
title: "Adresszeilen für Auslandsüberweisungen KI-gestützt strukturieren"
method: POST
path: "/payments/structure-addresses"
tags: ["Zahlungsverkehr"]
---

# Adresszeilen für Auslandsüberweisungen KI-gestützt strukturieren

`POST /payments/structure-addresses`

## Request

- Base URL: `https://finisma.de/api/v1`
- URL: `https://finisma.de/api/v1/payments/structure-addresses`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://finisma.de/api/oauth/authorize`, token URL `https://finisma.de/api/oauth/token`, scopes: `invoice:verify`, `invoice:create`)

Zerlegt bis zu 50 Freitext-Adressen (je 1 bis 4 Zeilen, ISO-Ländercode dazu) per LLM in Ort, Postleitzahl, Straße und Hausnummer, ohne etwas zu erfinden. Bei Unsicherheit kommt confident=false zurück statt eines geratenen Feldes. Erfordert das Feature 'paymentsAbroad' (Auslandsmodul-Add-on, setzt das Zahlungsverkehr-Abo voraus; 'payments' allein reicht hier NICHT, anders als bei bank-lookup). Auth per Login-Session oder Bearer-Credential, unabhängig vom OAuth-Scope. Keine Persistenz der Adressdaten.

## Request body

- AddressStructureRequest
  - `items` object[], required
    - `id` string, required
    - `countryCode` string, required
    - `addressLines` string[], required

## Response `200`

Strukturierungsergebnis je Item, in derselben Reihenfolge wie die Anfrage.

- AddressStructureResponse
  - `items` object[], required
    - `id` string, required
    - `townName` string
    - `postCode` string
    - `streetName` string
    - `buildingNumber` string
    - `addressLines` string[]
    - `confident` boolean, required

## Other responses

- `400`: Request-Body entspricht nicht dem Schema (z. B. mehr als 50 Items).
- `401`: Kein oder ungültiges Credential (code auth_required bzw. invalid_key).
- `403`: Feature 'paymentsAbroad' fehlt (code subscription_required).
- `502`: Der KI-Dienst (OpenAI) ist derzeit nicht erreichbar.

---

[API](https://skmtc.dev/finisma/apis/finisma-rest-api.md) · [All operations](https://skmtc.dev/finisma/apis/finisma-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/finisma/apis/finisma-rest-api/revisions/c1a9acfab69b?raw)