# Umrechnung zum Monatskurs prüfen (https://developer.bimetrics.de/reference/documents/preview-document-monthly-rate)

`GET https://app.bimetrics.de/api/document/{id}/monthly-rate`

operationId: `previewDocumentMonthlyRate` · Berechtigung (Scope): `read` · Bereich: Belege

Sagt für einen Beleg in Fremdwährung mit „Euro-Betrag fehlt“, ob `euroAtMonthlyRate` in `PATCH /api/document/{id}` ihn jetzt zum Monatskurs des BMF umrechnen kann, und ändert nichts. `ready` nennt die Kurse je Monat und die Euro-Summe danach. `waiting` heißt, der Kurs gilt ab `availableFrom`: Das BMF gibt ihn am ersten Arbeitstag des Folgemonats bekannt. `late`: Der Kurs ist überfällig. `noRate`: Für die Währung gibt es keinen Monatskurs, dann den Euro-Betrag mit `euroTotalAmount` eintragen. `notEligible` mit `reason`, etwa `settledPayment` (die Zuordnung hat schon Skonto, Mahnkosten oder eine Kursdifferenz gebucht). Ist eine Bankzahlung ohne solchen Ausgleich zugeordnet, rechnet `euroAtMonthlyRate` trotzdem um; den Rest zur Zahlung bucht danach `POST /api/match/{id}/exchange-difference` als Kursdifferenz. `askEuroTax`: Bei deutscher Umsatzsteuer auf einem Eingangsbeleg erst fragen, ob er die Steuer in Euro ausweist; wenn ja, `euroTaxAmounts` statt `euroAtMonthlyRate`. `exported` heißt, die Buchungen sind schon an DATEV gegangen; beim Umrechnen storniert bimetrics dann wie in der App und bucht neu, als Nachtrag (`addendaMonths`; ein API-Schlüssel braucht dafür `documents:correct`).

Benötigt einen Schlüssel mit der Berechtigung `read`.

### Authentifizierung

`Authorization: Bearer bm_…` (alternativ `X-API-KEY: bm_…`, nie beide zugleich).

### Parameter

| Name | Ort | Pflicht | Typ | Beschreibung |
| --- | --- | --- | --- | --- |
| `id` | path | ja | string (uuid) | ID des Belegs in dieser Firma (UUID). |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/document/{id}/monthly-rate" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY"
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: DocumentMonthlyRatePreview |
| 400 | Ungültige Anfrage, z. B. ein Parameter mit ungültigem Wert wie eine ID, die keine UUID ist; korrigieren statt wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |
| 401 | Kein gültiger Schlüssel: fehlt (`Unauthorized`), ist unbekannt, abgelaufen oder widerrufen oder wurde nicht in genau einem Header gesendet (`InvalidAPIKey`). Schlüssel prüfen, nicht wiederholen. Auch eine ID, die zu einer anderen Firma gehört, ergibt `401 Unauthorized`. | `application/json`: Error |
| 403 | Dem Schlüssel fehlt die Berechtigung für diese Route (`APIKeyPermissionDenied`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error |
| 404 | Nicht gefunden (`NotFound`). | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error |
| 429 | Zu viele Anfragen; nach `Retry-After` Sekunden erneut senden. Mehr unter [Fehler](https://developer.bimetrics.de/errors). (Header: Retry-After) | `application/json`: Error |
| 500 | Serverfehler; die Anfrage später wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |

#### Felder der Antwort 200 (`DocumentMonthlyRatePreview`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `askEuroTax` | boolean | Eingangsbeleg mit deutscher Umsatzsteuer einer Firma mit Vorsteuerabzug: Erst fragen, ob der Beleg die Steuer in Euro ausweist. Ja: `euroTaxAmounts` in `PATCH /api/document/{id}` rechnet zum Kurs der Rechnung um; Nein: der Monatskurs. |
| `availableFrom` | string (date-time) | Bei `waiting` und `late`: Ab diesem Zeitpunkt gilt der zuletzt fehlende Monatskurs. |
| `bankRateHint` | boolean | `true`, wenn ein Euro-Betrag zum Kurs der Bank hier die Umsatzsteuer ändert: Eingangsbeleg mit deutscher Umsatzsteuer einer Firma mit Vorsteuerabzug oder Eingangsbeleg mit Reverse Charge einer Firma ohne Vorsteuerabzug. Der Kurs der Bank gilt dafür nur, wenn das Finanzamt ihn erlaubt hat (§ 16 Abs. 6 Satz 3 UStG), sonst der Monatskurs. Im zweiten Fall lehnt `POST /api/match/{id}/euro-amount` mit `reverseChargeWithoutInputTax` ab. |
| `billedInAdvance` | boolean | Eine Leistung endet nach dem Rechnungsmonat; dann gilt der Kurs des Rechnungsmonats. |
| `euroTotalAmount` | integer | Bei `ready`: Euro-Bruttosumme nach der Umrechnung in Cent, bei einer Gutschrift negativ. |
| `exported` | boolean | Die Buchungen des Belegs sind schon an DATEV gegangen. Beim Umrechnen storniert bimetrics dann wie in der App und bucht neu, als Nachtrag; ein API-Schlüssel braucht dafür `documents:correct`. Es zählen nur die Buchungen des Belegs selbst: Ist nur die zugeordnete Zahlung schon bei DATEV, steht hier `false`, ein API-Schlüssel braucht fürs Umrechnen aber trotzdem `documents:correct`. |
| `ownTaxHint` | boolean | Hochgeladene eigene Rechnung mit deutscher Umsatzsteuer: Es gilt der Monatskurs. Steht auf der Rechnung ein höherer Steuerbetrag in Euro, schuldet die Firma diesen (§ 14c Abs. 1 UStG); dann den Bruttobetrag zum Kurs der Rechnung mit `euroTotalAmount` eintragen. |
| `rates` | Array<MonthlyRate> | Bei `ready`: Kurse je Monat. |
| `reason` | string | Bei `notEligible`: `notForeignCurrency` (kein „Euro-Betrag fehlt“), `settledPayment` (die Zuordnung zur Bankzahlung hat schon Skonto, Mahnkosten oder eine Kursdifferenz gebucht), `cashBasisInvoice` (eigene Rechnung bei Ist-Versteuerung), `noDate` (kein Rechnungs- oder Leistungsdatum), `notConvertible` (eine Position würde 0 €). |
| `reference` | string: `monthly`, `ecb` | Woher `referenceRate` stammt: `monthly` (Monatskurs des ersten Eintrags in `rates`) oder, solange der fehlt, `ecb` (EZB-Kurs des Rechnungsdatums). |
| `referenceRate` | string (decimal) | Mit `askEuroTax`: der Kurs, mit dem `euroTaxAmounts` verglichen wird (1 Euro = `referenceRate` Einheiten, Dezimalzahl als String). Mehr als 3 % Abweichung brauchen `acceptRateDeviation`. |
| `state` | string: `ready`, `waiting`, `late`, `noRate`, `notEligible` | `ready`, `waiting`, `late`, `noRate` oder `notEligible`. |

Verschachtelte Schemas stehen vollständig in der OpenAPI-Beschreibung: https://app.bimetrics.de/api/openapi.json
