Ort aus PLZ, PLZ aus Ort
Benötigte Berechtigung:contacts:read(Kontakte lesen)
Liefert für Deutschland und Österreich die Orte einer Postleitzahl (cities) oder die Postleitzahlen eines Orts (postalCodes), wie die Vorschläge im Kontakt der App; mit beiden Parametern kommt beides. Kennt das Land die PLZ nicht, das andere aber schon, nennt elsewhere dieses Land, etwa Österreich für 4020. Die Listen sind nicht vollständig, Großkunden- und Postfach-PLZ fehlen oft. Eine unbekannte PLZ ist deshalb kein Fehler, die Listen bleiben dann leer. Für andere Länder kommt supported: false. Ohne postalCode und city antwortet die Route mit 400. Quellen: für Deutschland OpenStreetMap (ODbL 1.0), für Österreich die RTR-GmbH. Zeigst du die Vorschläge an, nenne attribution, bei osm mit Link auf https://www.openstreetmap.org/copyright.
Benötigt einen Schlüssel mit der Berechtigung contacts:read oder read.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
country?stringLand als ISO-Code, DE oder AT; ein Name wie „Österreich“ geht auch.
postalCode?stringPostleitzahl; Leerzeichen zählen nicht.
city?stringOrt, ohne Rücksicht auf Groß- und Kleinschreibung.
Erfolg.
application/json- response
Orte einer Postleitzahl oder Postleitzahlen eines Orts.
attribution?stringNamensnennung, die zu den Vorschlägen gehört, etwa „© OpenStreetMap-Mitwirkende“.
cities?array<string>Orte der Postleitzahl, der häufigste zuerst; leer, wenn die Liste sie nicht kennt. Nur mit postalCode.
city?stringDer angefragte Ort; nur mit city.
country?stringLand der Anfrage als ISO-Code.
elsewhere?Nur wenn das Land die Postleitzahl nicht kennt, das andere (DE oder AT) aber schon.
postalCode?stringDie angefragte Postleitzahl ohne Leerzeichen; nur mit postalCode.
postalCodes?array<string>Postleitzahlen des Orts, aufsteigend, höchstens 20; leer, wenn die Liste den Ort nicht kennt. Nur mit city.
source?stringQuelle der Liste: osm (OpenStreetMap, Deutschland) oder rtr (RTR-GmbH, Österreich); fehlt bei anderen Ländern.
supported?booleantrue für DE und AT, sonst false mit leeren Listen.
curl --fail-with-body "https://app.bimetrics.de/api/address/postal" \ -H "Authorization: Bearer $BIMETRICS_API_KEY"{ "attribution": "© OpenStreetMap-Mitwirkende", "cities": [ "Tostedt", "Kakenstorf", "Wistedt", "Dohren", "Königsmoor", "Otter" ], "country": "DE", "postalCode": "21255", "source": "osm", "supported": true}Beleg erneut lesen POST
Startet die Erkennung eines Belegs neu, dessen Lesen fehlgeschlagen ist (`ocrStatus` `failed`), wie „Erneut lesen“ in der App. Der Beleg wartet danach sofort wieder (`ocrStatus` `pending`), die Antwort ist der Beleg in diesem Stand. Die Datei bleibt dieselbe, du lädst nichts neu hoch. Das erneute Lesen zählt im Tarif als weiterer Beleg ins Kontingent. Ist der Beleg schon gelesen, wartet er oder wird er gerade gelesen, antwortet die Route mit `409 DocumentReadingNotFailed`, auch beim zweiten Aufruf. Einen von Hand erfassten Beleg lehnt sie mit `409 DocumentReadingManual` ab, einen mit festgeschriebenen Buchungen mit `409 DocumentReadingFinalized` und eine in bimetrics ausgestellte Rechnung mit `409 DocumentReadingIssued`. Idempotency-Key bei Wiederholung unverändert senden. Benötigt einen Schlüssel mit der Berechtigung `upload`.
Kontakt anlegen POST
Legt einen Kontakt ohne Bankverbindung und steuerliche Art an; beides lässt sich danach mit updateContact ergänzen. Gleiche normalisierte USt-IdNr., externalRef oder gleicher Name ohne Rechtsform ergeben `409 ContactDuplicate` mit existingId. Nur eine Namensdublette kann mit forceDuplicate bestätigt werden. Benötigt einen Schlüssel mit der Berechtigung `contacts:write`.