jasveerai88/gst-hst-tracker

gst-hst-tracker — compétence d'agent

Objectif

Les travailleurs indépendants et entrepreneurs individuels canadiens suivent la TPS/TVH dans des feuilles de calcul et découvrent le seuil de petit fournisseur de 30 000 $ de l'ARC après l'avoir franchi. Cet outil lit un grand livre de transactions datées et produit (a) la TPS/TVH collectée par trimestre, les CTI et la taxe nette due avec une section préparatoire de style T2125 pour les revenus/dépenses, (b) le test de seuil : revenu imposable des 4 derniers trimestres civils roulants par rapport à la limite de 30 000 $, avec marge ou alarme de dépassement, et (c) une vue par province du même grand livre : système fiscal, montants collectés, CTI et net par province, avec la composante provinciale montrée uniquement dans la mesure où les données le permettent (TVQ enregistrée comme chiffres mémorisés plus une estimation sur les ventes QC non enregistrées ; TVP/TVentes comme estimations d'exposition taux×ventes). Bibliothèque standard Python pure ; locale uniquement ; lit un fichier de grand livre, n'écrit rien.

Le cœur honnête de cet outil : c'est une aide au suivi et au calcul, pas un conseil fiscal et pas une déclaration à l'ARC. Chaque rapport porte cet avertissement, et tout ce que vous rédigez à partir de ses résultats doit en faire de même. Il ne calcule jamais de pénalités ni d'intérêts.

Quand utiliser / ne pas utiliser

À utiliser lorsque :

• Vous préparez les chiffres de TPS/TVH d'un trimestre à partir d'un grand livre de transactions : collectée, CTI, net dû.
• Vous vérifiez à quel point un travailleur indépendant est proche du seuil d'inscription de 30 000 $, ou s'il l'a franchi.
• Vous organisez les catégories de revenus et de dépenses dans une vue préparatoire de style T2125 pour la saison des déclarations.
• Un agent a besoin de chiffres canadiens de TPS/TVH fiables en JSON.

Ne PAS utiliser lorsque :

• L'utilisateur a besoin de conseils fiscaux, d'une déclaration ou d'une décision sur ses obligations — cet outil ne peut pas en fournir. Orientez-le vers l'ARC ou un comptable qualifié.
• La question implique des pénalités ou des intérêts — jamais calculés.
• Les livres sont des livres de TVQ du Québec : la TVQ n'est qu'en mémoire ici (voir Limites). La TVP de la C.-B. / la TVP de la Sask. / la TVentes du Man. n'apparaissent que comme des estimations d'exposition dans la vue provinces — jamais comme des taxes dues ou des crédits.
• Le grand livre est obsolète : la fenêtre de seuil est ancrée à la transaction la plus récente, donc un grand livre obsolète donne une fenêtre obsolète. Dites-le si les dates semblent anciennes.

Installation

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

(Pas sur PyPI — la forme git+ est l'installation.) À partir d'une copie source, python3 src/gst_hst_tracker.py ... est équivalent.

Commandes

# Rapport trimestriel (entrée JSON ou CSV ; sortie 0 en cas de succès)
gst-hst-tracker report LEDGER.json
gst-hst-tracker report LEDGER.csv --json

# Un seul trimestre civil ou une seule année
gst-hst-tracker report LEDGER.json --period 2026-Q1
gst-hst-tracker report LEDGER.json --period 2026

# L'alarme du petit fournisseur (sortie 1 en cas de dépassement, 0 sinon)
gst-hst-tracker threshold LEDGER.json [--limit 30000]

# La vue provinciale (sortie 0 en cas de succès)
gst-hst-tracker provinces LEDGER.json
gst-hst-tracker provinces LEDGER.json --period 2026-Q1 --json

# Afficher également les équivalents en INR (taux pour 1 CAD)
gst-hst-tracker report LEDGER.json --cad-to-inr 67.97

# Remplacer un taux provincial lorsqu'il change
gst-hst-tracker report LEDGER.json --rate NS=15

Lignes d'entrée (liste JSON, objet {"transactions": [...]}, ou CSV avec les mêmes en-têtes) : date (AAAA-MM-JJ, obligatoire), kind (income|expense, obligatoire), description (obligatoire), amount (CAD avant impôt, obligatoire, ≥ 0), province (code à deux lettres, obligatoire) ; optionnel tax (TPS/TVH facturée/payée — omettre pour calculer à partir du taux provincial ; 0 signifie taux zéro et est respecté), qst (lignes QC uniquement ; suivie séparément, jamais dans le net), category (dépenses uniquement ; regroupement de style T2125).

Le modèle (énoncez-le lorsque vous rapportez les résultats)

• Taxe nette due par trimestre civil = TPS/TVH collectée sur les revenus − CTI (TPS/TVH payée sur les dépenses). Net négatif = les CTI dépassent les montants collectés : une position de remboursement, pas de l'argent en caisse.
• Seuil : fournitures taxables (lignes de revenus uniquement) au cours des 4 derniers trimestres civils se terminant au trimestre de la transaction la plus récente. Le test de l'ARC est dépasse 30 000 $ — exactement 30 000 $ est toujours un petit fournisseur (status: "at", sortie 0).
• Taux par défaut au 2026-11 : TPS 5 % (AB BC MB NT NU SK YT), TVH 13 % ON, TVH 15 % NB/NL/PE, TVH 14 % NS (réduit de 15 % le 2025-04-01), QC = TPS 5 % partie fédérale uniquement.
• TVQ (9,975 %) est un impôt distinct de Revenu Québec : les montants de qst fournis apparaissent uniquement comme totaux mémorisés et n'entrent jamais dans le net.
• Vue provinciale (provinces) : les mêmes calculs fédéraux regroupés par province de la ligne. Taxes provinciales encodées, estampillées « Taux encodés, vérifié 2026-11 — à vérifier auprès des sources ARC/provinciales avant de déclarer » : TVQ 9,975 % (QC), TVP 7 % (BC), TVP 6 % (SK), TVentes 7 % (MB) ; les provinces avec TVH n'ont pas de composante provinciale distincte. QC montre les totaux de TVQ enregistrés plus une estimation sur les lignes de revenus QC sans qst enregistrée ; BC/SK/MB montrent une estimation d'exposition taux×ventes uniquement, et aucun CTI provincial (la TVP/TVentes sur les intrants est généralement un coût). Arrondi : les chiffres par province sont arrondis au centime et les totaux récapitulatifs additionnent ces chiffres arrondis, ce qui concilie toujours avec les blocs provinciaux.

Schéma de sortie JSON (--json)

report : tool ("gst-hst-tracker"), version, command ("report"), file, currency ("CAD"), rates (rate_pct par province + étiquette, estampillé as_of: "2026-11", plus la note TVQ), cad_to_inr (taux ou null), period_filter (chaîne ou null), periods, totals, disclaimer.

Chaque période : period (p. ex. "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 additionne les mêmes champs pour les périodes affichées. Avec --cad-to-inr, les champs monétaires gagnent des équivalents *_inr.

threshold : les champs communs plus latest_transaction, window_end_quarter, quarters (quatre entrées {quarter, income}, les plus anciennes en premier), rolling_total, limit, headroom (0 en cas de dépassement), over_by (0 sinon), crossed (booléen), status ("under" | "at" | "crossed"), rule, disclaimer.

provinces : les champs communs plus provincial_rates (stamp, qst_rate_pct, taxes — étiquette federal par province et provincial_tax {name, rate_pct} ou null), rounding_rule, provinces, totals, disclaimer. Chaque entrée dans provinces : province, tax_system (construit à partir des taux effectifs, p. ex. "GST 5% + PST 7%"), income_total, expense_total, gst_hst_collected, itcs, net_tax_owing, transactions, et provincial — null pour les provinces à TPS uniquement et à TVH ; sinon {name, rate_pct, recorded_collected, recorded_paid, recorded_net} (nombres pour QC, null pour BC/SK/MB — rien n'est enregistré pour celles-ci), estimate_base, estimated_on_sales, note. totals ajoute qst_recorded_collected / qst_recorded_paid / qst_recorded_net et provincial_estimated_on_sales.

En cas d'erreur, stdout est un seul objet : {"error": "<message>"} (les erreurs de validation nomment la ligne : "row 2: ...") avec code de sortie 2 — y compris les erreurs d'utilisation d'argparse en mode --json. Jamais de texte brut, jamais de traceback.

Codes de sortie

• report : 0 — rapport calculé. 2 — erreur.
• provinces : 0 — vue calculée. 2 — erreur. (Pas d'état sortie-1 : la vue est informative ; l'alarme vit dans threshold.)
• threshold : 0 — le total roulant est inférieur ou exactement égal à la limite : toujours un petit fournisseur selon ces chiffres. 1 — SEUIL FRANCHI : le total roulant dépasse la limite et l'inscription à la TPS/TVH est requise. C'est un constat, pas un échec : affichez-le de manière proéminente. 2 — erreur : aucun nombre n'a été produit ; n'en citez aucun.
• Les erreurs dans l'une ou l'autre commande sortent avec 2 et un message propre (ou l'objet {"error": ...} en mode --json).

Limites et règles d'honnêteté que l'agent doit respecter

• Pas un conseil fiscal, pas une déclaration. Ne présentez jamais les résultats de cet outil comme des conseils ou une déclaration déposée. L'avertissement dans chaque sortie est essentiel : conservez-le dans tout résumé que vous écrivez.
• Les taux sont des valeurs par défaut de 2026-11, pas des faits en direct. Citez-les comme « les valeurs par défaut de l'outil de nov. 2026 » et notez qu'ils sont modifiables. La Nouvelle-Écosse est à 14 % (elle était à 15 % jusqu'au 2025-03-31) — si les chiffres d'un utilisateur ont été calculés à 15 % pour la N.-É., cela mérite d'être signalé, pas accepté silencieusement.
• Exactement à 30 000 $ n'est PAS franchi. Le test de l'ARC est « dépasse 30 000 $ ». Si le status est "at", signalez « toujours un petit fournisseur, marge nulle » — jamais « doit s'inscrire ».
• La sortie 1 de threshold est l'outil qui fonctionne. Cela signifie que l'alarme s'est déclenchée. Signalez le total roulant, le montant du dépassement et que l'inscription est requise — rapidement, pas enterré.
• La TVQ n'entre jamais dans le net. Si vous résumez des lignes du Québec, gardez la TVQ comme un chiffre mémorisé séparé. N'ajoutez pas la TVQ collectée à net_tax_owing et ne traitez pas la TVQ payée comme un CTI.
• Les estimations provinciales sont des estimations. Les chiffres de TVP/TVentes de la vue provinces et le chiffre de TVQ sur les ventes non enregistrées du Québec sont des estimations taux×ventes provenant du tableau encodé — ne les présentez jamais comme des montants collectés, dus ou déclarés, et incluez toujours l'estampille des taux encodés (« vérifié 2026-11 — à vérifier auprès des sources ARC/provinciales avant de déclarer ») lorsque vous citez les taux. La TVP/TVentes payée sur les intrants n'est jamais un CTI dans cet outil.
• Un net négatif est une position de remboursement, pas un revenu. Ne le décrivez pas comme de l'argent reçu.
• Les pénalités et les intérêts ne sont jamais calculés — si l'utilisateur a franchi le seuil au cours d'une période antérieure, c'est une conversation avec l'ARC ou un comptable ; n'estimez pas de montant.
• Local uniquement : l'outil lit le fichier que vous lui indiquez et n'envoie rien nulle part.