bimetricsEntwickler
Zuordnungen

Euro-Betrag aus der Zahlung übernehmen

Als Markdown ansehen

Benötigte Berechtigung:matching:write(Belege und Zahlungen zuordnen)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
post/api/match/{id}/euro-amount

Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.

Bucht den Beleg einer Zuordnung, der in einer Fremdwährung ist, mit dem Euro-Betrag seiner Zahlungen, wie „Euro-Betrag übernehmen“ in der App. Rufe das erst auf, wenn der Nutzer die Werte aus previewMatchEuroAmount bestätigt hat und die Zahlungen den ganzen Beleg decken, keine Teilzahlung. bimetrics rechnet jede Position anteilig auf die Summe der Zahlungen um, Steuersätze, Kategorien, Belegwährung und Originalbetrag bleiben; die Zuordnung bleibt bestehen, ihr offener Betrag ist danach null, und euroAmountSource steht auf payment. Der Bankbetrag folgt dem Kurs der Bank; für die deutsche Umsatzsteuer gilt grundsätzlich der Monatskurs des Bundesfinanzministeriums, das prüft die Steuerberatung. expectedVersions kommt unverändert aus previewMatchEuroAmount. Eine Wiederholung mit gleichem Schlüssel bucht nichts erneut. Nicht möglich, wenn die Zuordnung nicht passt (400 EuroAmountNotEligible, der Grund steht in detail) und wenn Buchungen schon an DATEV exportiert sind (409 FinalizedBookingsLocked); andere festgeschriebene Buchungen bleiben stehen und werden storniert und neu gebucht.

Benötigt einen Schlüssel mit der Berechtigung matching:write.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.

Pfadparameter

id*string

ID des Objekts in dieser Firma (UUID).

Formatuuid

Header-Parameter

Idempotency-Key*string

Stabiler Schlüssel für genau diese Änderung: 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Bei Wiederholungen denselben Schlüssel und unveränderten Inhalt senden; das Ergebnis wird nicht nochmals erzeugt.

Muster^[!-~]+$
Länge1 <= length <= 128

Request-Body

The versions of the preview

application/json
  1. body

Übernimmt den Euro-Betrag genau so, wie die Vorschau ihn zeigt.

expectedVersions?|

Vollständige Versionsmap aus previewMatchEuroAmount, unverändert.

Antworten

Erfolg.

application/json
  1. response

Der Beleg mit den Euro-Beträgen; die Zuordnung bleibt.

document?|

Der Beleg nach der Übernahme.

replayed?boolean

True bei sicherer Wiederholung eines bereits erfolgreichen Aufrufs.

reversedFinalizedMonths?array<string>

Monate (YYYY-MM), in denen bimetrics festgeschriebene Buchungen storniert und mit geändertem Datum, Leistungszeitraum, Konto, Steuerkennzeichen oder Betrag neu gebucht hat. Ändert sich nur der Buchungstext oder die Zuordnung, fehlt der Monat. Hast du die Umsatzsteuer-Voranmeldung für einen dieser Monate oder, bei geändertem Datum, für den neuen Monat schon abgegeben, musst du sie womöglich berichtigen. Fehlt, wenn nichts storniert wurde, und bei einer Wiederholung mit demselben Idempotency-Key.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/match/497f6eca-6276-4993-bfeb-53cbbbba6f08/euro-amount" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
Beispielantwort
{  "document": {    "bookings": [      {        "account": 4930,        "accountContra": 71007,        "accountingModel": "SKR03",        "amount": "43.89",        "bookingDate": {          "day": 27,          "month": 8,          "year": 2026        },        "bookingFlags": "v19%",        "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",        "createdAt": "2026-09-04T08:02:40Z",        "deletedAt": null,        "finalized": "2026-09-05T10:41:09Z",        "finalizedBy": "export",        "id": "f00b48c7-6eb3-4082-aba2-917944ac5f93",        "label": "Papierhaus Wendt KG, Kopierpapier A4 10 Pakete",        "performanceFrom": {          "day": 27,          "month": 8,          "year": 2026        },        "performanceTo": {          "day": 27,          "month": 8,          "year": 2026        },        "refBankTransactionId": null,        "refDocumentId": "a129ef0a-da5d-4204-804c-764d751bca95",        "refMatch": "d00419ed-ecab-4800-ad69-d482b73a6961",        "revertsAccountBookingId": null,        "updatedAt": "2026-09-05T10:41:09Z"      }    ],    "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",    "contentSource": "manual",    "createdAt": "2026-08-28T06:15:03Z",    "deletedAt": null,    "deliveryDate": null,    "documentContract": null,    "documentContractId": null,    "documentCurrency": "USD",    "documentSeries": null,    "documentSeriesId": null,    "dueDate": {      "day": 10,      "month": 9,      "year": 2026    },    "euroAmountSource": "payment",    "id": "a129ef0a-da5d-4204-804c-764d751bca95",    "importOrigin": "email",    "invoiceDate": {      "day": 27,      "month": 8,      "year": 2026    },    "invoiceNumber": "2026-5531",    "invoicePositions": [      {        "additionalInfo": {          "freeOfVat": false,          "reverseCharge": false        },        "category": "office_supplies",        "label": "Kopierpapier A4 10 Pakete",        "subPositions": null,        "total": 3951,        "vatPercentage": "19"      }    ],    "issuer": {      "address": "Bahnhofstraße 8, 24103 Kiel",      "customerNumber": 1007,      "iban": "DE02500105170137075030",      "name": "Papierhaus Wendt KG",      "taxId": "DE246813579"    },    "kind": "receipt",    "match": {      "amountOpen": 0,      "autoMatch": false,      "bankTransactions": [        {          "bankTransactionId": "78c4ff15-f2a0-4eae-945d-73a969adab4b",          "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",          "createdAt": "2026-09-04T08:02:37Z",          "id": "b06c1337-d724-4854-bba8-d52bc6355c8b",          "matchId": "d00419ed-ecab-4800-ad69-d482b73a6961",          "updatedAt": "2026-09-04T08:02:37Z"        }      ],      "category": "payment",      "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",      "createdAt": "2026-09-04T08:02:37Z",      "documents": [        {          "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",          "createdAt": "2026-09-04T08:02:37Z",          "documentId": "a129ef0a-da5d-4204-804c-764d751bca95",          "id": "e1331e65-c539-4c84-9271-66cc20f52910",          "matchId": "d00419ed-ecab-4800-ad69-d482b73a6961",          "updatedAt": "2026-09-04T08:02:37Z"        }      ],      "id": "d00419ed-ecab-4800-ad69-d482b73a6961",      "matchingRule": {        "active": true,        "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",        "createdAt": "2026-09-04T08:02:41Z",        "id": "5e0f6a4b-8d2c-4f7e-9b1a-3c6d2e8f4a71",        "updatedAt": "2026-09-04T08:02:41Z"      },      "matchingRuleId": "5e0f6a4b-8d2c-4f7e-9b1a-3c6d2e8f4a71",      "updatedAt": "2026-09-04T08:02:37Z"    },    "originalTotalAmount": 4389,    "paymentTerms": "Der Betrag wird per SEPA-Lastschrift eingezogen.",    "performancePeriodFrom": null,    "performancePeriodTo": null,    "recipient": {      "address": "Mühlenkamp 31, 22303 Hamburg",      "customerNumber": null,      "iban": "",      "name": "Hansen & Kowalski Werbetechnik GmbH",      "taxId": "DE123456789"    },    "source": "",    "updatedAt": "2026-09-05T10:41:09Z",    "uploadDocument": {      "blob": {        "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5",        "createdAt": "2026-08-28T06:15:03Z",        "id": "138b7a6f-7e79-4040-bc64-3638e95d9682",        "length": 48213,        "mime": "application/pdf",        "originalFilename": "Rechnung_2026-5531.pdf",        "sha256": "a5a23fdf5e666babc92d877ccf80202609c25ae54b48095f0eaa02289012ca54",        "updatedAt": "2026-08-28T06:15:03Z"      },      "blobId": "138b7a6f-7e79-4040-bc64-3638e95d9682",      "creatorUserCompanyId": "53cd10a9-c864-4dc3-a777-9860d59efe6c",      "ocrFinishedAt": "2026-08-28T06:15:19Z",      "ocrStartedAt": "2026-08-28T06:15:04Z",      "ocrStatus": "success",      "pageCount": 2,      "pagesRead": 2    },    "uploadDocumentId": "08f65ded-eef9-4cdf-8954-ace8add6eb53",    "version": ""  },  "replayed": false}

Aufheben einer Zuordnung prüfen GET

Liefert die aktuellen Versionsbedingungen und IDs der Serienbelege, die beim Aufheben gelöscht würden. Verändert nichts. Prüfe die betroffenen Belege vor DELETE und sende expectedVersions unverändert. Benötigt einen Schlüssel mit der Berechtigung `read`.

Euro-Betrag aus der Zahlung prüfen GET

Sagt, ob sich für den Beleg einer Zuordnung, der in einer Fremdwährung ist und dessen Euro-Betrag fehlt (`documentCurrency` ohne `euroAmountSource`), der Euro-Betrag aus der Zahlung übernehmen lässt, und liefert, was der Nutzer vorher bestätigt: Belegwährung, Betrag vom Beleg, Euro-Betrag der Zahlungen und jede Position vorher und nachher. Nötig sind genau ein Beleg und mindestens ein gebuchter Euro-Umsatz, kein Skonto an der Zuordnung und keine erfassten Zahlungen am Beleg. Passt die Zuordnung nicht, antwortet die API mit `eligible: false`, `refusal` nennt den Code und `refusalReason` den Grund. Verändert nichts. Benötigt einen Schlüssel mit der Berechtigung `read`.