jasveerai88/gst-hst-tracker

gst-hst-tracker — habilidad para agente

Propósito

Los autónomos y empresarios individuales canadienses realizan un seguimiento de GST/HST en hojas de cálculo y descubren el umbral de $30,000 para pequeños proveedores de la CRA después de superarlo. Esta herramienta lee un libro mayor de transacciones fechadas y produce (a) el GST/HST recaudado por trimestre, los ITCs y el impuesto neto adeudado con una sección preparatoria de ingresos/gastos estilo T2125, (b) la prueba de umbral: ingresos gravables acumulados de los últimos 4 trimestres naturales frente al límite de $30,000, con margen o una alarma de superación, y (c) una vista por provincia del mismo libro mayor: sistema fiscal, recaudado, ITCs y neto por provincia, con el componente provincial mostrado solo hasta donde los datos lo permitan (QST registrado como cifras memo más una estimación en ventas de QC no registradas; PST/RST como estimaciones de exposición tasa×ventas). Biblioteca estándar de Python pura; solo local; lee un archivo de libro mayor, no escribe nada.

El núcleo de honestidad de esta herramienta: es una ayuda de seguimiento y cálculo, no asesoría fiscal y no una declaración ante la CRA. Cada informe lleva ese descargo de responsabilidad, y también debe llevarlo cualquier cosa que escriba a partir de su salida. Nunca calcula multas ni intereses.

Cuándo usarla / no usarla

Úsela cuando:

• Esté preparando las cifras de GST/HST de un trimestre a partir de un libro mayor de transacciones: recaudado, ITCs, neto adeudado.
• Esté verificando qué tan cerca está un autónomo del umbral de registro de $30,000, o si lo ha superado.
• Esté organizando categorías de ingresos y gastos en una vista preparatoria estilo T2125 para la temporada de declaración.
• Un agente necesite cifras canadienses de GST/HST en las que pueda confiar en JSON.

NO la use cuando:

• El usuario necesite asesoría fiscal, una declaración o una resolución sobre sus obligaciones: esta herramienta no puede proporcionarlas. Diríjalo a la CRA o a un contador calificado.
• La pregunta involucre multas o intereses: nunca se calculan.
• Los libros sean libros de QST de Quebec: aquí QST es solo memo (consulte Límites). PST de BC / PST de SK / RST de MB aparecen solo como estimaciones de exposición en la vista provinces — nunca como impuestos adeudados o créditos.
• El libro mayor esté desactualizado: la ventana del umbral está anclada a la transacción más reciente, por lo que un libro mayor desactualizado da una ventana desactualizada. Dígalo si las fechas parecen antiguas.

Instalación

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

(No está en PyPI: la forma git+ es la instalación). Desde un checkout del código fuente, python3 src/gst_hst_tracker.py ... es equivalente.

Comandos

# Informe trimestral (entrada JSON o CSV; código de salida 0 en caso de éxito)
gst-hst-tracker report LEDGER.json
gst-hst-tracker report LEDGER.csv --json

# Solo un trimestre natural o un año
gst-hst-tracker report LEDGER.json --period 2026-Q1
gst-hst-tracker report LEDGER.json --period 2026

# La alarma de pequeño proveedor (código de salida 1 cuando se supera, 0 en caso contrario)
gst-hst-tracker threshold LEDGER.json [--limit 30000]

# La vista provincial (código de salida 0 en caso de éxito)
gst-hst-tracker provinces LEDGER.json
gst-hst-tracker provinces LEDGER.json --period 2026-Q1 --json

# También muestra equivalentes en INR (tasa por 1 CAD)
gst-hst-tracker report LEDGER.json --cad-to-inr 67.97

# Sobrescribir una tasa provincial cuando cambia
gst-hst-tracker report LEDGER.json --rate NS=15

Filas de entrada (lista JSON, objeto {"transactions": [...]} o CSV con los mismos encabezados): date (YYYY-MM-DD, requerido), kind (income|expense, requerido), description (requerido), amount (CAD antes de impuestos, requerido, ≥ 0), province (código de dos letras, requerido); opcional tax (GST/HST cobrado/pagado — omita para calcular a partir de la tasa provincial; 0 significa tasa cero y se respeta), qst (solo filas de QC; se rastrea por separado, nunca en el neto), category (solo gastos; agrupación estilo T2125).

El modelo (indíquelo cuando informe resultados)

• Impuesto neto adeudado por trimestre natural = GST/HST recaudado sobre ingresos − ITCs (GST/HST pagado sobre gastos). Neto negativo = ITCs superan a lo recaudado: posición de reembolso, no efectivo disponible.
• Umbral: suministros gravables (solo filas de ingresos) durante los últimos 4 trimestres naturales que terminan en el trimestre de la transacción más reciente. La prueba de la CRA es supera los $30,000 — exactamente $30,000 sigue siendo un pequeño proveedor (status: "at", código de salida 0).
• Tasas predeterminadas a partir de noviembre de 2026: GST 5% (AB BC MB NT NU SK YT), HST 13% ON, HST 15% NB/NL/PE, HST 14% NS (reducida del 15% el 2025-04-01), QC = GST 5% solo parte federal.
• QST (9.975%) es un impuesto separado de Revenu Québec: los montos qst proporcionados aparecen solo como totales memo y nunca entran en el neto.
• Vista provincial (provinces): las mismas matemáticas federales agrupadas por la provincia de la fila. Impuestos provinciales codificados, con la estampilla "Tasas codificadas, verificadas en noviembre de 2026 — verifique con fuentes CRA/provinciales antes de declarar": QST 9.975% (QC), PST 7% (BC), PST 6% (SK), RST 7% (MB); las provincias HST no tienen un componente provincial separado. QC muestra los totales de QST registrados más una estimación en filas de ingresos de QC sin qst registrado; BC/SK/MB muestran solo una estimación de exposición tasa×ventas, y ningún ITC provincial (PST/RST sobre insumos es generalmente un costo). Redondeo: las cifras por provincia se redondean a céntimos y el resumen suma esas cifras redondeadas, por lo que siempre coincide con los bloques de provincia.

Esquema de salida JSON (--json)

report: tool ("gst-hst-tracker"), version, command ("report"), file, currency ("CAD"), rates (rate_pct por provincia + etiqueta, con estampilla as_of: "2026-11", más la nota de QST), cad_to_inr (tasa o nulo), period_filter (cadena o nulo), periods, totals, disclaimer.

Cada período: period (ej. "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 suma los mismos campos en los períodos mostrados. Con --cad-to-inr, los campos monetarios ganan hermanos *_inr.

threshold: los campos comunes más latest_transaction, window_end_quarter, quarters (cuatro entradas {quarter, income}, la más antigua primero), rolling_total, limit, headroom (0 cuando se supera), over_by (0 cuando no se supera), crossed (bool), status ("under" | "at" | "crossed"), rule, disclaimer.

provinces: los campos comunes más provincial_rates (stamp, qst_rate_pct, taxes — por provincia federal label y provincial_tax {name, rate_pct} o nulo), rounding_rule, provinces, totals, disclaimer. Cada entrada en provinces: province, tax_system (construido a partir de las tasas efectivas, ej. "GST 5% + PST 7%"), income_total, expense_total, gst_hst_collected, itcs, net_tax_owing, transactions, y provincial — nulo para provincias solo GST y HST; en caso contrario {name, rate_pct, recorded_collected, recorded_paid, recorded_net} (números para QC, nulo para BC/SK/MB — no hay nada registrado para esas), estimate_base, estimated_on_sales, note. totals añade qst_recorded_collected / qst_recorded_paid / qst_recorded_net y provincial_estimated_on_sales.

En caso de error, stdout es un solo objeto: {"error": "<mensaje>"} (los errores de validación nombran la fila: "fila 2: ...") con código de salida 2 — incluidos los errores de uso de argparse en modo --json. Nunca texto plano, nunca un traceback.

Códigos de salida

• report: 0 — informe calculado. 2 — error.
• provinces: 0 — vista calculada. 2 — error. (Sin estado de salida 1: la vista es informativa; la alarma está en threshold.)
• threshold: 0 — el total acumulado está por debajo o exactamente en el límite: todavía es un pequeño proveedor según estas cifras. 1 — UMBRAL SUPERADO: el total acumulado supera el límite y se requiere registro de GST/HST. Esto es un hallazgo, no un fallo: preséntelo de manera destacada. 2 — error: no se produjeron números; no cite ninguno.
• Los errores en cualquier comando salen con 2 y un mensaje limpio (o el objeto {"error": ...} en modo --json).

Límites y reglas de honestidad que el agente debe respetar

• No es asesoría fiscal, no es una declaración. Nunca presente el resultado de esta herramienta como asesoría o como una declaración presentada. El descargo de responsabilidad en cada salida es esencial: manténgalo adjunto a cualquier resumen que escriba.
• Las tasas son valores predeterminados de noviembre de 2026, no hechos actualizados. Cítelas como "los valores predeterminados de noviembre de 2026 de la herramienta" y note que se pueden sobrescribir. Nueva Escocia es 14% (fue 15% hasta el 2025-03-31) — si las cifras de un usuario se calcularon al 15% para NS, vale la pena señalarlo, no aceptarlo en silencio.
• Exactamente $30,000 NO está superado. La prueba de la CRA es "supera los $30,000". Si status es "at", informe "sigue siendo un pequeño proveedor, margen cero" — nunca "debe registrarse".
• El código de salida 1 de threshold es la herramienta funcionando. Significa que la alarma se disparó. Informe el total acumulado, la cantidad en exceso y que se requiere registro — de inmediato, no enterrado.
• QST nunca entra en el neto. Si resume filas de Quebec, mantenga QST como una cifra memo separada. No agregue QST recaudado a net_tax_owing, y no trate QST pagado como un ITC.
• Las estimaciones provinciales son estimaciones. Las cifras de PST/RST de la vista provinces y la cifra de QST en ventas no registradas de Quebec son estimaciones tasa×ventas de la tabla codificada — nunca las presente como montos recaudados, adeudados o declarados, y siempre lleve la estampilla de tasas codificadas ("verificadas en noviembre de 2026 — verifique con fuentes CRA/provinciales antes de declarar") cuando cite las tasas. PST/RST pagado sobre insumos nunca es un ITC en esta herramienta.
• Un neto negativo es una posición de reembolso, no un ingreso. No lo describa como dinero recibido.
• Multas e intereses nunca se calculan — si el usuario superó el umbral en un período anterior, eso es una conversación con la CRA/un contador; no estime un monto.
• Solo local: la herramienta lee el archivo al que apunta y no envía nada a ninguna parte.