> For the complete documentation index, see [llms.txt](https://docs.solutioo.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.solutioo.de/differenzbesteuerung-entwicklerdokumentation/reference.md). # Entwicklerdokumentation > **App 0.28.1.2 · Entwicklungsvorschau · Stand 29.10.2026.** Öffentliche AL-Berechnung und Berichtsspalten; keine freigegebene Fremdbuchungs-, Import- oder Shopware-API. Produktivfreigabe und endgültige Auslieferungsprüfung stehen aus. ## 1. Erweiterungsmodell und unterstützter Umfang Die Kern-App referenziert ausschließlich Microsoft Application. Test- und Build-Werkzeuge sind keine Laufzeitabhängigkeiten. Es gibt noch keine Shopware-Bridge. ## 2. Entwicklungsumgebung, Abhängigkeiten und Versionen Verwenden Sie Microsoft AL mit Runtime 17.0 und Microsoft Application ab 28.0.0.0. Die Kern-App hat die ID `6ca3568c-f86e-4868-b5db-bed61a866e62`; Name `solutioo Margin Tax`, Publisher `solutioo`, beschriebene Version `0.28.1.2`. Tragen Sie diese Abhängigkeit in Ihre Erweiterung ein. Das installierte Objektprofil muss zu Ihrem Symbolpaket passen. [Kompatibilität](#id-8.-kompatibilitat-anderungen-und-abkundigungen). ## 3. Authentifizierung, Berechtigungen und Datenkontext Die Berechnungs-Codeunit läuft innerhalb einer AL-Sitzung. Sie benötigt keinen eigenen OAuth-Zugang und liest oder schreibt keine Geschäftsdaten. Für ihren Aufruf ist Ausführungsrecht auf `Margin Tax Calculation SOU` erforderlich, enthalten in `MARGIN TAX USER SOU`. Tabellenzugriff für Auswertungen benötigt gesonderte passende Leserechte und bleibt mandantengebunden. Produktivrollen enthalten keinen Test-API-Zugang. Die geschlossenen steuerlichen Enums sind nicht beliebig durch Fremdwerte erweiterbar. ## 4. Referenz der Events, APIs und Erweiterungspunkte ### Öffentliche AL-Berechnung Codeunit `Margin Tax Calculation SOU`: * `Calculate(PurchasePrice, SalesPrice, VATRate, Precision, var GrossMargin, var TaxableBase, var VATAmount)`: reine Rechnung einer einzelnen gewöhnlichen Lieferung mit Nullbegrenzung der Steuer. Keine Buchung und keine rechtliche Zulässigkeitsprüfung. * `CalculateAggregate(Purchases, Sales, VATRate, Precision, var TaxableBase, var VATAmount)`: reine Rechnung aus nichtnegativen Summen. Der interne Abrechnungsdienst verarbeitet signierte Quellbewegungen, Jahreskumulierung, Vorperioden und Revisionsbuchungen; diese reine Funktion bucht nichts. * `InvoiceNotice(Classification): Text[100]`: gesetzlicher deutscher Hinweis zur Warenklassifikation. Ausgeschlossene Waren führen zu Fehlern. Steuerliche Enums sind bewusst geschlossen: fremde Werte dürften andernfalls bestehende Zulässigkeitsprüfungen unbemerkt umgehen. Ein späterer fachlicher Ausbau muss jeden neuen Steuerfall explizit verarbeiten und testen. ### Daten für Auswertungen Die Erwerbs- und Steuerpostentabellen sind lesbar und revisionsorientiert append-only angelegt. Erweiterungen dürfen weder direkt neue Steuerposten erstellen noch vorhandene Nachweise verändern. Für eine zukünftige Bridge ist eine eigene, freizugebende Fassade mit reinen Produkt-/Verkaufskennzeichen vorgesehen. Einkaufspreise und Margen gehören nicht in Kundenschnittstellen. Die schreibenden Codeunits `Validation`, `Documents`, `Posting`, `Aggregate`, `Stock Mgt`, `Returns`, `Price Credits`, `Industry Mgt`, `Corrections`, `Payments`, `Evidence`, `VAT Statement`, `Guards` und `Export` sind intern. Die separate Test-App erhält ausschließlich für Tests Zugriff über `internalsVisibleTo`. `Margin Tax Movement SOU` enthält die tatsächlichen Gesamtverfahrensquellen. `Margin Tax Settlement SOU` enthält kumulierte Jahressummen, gebuchte Anpassungen, Revision und den letzten einbezogenen Quellposten. Für einen historischen Nachweis immer Jahr, MwSt.-Datum bis Periodenende **und** Quellnummer bis `Last Movement No.` filtern; nur das Datum würde später rückdatierte Belege fälschlich einbeziehen. `Margin Tax Entry SOU` unterscheidet Verkauf, Gegenbuchung und Gesamtdifferenzabrechnung sowie das Verfahren. ### Reports Die Erweiterung von `Standard Sales - Invoice` liefert: * `MarginSchemeSOU`: differenzbesteuerte Position. * `MarginSchemeNoticeSOU`: gesetzlicher Hinweis. * `HideLineVATSOU`: Layout muss Steuersatz und Steuerbetrag dieser Position ausblenden. Diese Spalten enthalten keine Einkaufspreise, Bemessungsgrundlagen oder interne Margen. Ein fremdes Layout muss die Spalten aktiv verwenden. Die App liefert zusätzlich eigene RDLC-Rechnungs- und Gutschriftreports. Dieselben Kennzeichen-/Hinweisspalten ergänzen auch `Standard Sales - Credit Memo`. Die Gutschriftausgabe referenziert den ursprünglichen Gegenstand und die Ursprungsrechnung; Einkaufsbasis und interne Steuer werden nicht in deren Kundendataset aufgenommen. Die beiden eigenen Berichte und die erweiterten Standardberichte prüfen ab 0.21 vor Ausgabe den vollständigen Beleg gegen unveränderliche Verkaufs-/Erwerbsnachweise. Die gebuchten SOU-Kennzeichen können nicht über normale AL-Schreibaufrufe umgedeutet werden. Fehlende Margenzeilen und bereits inkonsistente Altkennzeichen führen zum Abbruch. Diese vorgeschaltete Prüfung ersetzt nicht die korrekte Nutzung der Dataset-Spalten im kundenspezifischen Layout. Einzelheiten und Grenzen: [Überwachung und Fehlerbehebung](https://docs.solutioo.de/differenzbesteuerung/troubleshooting). ### Separate Test-App Die privilegierte QA-Oberfläche gehört ausschließlich in die Sandbox und ist keine öffentliche Kundenschnittstelle. Kundenauslieferung und Produktivrollen dürfen die Test-App nicht enthalten. ### Steuerliche Bestandshistorie `Margin Tax Stock Entry SOU` ist ein lesbarer Nachweis für freigegebene Überleitungen und endgültige Verluste. Das Erwerbsverfahren und der Einkaufspreis am ursprünglichen Erwerb bleiben historische Werte. Das tatsächlich am Verkaufsdatum anzuwendende Verfahren und die gegebenenfalls verbleibende Einzelbasis werden intern aus der datierten Bestandshistorie ermittelt. Externe Erweiterungen dürfen diese Basis nicht allein aus dem Artikelkennzeichen oder dem ursprünglichen Erwerbsverfahren ableiten. `Margin Tax Movement SOU.Stock Entry No.` verknüpft Altbestands-/Verlustquellen mit ihrer Freigabe und Basisfortschreibung. `Margin Tax Stock Permit SOU` und die schreibenden Bestandsdienste sind interne Implementierungsdetails und keine öffentliche Import-/Buchungs-API. Es existiert noch kein allgemein freigegebener Fremdbestandsimport. `Margin Return Entry SOU` verknüpft tatsächliche Retourenartikelposten mit dem ursprünglichen Erwerb, dem Quellverkauf und der Gegenbuchung bzw. der Lieferantenrückgabe. `Margin Tax Entry SOU.Inbound Item Entry No.` bezeichnet den tatsächlich verbrauchten Original- oder Retourenzugang; `Return Item Entry No.` bezeichnet den tatsächlichen Rücknahmezugang. Die ursprüngliche Erwerbsnummer bleibt die steuerliche Identität. Die neue Retourentabelle allein ist keine freigegebene Import-API oder eine automatische Migration älterer physischer Retouren. `Margin Tax Movement SOU.Return Item Entry No.` verknüpft Einkaufssummenkorrekturen mit dem unveränderlichen Lieferantenretourennachweis. Die Entscheidung über den Korrekturzeitraum ist dokumentierter fachlicher Input. `Margin Return Permit SOU` ist ein unbestätigtes Implementierungsdetail, kein dauerhaft aktivierbarer Buchungsmodus. ### Preisgutschriften `Margin Price Credit SOU` speichert finanzielle Entgeltminderungen, Vorher-/Nachher-Werte, Reviewdaten und Standardkostenreferenz. `Margin Tax Entry SOU.Price Credit No.` und `Margin Tax Movement SOU.Price Credit No.` verknüpfen die Steuer-/Quellenkorrektur damit. Die Menge des Korrekturpostens ist null. Die erweiterten Postenarten unterscheiden Kunden- und Lieferantenkorrekturen von tatsächlichen Retouren. Die letzte in einer Bestandsüberleitung enthaltene Preisgutschrift wird als `Price Credit Cutoff No.` gespeichert. Die interne Erweiterung `FiscalPurchaseSOU` des Standard-Enums `Purchase Applies-to Document Type` bezeichnet ausschließlich die genaue ursprüngliche Einkaufszuordnung für den Standard-Artikelzuschlag. `Purch.-Post.OnPostItemChargeLineOnAfterPostItemCharge` liefert über `IncludeSender` die laufende Standard-Buchungsinstanz; deren `PostItemCharge` erzeugt den kostenbezogenen Wertposten in derselben Transaktion. Dieser interne Zuordnungstyp ist keine allgemeine Import- oder Fremd-API. Es gibt keinen direkten eigenen Standard-Wertposteninsert. ### Datierte Steuerkonfiguration `Margin VAT Rate SOU` enthält bestätigte Gültigkeitsanfänge und gesetzliche Nachweise. `Margin Tax Entry SOU.Tax Point Date` ist vom MwSt.-Meldezeitraum getrennt; `Posted VAT Bus. Group` und `Posted VAT Prod. Group` erhalten die ursprüngliche gebuchte Konfiguration für spätere Korrekturen. Verwendete Datensätze sind unveränderlich. Das interne Erstattungs- und Standardkorrekturmodul ist keine freigegebene Fremdbuchungs-API. Die zusätzlichen dauerhaft gespeicherten QA-Aktionen gehören ausschließlich zur separat installierten Test-App und prüfen erlaubte synthetische Firmen; temporäre Benutzerregistrierung prüft zusätzlich die vorhandene Standard-Benutzeradministratorberechtigung. ## 5. Vollständige Beispiele Das folgende vollständige Minimalprojekt verwendet ausschließlich die öffentliche Berechnung. Wählen Sie für eine eigene Erweiterung einen Ihnen zugeteilten Objektslot; `50100` ist hier eine Beispielnummer. Installieren Sie das passende Kernpaket und laden Sie seine Symbole. Das Beispiel benötigt Ausführungsrecht auf der eigenen und der Berechnungs-Codeunit. `app.json`: ```json { "id": "e63dbbdf-bb68-44b2-99ea-b4515ee454b1", "name": "Margin Tax Calculation Example", "publisher": "solutioo", "version": "1.0.0.0", "platform": "28.0.0.0", "application": "28.0.0.0", "runtime": "17.0", "target": "Cloud", "idRanges": [ { "from": 50100, "to": 50100 } ], "dependencies": [ { "id": "6ca3568c-f86e-4868-b5db-bed61a866e62", "name": "solutioo Margin Tax", "publisher": "solutioo", "version": "0.28.1.2" } ] } ``` `CalculationExample.Codeunit.al`: ```al namespace Solutioo.MarginTax.Example; using Solutioo.MarginTax; codeunit 50100 "Margin Calculation Example" { procedure CheckExample() var Calculation: Codeunit "Margin Tax Calculation SOU"; GrossMargin: Decimal; TaxableBase: Decimal; VATAmount: Decimal; begin Calculation.Calculate(100, 150, 19, 0.01, GrossMargin, TaxableBase, VATAmount); if (GrossMargin <> 50) or (TaxableBase <> 42.02) or (VATAmount <> 7.98) then Error('Unexpected margin calculation result.'); end; } ``` `CheckExample()` erwartet bei 100 EUR Einkauf, 150 EUR Verkauf, 19 Prozent und Präzision 0,01: 50 EUR Bruttodifferenz, 42,02 EUR Bemessungsgrundlage und 7,98 EUR Steuer. Eine Abweichung löst einen Fehler aus. Das Beispiel erzeugt weder einen geprüften Erwerb noch eine Buchung. Die aktuelle öffentliche Berechnungsimplementierung ist unverändert; die nativen Berechnungsfälle gehören zur bestandenen Auswahl des [Prüfstands](https://docs.solutioo.de/differenzbesteuerung/updates). ## 6. Transaktionen, Wiederholungen und Fehlerverhalten `Calculate` und `CalculateAggregate` akzeptieren ausschließlich nichtnegative Eingangspreise/-summen, einen Satz größer null bis 100 sowie eine positive Rundungspräzision. Fehler werden mit AL `Error` ausgelöst. Die Ausgaben sind `var Decimal`; überschreiben Sie keine bereits gebuchten Ergebnisse damit. Die Methoden schreiben keine Daten und sind bei identischen Eingaben deterministisch wiederholbar. Es gibt keine Idempotenz-ID oder Hintergrundverarbeitung. `Calculate` rundet zuerst `SalesPrice - PurchasePrice`, begrenzt die Steuer bei null/negativer Marge auf null und berechnet sonst `Round(GrossMargin * VATRate / (100 + VATRate), Precision)`; die Basis ist Bruttomarge minus Steuer. `CalculateAggregate` ruft diese reine Rechnung auf. Sie implementiert allein weder signierte Korrekturquellen noch kumulierte Jahresabrechnung oder deren Buchung. Exakte Signaturen aller drei öffentlichen Methoden: ```al procedure Calculate(PurchasePrice: Decimal; SalesPrice: Decimal; VATRate: Decimal; Precision: Decimal; var GrossMargin: Decimal; var TaxableBase: Decimal; var VATAmount: Decimal) procedure CalculateAggregate(Purchases: Decimal; Sales: Decimal; VATRate: Decimal; Precision: Decimal; var TaxableBase: Decimal; var VATAmount: Decimal) procedure InvoiceNotice(Classification: Enum "Margin Tax Class SOU"): Text[100] ``` `InvoiceNotice` liefert für `UsedGoods`, `Art` und `CollectorsAntiques` den fest hinterlegten deutschen Hinweis; alle übrigen Werte führen zum Fehler. Die Funktion führt keine Erwerbsberechtigungsprüfung aus. Öffentliche Integration-/Business-Events oder Webhooks sind in diesem Stand nicht ausgewiesen; Standard-Eventsubscriber der App sind keine eigenen veröffentlichten Events. ## 7. Testen und Debuggen Die ausgewählten aktuellen Prüfungen wurden auf BC 28.5 in einer getrennten Dev-Sandbox mit synthetischen Daten ausgeführt. Frühere Nachweise gelten nur für ihre damaligen Pakete und Umgebungen. Das Manifest deaktiviert Debugging, Source-Download und Source im Symbolpaket. Verwenden Sie einen kontrollierten Entwicklungsbuild aus den Quellen, wenn Sie intern debuggen müssen; ein kundenseitig freigegebenes Paket wird dadurch nicht ersetzt. Die Test-App ist separat, nutzt Funktionsrollback und privilegierte Sandboxaktionen. Ihre Berechtigungen sind keine normale Benutzerrolle. Führen Sie normale Rollenprüfungen getrennt aus und dokumentieren Sie Version, Commit, tatsächliches Paket, Rolle, Umgebung und Ergebnis. Keine echte steuerliche Meldung oder externen Bestellungen aus synthetischen Tests auslösen. ## 8. Kompatibilität, Änderungen und Abkündigungen Es besteht noch keine produktiv freigegebene Marketplace-Baseline. Ändern Sie Identitäten und Felder nicht blind zwischen Entwicklungs- und Marketplace-Profil. Beurteilen Sie öffentliche Signaturen, Schema und Reportspalten bei jedem Update gegen das tatsächlich ausgelieferte Paket. Historische Einführung einzelner Methoden ist hier nicht zugesagt; maßgeblich sind [Versionsstand](https://docs.solutioo.de/differenzbesteuerung/updates) und Quellvergleich. Interne APIs begründen keine Kompatibilitätszusage. ## 9. Technische FAQ und Support **Kann eine Erweiterung mit `CalculateAggregate` eine Abrechnung buchen?** Nein. Die Methode ist eine reine Berechnung ohne Jahres-/Quellkontext. Die schreibenden Dienste sind intern. **Kann ich Margentabellen direkt importieren oder ändern?** Es gibt keine freigegebene Fremdbuchungs-/Migrations-API. Direkte Nachweisänderungen sind nicht unterstützt; die internen Permits sind kein öffentlicher Freischaltmodus. **Was muss ein eigenes Layout beachten?** Es muss `HideLineVATSOU` und den klassifikationsabhängigen Hinweis umsetzen, die übrigen Standardpflichtangaben erhalten und eine vollständige Belegprüfung durchlaufen. Die Dataset-Erweiterung allein ändert das Layout nicht. Senden Sie Fehler mit App-/BC-Version, eigener Erweiterungsversion, kleinem Reproduktionsprojekt, tatsächlicher Rolle und bereinigter Fehlermeldung über den vereinbarten [Supportweg](https://docs.solutioo.de/differenzbesteuerung/support). Einkaufspreise/Margen nicht öffentlich in Issues oder Screenshots einstellen. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.solutioo.de/differenzbesteuerung-entwicklerdokumentation/reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.