jasveerai88/gst-hst-tracker

gst-hst-tracker — Agenten-Fähigkeit

Zweck

Kanadische Freelancer und Einzelunternehmer verfolgen GST/HST in Tabellenkalkulationen und entdecken die 30.000-€-Kleinlieferanten-Schwelle der CRA erst, nachdem sie überschritten wurde. Dieses Werkzeug liest ein datiertes Transaktionsjournal und erzeugt (a) pro Kalendervierteljahr erhobene GST/HST, Vorsteuer (ITCs) und geschuldete Netto-Steuer mit einem T2125-ähnlichen Einnahmen-/Ausgaben-Vorbereitungsabschnitt, (b) den Schwellentest: rollierende letzte 4 Kalendervierteljahre des steuerpflichtigen Einkommens gegen die 30.000-€-Grenze, mit Spielraum oder einem Überschreitungsalarm, und (c) eine provinzbasierte Ansicht desselben Journals: Steuersystem, erhobene Beträge, Vorsteuer und Netto pro Provinz, wobei die provinzielle Komponente nur so weit gezeigt wird, wie die Daten es unterstützen (aufgezeichnete QST als Memozahlen zuzüglich einer Schätzung für nicht erfasste QC-Verkäufe; PST/RST als Satz×Verkaufs-Expositionsschätzungen). Reine Python-Standardbibliothek; nur lokal; liest eine Journaldatei, schreibt nichts.

Der ehrliche Kern dieses Werkzeugs: Es ist eine Berechnungs- und Nachverfolgungshilfe, keine Steuerberatung und keine CRA-Einreichung. Jeder Bericht trägt diesen Haftungsausschluss, und alles, was Sie aus seiner Ausgabe schreiben, muss ihn ebenfalls tragen. Es berechnet niemals Strafen oder Zinsen.

Wann verwenden / nicht verwenden

Verwenden Sie es, wenn:

• Sie die GST/HST-Zahlen eines Quartals aus einem Transaktionsjournal aufbereiten: erhobene Beträge, Vorsteuer, geschuldeter Netto-Betrag.
• Sie prüfen, wie nah ein Freelancer der 30.000-€-Registrierungsschwelle ist oder ob er sie überschritten hat.
• Sie Einnahmen- und Ausgabenkategorien in einer T2125-ähnlichen Vorbereitungsansicht für die Steuersaison organisieren.
• Ein Agent kanadische GST/HST-Zahlen benötigt, denen er in JSON vertrauen kann.

Verwenden Sie es NICHT, wenn:

• Der Benutzer Steuerberatung, eine Einreichung oder eine Entscheidung über seine Verpflichtungen benötigt – dieses Werkzeug kann keine geben. Verweisen Sie ihn an die CRA oder einen qualifizierten Buchhalter.
• Die Frage Strafen oder Zinsen betrifft – diese werden nie berechnet.
• Die Bücher Quebec-QST-Bücher sind: QST ist hier nur als Memo (siehe Grenzen). BC PST / SK PST / MB RST erscheinen nur als Expositionsschätzungen in der provinces-Ansicht – niemals als geschuldete Steuern oder Gutschriften.
• Das Journal veraltet ist: das Schwellenfenster ist an die letzte Transaktion gebunden, daher ergibt ein veraltetes Journal ein veraltetes Fenster. Sagen Sie dies, wenn die Daten alt aussehen.

Installation

pipx install git+https://github.com/jasveerai88/gst-hst-tracker
# oder: pip install git+https://github.com/jasveerai88/gst-hst-tracker

(Nicht auf PyPI – die git+-Form ist die Installation.) Aus einem Quellcode-Checkout ist python3 src/gst_hst_tracker.py ... gleichwertig.

Befehle

# Quartalsbericht (JSON- oder CSV-Eingabe; Exit 0 bei Erfolg)
gst-hst-tracker report LEDGER.json
gst-hst-tracker report LEDGER.csv --json

# Nur ein Kalendervierteljahr oder ein Jahr
gst-hst-tracker report LEDGER.json --period 2026-Q1
gst-hst-tracker report LEDGER.json --period 2026

# Der Kleinlieferanten-Alarm (Exit 1 bei Überschreitung, sonst 0)
gst-hst-tracker threshold LEDGER.json [--limit 30000]

# Die provinzielle Ansicht (Exit 0 bei Erfolg)
gst-hst-tracker provinces LEDGER.json
gst-hst-tracker provinces LEDGER.json --period 2026-Q1 --json

# Auch INR-Äquivalente anzeigen (Wechselkurs pro 1 CAD)
gst-hst-tracker report LEDGER.json --cad-to-inr 67.97

# Provinzsatz überschreiben, wenn er sich ändert
gst-hst-tracker report LEDGER.json --rate NS=15

Eingabezeilen (JSON-Liste, {"transactions": [...]}-Objekt oder CSV mit denselben Kopfzeilen): date (YYYY-MM-DD, erforderlich), kind (income|expense, erforderlich), description (erforderlich), amount (Vorsteuer-CAD, erforderlich, ≥ 0), province (zweistelliger Code, erforderlich); optional tax (berechnete/gezahlte GST/HST – weglassen, um aus dem Provinzsatz zu berechnen; 0 bedeutet nullsteuerpflichtig und wird respektiert), qst (nur QC-Zeilen; separat verfolgt, niemals im Netto), category (nur Ausgaben; T2125-ähnliche Gruppierung).

Das Modell (bei Ergebnisberichterstattung angeben)

• Geschuldete Netto-Steuer pro Kalendervierteljahr = GST/HST auf Einnahmen erhoben − Vorsteuer (GST/HST auf Ausgaben gezahlt). Negatives Netto = Vorsteuer übersteigt Erhebungen: eine Erstattungsposition, kein Bargeldbestand.
• Schwelle: steuerpflichtige Lieferungen (nur Einnahmenzeilen) über die letzten 4 Kalendervierteljahre, die mit dem Quartal der letzten Transaktion enden. Der CRA-Test ist übersteigt 30.000 € – genau 30.000 € ist immer noch ein Kleinlieferant (status: "at", Exit 0).
• Satz-Standards ab Nov. 2026: GST 5 % (AB BC MB NT NU SK YT), HST 13 % ON, HST 15 % NB/NL/PE, HST 14 % NS (gesenkt von 15 % am 01.04.2025), QC = GST 5 % nur Bundesanteil.
• QST (9,975 %) ist eine separate Steuer von Revenu Québec: bereitgestellte qst-Beträge erscheinen nur als Memo-Summen und gehen niemals in den Netto ein.
• Provinzielle Ansicht (provinces): dieselbe Bundesmathematik, gruppiert nach der Provinz der Zeile. Kodierte provinzielle Steuern, gekennzeichnet mit „Kodierte Sätze, geprüft Nov. 2026 – gegen CRA/provinzielle Quellen vor der Einreichung verifizieren”: QST 9,975 % (QC), PST 7 % (BC), PST 6 % (SK), RST 7 % (MB); HST-Provinzen haben keine separate provinzielle Komponente. QC zeigt aufgezeichnete QST-Summen zuzüglich einer Schätzung für QC-Einnahmezeilen ohne aufgezeichnetes qst; BC/SK/MB zeigen nur eine Satz×Verkaufs-Expositionsschätzung und keine provinzielle Vorsteuer (PST/RST auf Eingaben sind in der Regel Kosten). Rundung: provinzielle Zahlen werden auf Cent gerundet und die Summe addiert diese gerundeten Zahlen, sodass sie immer mit den Provinzblöcken übereinstimmt.

JSON-Ausgabeschema (--json)

report: tool ("gst-hst-tracker"), version, command ("report"), file, currency ("CAD"), rates (pro Provinz rate_pct + Bezeichnung, gekennzeichnet as_of: "2026-11", plus die QST-Notiz), cad_to_inr (Wechselkurs oder null), period_filter (Zeichenkette oder null), periods, totals, disclaimer.

Jeder Zeitraum: period (z.B. "2026-Q1"), quarter ([2026, 1]), income_total, expense_total, gst_hst_collected, itcs, net_tax_owing, qst_collected, qst_paid, transactions, t2125 (gross_business_income, expenses_by_category, total_expenses). totals summiert dieselben Felder über die angezeigten Zeiträume. Mit --cad-to-inr erhalten Geldfelder *_inr-Geschwister.

threshold: die gemeinsamen Felder plus latest_transaction, window_end_quarter, quarters (vier {quarter, income}-Einträge, älteste zuerst), rolling_total, limit, headroom (0 bei Überschreitung), over_by (0 bei Nichtüberschreitung), crossed (bool), status ("under" | "at" | "crossed"), rule, disclaimer.

provinces: die gemeinsamen Felder plus provincial_rates (stamp, qst_rate_pct, taxes – pro Provinz federal-Bezeichnung und provincial_tax {name, rate_pct} oder null), rounding_rule, provinces, totals, disclaimer. Jeder Eintrag in provinces: province, tax_system (aus den effektiven Sätzen erstellt, z.B. "GST 5% + PST 7%"), income_total, expense_total, gst_hst_collected, itcs, net_tax_owing, transactions und provincial – null für reine GST- und HST-Provinzen; andernfalls {name, rate_pct, recorded_collected, recorded_paid, recorded_net} (Zahlen für QC, null für BC/SK/MB – für diese wird nichts aufgezeichnet), estimate_base, estimated_on_sales, note. totals fügt qst_recorded_collected / qst_recorded_paid / qst_recorded_net und provincial_estimated_on_sales hinzu.

Bei Fehlern ist stdout ein einzelnes Objekt: {"error": "<Nachricht>"} (Validierungsfehler nennen die Zeile: "row 2: ...") mit Exit-Code 2 – einschließlich argparse-Nutzungsfehlern im --json-Modus. Niemals Klartext, niemals ein Traceback.

Exit-Codes

• report: 0 – Bericht berechnet. 2 – Fehler.
• provinces: 0 – Ansicht berechnet. 2 – Fehler. (Kein Exit-1-Zustand: die Ansicht ist informativ; der Alarm lebt in threshold.)
• threshold: 0 – rollierender Gesamtbetrag liegt unter oder genau bei der Grenze: noch ein Kleinlieferant anhand dieser Zahlen. 1 – SCHWELLE ÜBERSCHRITTEN: der rollierende Gesamtbetrag übersteigt die Grenze und eine GST/HST-Registrierung ist erforderlich. Dies ist ein Befund, kein Fehler: heben Sie ihn deutlich hervor. 2 – Fehler: keine Zahlen wurden erzeugt; zitieren Sie keine.
• Fehler in beiden Befehlen beenden mit 2 und einer sauberen Nachricht (oder dem {"error": ...}-Objekt im --json-Modus).

Grenzen & Ehrlichkeitsregeln, die der Agent respektieren muss

• Keine Steuerberatung, keine Einreichung. Präsentieren Sie die Ausgabe dieses Werkzeugs niemals als Beratung oder als eingereichte Steuererklärung. Der Haftungsausschluss in jeder Ausgabe ist tragend: halten Sie ihn an jeder Zusammenfassung, die Sie schreiben, fest.
• Die Sätze sind Standardwerte ab Nov. 2026, keine lebenden Fakten. Zitieren Sie sie als „die Nov-2026-Standardwerte des Werkzeugs” und weisen Sie darauf hin, dass sie überschreibbar sind. Nova Scotia ist 14 % (es war 15 % bis 31.03.2025) – wenn die Zahlen eines Benutzers mit 15 % für NS berechnet wurden, ist dies erwähnenswert, nicht stillschweigend zu akzeptieren.
• Genau bei 30.000 € ist NICHT überschritten. Der CRA-Test ist „übersteigt 30.000 €”. Wenn status "at" ist, melden Sie „noch ein Kleinlieferant, null Spielraum” – niemals „muss sich registrieren”.
• Exit 1 von threshold bedeutet, dass das Werkzeug funktioniert. Es bedeutet, dass der Alarm ausgelöst wurde. Melden Sie den rollierenden Gesamtbetrag, den Überschreitungsbetrag und dass eine Registrierung erforderlich ist – umgehend, nicht versteckt.
• QST geht niemals in den Netto ein. Wenn Sie Quebec-Zeilen zusammenfassen, halten Sie QST als separate Memo-Zahl. Fügen Sie erhobene QST nicht zu net_tax_owing hinzu und behandeln Sie gezahlte QST nicht als Vorsteuer.
• Provinzielle Schätzungen sind Schätzungen. Die PST/RST-Zahlen der provinces-Ansicht und die QST-Zahl für nicht erfasste Quebec-Verkäufe sind Satz×Verkaufs-Schätzungen aus der kodierten Tabelle – präsentieren Sie sie niemals als erhobene, geschuldete oder eingereichte Beträge, und führen Sie immer den Kodierte-Sätze-Stempel („geprüft Nov. 2026 – gegen CRA/provinzielle Quellen vor der Einreichung verifizieren”) an, wenn Sie die Sätze zitieren. PST/RST, die auf Eingaben gezahlt wurden, sind in diesem Werkzeug niemals eine Vorsteuer.
• Ein negatives Netto ist eine Erstattungsposition, kein Einkommen. Beschreiben Sie es nicht als erhaltenes Geld.
• Strafen und Zinsen werden niemals berechnet – wenn der Benutzer in einem früheren Zeitraum überschritten hat, ist dies ein Gespräch mit der CRA/einem Buchhalter; schätzen Sie keinen Betrag.
• Nur lokal: das Werkzeug liest die Datei, auf die Sie es verweisen, und sendet nichts irgendwohin.