International — API und MCP
Überblick
Dieser Bereich stellt 21 Operationen bereit. Jede davon ist zugleich ein MCP-Werkzeug.
Der Bereich hängt am Modul-Schalter module.international. Ist das Modul aus, antworten diese Operationen mit 404.
Operationen
| Methode | Pfad | Zweck | Recht | Parameter |
|---|---|---|---|---|
GET | /api/v1/international/country-tax-rates | Liste der CountryTaxRate | international.taxrate.view | page, country, category, active, order[countryCode], order[rate] |
POST | /api/v1/international/country-tax-rates | Bestimmungsland-Steuersatz anlegen — Payload {countryCode, category, rate, validFrom?, validTo?}. countryCode muss ein EU-Mitgliedstaat sein — für Drittländer gibt es keinen Bestimmungslandsatz, dort ist die Lieferung steuerfrei. Land und Kategorie zusammen sind eindeutig; ein zweiter Satz für dieselbe Kombination braucht ein abgegrenztes Gültigkeitsfenster. | international.taxrate.manage | + Rumpf |
GET | /api/v1/international/country-tax-rates/{ulid} | Eine CountryTaxRate lesen | international.taxrate.view | ulid |
PATCH | /api/v1/international/country-tax-rates/{ulid} | Bestimmungsland-Steuersatz ändern — Satz, Gültigkeitsfenster und Aktiv-Kennzeichen. Land und Kategorie sind unveränderlich — ein umgehängter Satz träfe rückwirkend Belege, die mit ihm nichts zu tun haben. | international.taxrate.manage | ulid, + Rumpf |
GET | /api/v1/international/ec-sales-reports | Liste der EcSalesReport | international.ecsales.view | page, year, status, periodType, overdue, order[periodYear], order[periodNumber], order[dueDate] |
POST | /api/v1/international/ec-sales-reports | Zusammenfassende Meldung erzeugen — Payload {year, periodType, periodNumber} — periodType ist quarter (Regelfall, periodNumber 1–4) oder month (Monatsmelder ab 50.000 EUR i. g. Lieferungen im Quartal, periodNumber 1–12). Summiert das Meldebuch des Zeitraums je Erwerber (USt-IdNr.) und Meldeart und FRIERT das Ergebnis ein. Ein bestehender Entwurf wird neu berechnet; eine freigegebene Meldung wird mit 422 abgelehnt. | international.ecsales.manage | + Rumpf |
GET | /api/v1/international/ec-sales-reports/{ulid} | Eine EcSalesReport lesen | international.ecsales.view | ulid |
POST | /api/v1/international/ec-sales-reports/{ulid}/confirm | Zusammenfassende Meldung freigeben (Steuerberater-Gate) — Payload {confirmationNote?}. Erklärt die Zahlen für richtig; ab hier ist die Meldung unveränderlich und herunterladbar. Eine Meldung OHNE Zeilen lässt sich freigeben — das ist die Nullmeldung. Zurückgewiesen wird nur eine Meldung, die nie berechnet wurde. | international.ecsales.confirm | ulid, + Rumpf |
GET | /api/v1/international/ec-sales-reports/{ulid}/file | Zusammenfassende Meldung als CSV herunterladen — Semikolon-getrennt, deutsche Dezimalschreibweise, CRLF (Länderkennzeichen, USt-IdNr., Kennzeichen, Betrag, Meldezeitraum). Kennzeichen: leer = innergemeinschaftliche Lieferung, 1 = sonstige Leistung. Nur für freigegebene Meldungen; ein Entwurf antwortet mit 422. CHECKPOINT: nach Spezifikation gebaut, nicht gegen das amtliche Prüfprogramm des BZSt gelaufen; Dreiecksgeschäfte (Kennzeichen 2) sind nicht abgebildet. | international.ecsales.manage | ulid |
GET | /api/v1/international/exchange-rates | Liste der ExchangeRate | international.rate.view | page, currency, from, to, source, order[rateDate] |
POST | /api/v1/international/exchange-rates | Kurs von Hand setzen — Payload {currency, rateDate, rate}. rate ist die Zahl der FREMDWÄHRUNGSEINHEITEN je 1 EUR (EZB-Konvention: 1 EUR = 1,0850 USD → "1.0850"). Ein bereits vorhandener Kurs desselben Tages wird überschrieben und auf manual gesetzt — der EZB-Import lässt handgepflegte Kurse danach in Ruhe. | international.rate.manage | + Rumpf |
POST | /api/v1/international/exchange-rates/import | EZB-Tagesreferenzkurse importieren — Holt den Tages-Feed der Europäischen Zentralbank und schreibt ihn ins Kursbuch. Idempotent: ein zweiter Aufruf am selben Tag ändert nichts. Handgepflegte Kurse (source=manual) bleiben unangetastet und werden in skipped gezählt. Ohne Netz antwortet die Operation mit 502 und das Kursbuch bleibt, wie es war. | international.rate.manage | + Rumpf |
GET | /api/v1/international/oss-reports | Liste der OssReport | international.oss.view | page, year, status, kind, overdue, order[periodYear], order[periodQuarter], order[dueDate] |
POST | /api/v1/international/oss-reports | OSS-Quartalsmeldung erzeugen — Payload {year, quarter} (Quartal 1–4). Summiert das Meldebuch des Zeitraums je Bestimmungsland und Steuersatz und FRIERT das Ergebnis ein — der spätere Export liest nur noch diesen Schnappschuss, damit eine nachträglich festgeschriebene Rechnung eine bereits abgegebene Meldung nicht stillschweigend verändert. Ein bestehender Entwurf desselben Quartals wird neu berechnet; eine bereits freigegebene Meldung wird mit 422 abgelehnt (Korrekturen laufen über das BZSt). | international.oss.manage | + Rumpf |
POST | /api/v1/international/oss-reports/corrections | OSS-Berichtigung eines früheren Zeitraums erzeugen — Payload {year, quarter, correctsYear, correctsQuarter} — year/quarter ist der MELDEzeitraum (in dem berichtigt wird), correctsYear/correctsQuarter der berichtigte Zeitraum (§ 18j Abs. 5 UStG). Die Berichtigung trägt ausschliesslich die Meldebuch-Zeilen des alten Zeitraums, die in keiner Meldung stehen — typischerweise eine Storno- oder Nachtragsrechnung. Das abgegebene Quartal wird NICHT neu gerechnet und nicht verändert. Der berichtigte Zeitraum muss vor dem Meldezeitraum liegen und bereits freigegeben sein, sonst 422. | international.oss.correct | + Rumpf |
GET | /api/v1/international/oss-reports/{ulid} | Eine OssReport lesen | international.oss.view | ulid |
POST | /api/v1/international/oss-reports/{ulid}/confirm | OSS-Meldung freigeben (Steuerberater-Gate) — Payload {confirmationNote?}. Erklärt die Zahlen für richtig; ab hier ist die Meldung unveränderlich und herunterladbar. Name und Zeitpunkt der Freigabe stehen danach am Datensatz. Eine Meldung OHNE Zeilen lässt sich freigeben — das ist die Nullmeldung, und die ist fristgebunden Pflicht (§ 18j UStG). Zurückgewiesen wird nur eine Meldung, die nie berechnet wurde. | international.oss.confirm | ulid, + Rumpf |
GET | /api/v1/international/oss-reports/{ulid}/file | OSS-Meldung als CSV herunterladen — Semikolon-getrennt, deutsche Dezimalschreibweise, CRLF — der Aufbau der BZSt-Importmaske (Land, Satzart, Steuersatz, Bemessungsgrundlage, Steuer, Meldezeitraum, Bezugszeitraum). Der Bezugszeitraum ist bei einer Berichtigung der berichtigte Zeitraum und sonst leer. Eine Nullmeldung besteht aus der Kopfzeile ohne Meldezeile. Nur für freigegebene Meldungen; ein Entwurf antwortet mit 422. CHECKPOINT: die Datei ist nach Spezifikation gebaut, aber nicht gegen das amtliche Prüfprogramm des BZSt gelaufen. | international.oss.manage | ulid |
GET | /api/v1/international/oss-threshold | Stand der EU-Lieferschwelle — Summiert die festgeschriebenen Rechnungen an PRIVATkunden in anderen Mitgliedstaaten des Kalenderjahres (netto, in EUR umgerechnet mit dem am Beleg eingefrorenen Kurs) und vergleicht sie mit der Schwelle. Ehrliche Grenze: gezählt wird die HEUTIGE Kundenadresse — für eine Warnschwelle richtig genug, für die Meldung selbst gilt das eingefrorene Meldebuch. | international.oss.view | year |
GET | /api/v1/international/vat-id-checks | Liste der VatIdCheck | international.vatid.check | page, vatId, partnerId, result, order[checkedAt] |
POST | /api/v1/international/vat-id-checks | USt-IdNr. prüfen — Payload {vatId, partnerId?, refresh?}. Ohne refresh gilt eine bereits bestätigte Nummer für die eingestellte Frist (international.vat_id.recheck_days, Vorgabe 90 Tage) als bestätigt und es wird KEINE neue Abfrage gestellt — nur so übersteht die Steuerermittlung eine Rechnung mit zwölf Positionen ohne zwölf Netzabfragen. Ein nicht erreichbarer Dienst liefert result=unavailable (HTTP 201, kein Fehler): eine Netzstörung entwertet keine gültige Nummer und winkt keine ungültige durch. | international.vatid.check | + Rumpf |
Zweckangaben, die nicht dem Standardmuster folgen, stammen unverändert aus der Schnittstellen-Beschreibung im Code.