اپنے انوائس اور اخراجات کے ڈیٹا بیس سے Claude Code کے ساتھ VAT ریٹرن سسٹم بنانا

یہ لمبی شکل کا گہرا غوطہ ہے۔ تیز تر، سکم پڑھنے کے قابل ورژن کے لیے، دیکھیں ساتھی بلاگ پوسٹ.

1. میں نے اسے کیوں بنایا

VAT-رجسٹریشن کی حد سے زیادہ ٹیکس کے قابل کاروبار کے ساتھ UK کے ہر چھوٹے کاروبار کو HMRC کی Making Tax Digital (MTD) سروس کے ذریعے - عام طور پر سہ ماہی - VAT ریٹرن کا حساب لگانا اور جمع کروانا پڑتا ہے۔ نو نمبر والے خانے۔ آؤٹ پٹ VAT مائنس ان پٹ VAT۔ خالص رقم ادا کریں، یا رقم کی واپسی کا دعوی کریں۔ نظریہ میں آسان؛ عملی طور پر سزا دینا جب آپ کی رسیدیں Postgres میں رہتی ہیں، آپ کے اخراجات کی رسیدیں بیس مختلف سپلائرز کی PDF ہیں، آپ کے بینک اسٹیٹمنٹس Wise اور Revolut سے CSV ہیں، اور آپ کی غیر ملکی کرنسی لائنوں کو صحیح ماہانہ شرح پر پاؤنڈز میں دوبارہ بیان کرنا ہوگا۔

چند سالوں کے لیے میں ایک بڑی اسپریڈشیٹ، کیلنڈر کی یاد دہانی، اور ایمان کی ایک چھوٹی سی چھلانگ سے الجھتا رہا۔ ہر سہ ماہی میں تقریباً آدھا دن لگتا تھا، جس میں سے زیادہ تر ڈیٹا کا جھگڑا ہوتا تھا - انوائسز DB سے CSV برآمد کریں، Excel میں پیسٹ کریں، چند سو قطاروں کو ہاتھ سے درجہ بندی کریں، فارمولوں کو دو بار چیک کریں، نو نمبروں کو فریق ثالث MTD برج میں کاپی کریں، جمع کرائیں پر کلک کریں۔ آڈٹ ٹریل تھا "مجھ پر بھروسہ کریں، میرے پاس ایک اسپریڈشیٹ تھی"۔ وسط سہ ماہی کی شرح میں تبدیلی نے اسے توڑ دیا۔ رسیدیں غائب ہوگئیں۔ ایک غلط درجہ بندی کو آگے بڑھا سکتا ہے۔ Box 5 سینکڑوں پاؤنڈ کی کمی.

میں نے اس سال پائپ لائن کو ایک چھوٹے کے طور پر دوبارہ بنایا Claude Code پروجیکٹ جو میرے انوائس اور اخراجات کے ڈیٹا بیس سے براہ راست بات کرتا ہے، ہر لائن کی درجہ بندی کرتا ہے، ایک ڈیٹرمنسٹک Python انجن کے ساتھ Box 1 سے Box 9 کی گنتی کرتا ہے، ریٹرن کو مارک ڈاؤن رپورٹ کے طور پر خشک کرتا ہے، اور صرف اس کے بعد جب انسانی نشانیاں HMRC MTD پر جمع ہو جاتی ہیں۔ پوری سہ ماہی میں اب مجھے تقریباً ایک گھنٹہ لگتا ہے، جس میں سے زیادہ تر اپنے اکاؤنٹنٹ کے ساتھ ڈرائی رن کا جائزہ لے رہا ہے۔ آڈٹ ٹریل ایک گٹ ریپو ہے۔ ریاضی کا یونٹ ٹیسٹ کیا جاتا ہے۔ درجہ بندی ایک دستاویزی مارک ڈاؤن فائل ہے۔ جمع کرانے کا دروازہ بند ہے۔

یہ مضمون طویل ورژن ہے۔ پرامپٹس، ازگر، اسکیما، HMRC OAuth بہاؤ، کنارے کے کیسز۔ اگر آپ پہلے مختصر ورژن چاہتے ہیں تو پڑھیں ساتھی بلاگ.

2. HMRC MTD پرائمر (اور دستبرداری)

VAT کے لیے Making Tax Digital HMRC کا تقاضا ہے کہ VAT-رجسٹرڈ کاروبار ڈیجیٹل ریکارڈ رکھیں اور gov.uk ویب فارم میں نمبر ٹائپ کرنے کی بجائے دستاویزی API کے ذریعے ہم آہنگ سافٹ ویئر کے ذریعے ریٹرن جمع کرائیں۔ API OAuth2 ہے، اس کے لیے ابتدائی ڈیوائس کی شناخت کے لیے دھوکہ دہی سے بچاؤ کے HTTP ہیڈر کی ضرورت ہوتی ہے، اور آپ کے لائیو پروڈکشن کو چھونے سے پہلے ایک مفت سینڈ باکس میں دستیاب ہے۔

واپسی بذات خود نو باکسز ہے: Box 1 VAT فروخت اور دیگر آؤٹ پٹس پر واجب الادا ہے۔ Box 2 VAT ہے جو یورپی یونین کے رکن ممالک سے سامان کے حصول پر ہے (NI پروٹوکول کے تحت شمالی آئرلینڈ کے کاروبار کے لیے متعلقہ)؛ Box 3 کل VAT واجب الادا ہے (Box 1 + Box 2)؛ Box 4 VAT خریداریوں پر دوبارہ دعویٰ کرنے کے قابل ہے (ان پٹ VAT)؛ Box 5 ادائیگی یا دوبارہ دعوی کرنے کے لیے خالص VAT ہے (Box 3 - Box 4)؛ Box 6 VAT کو چھوڑ کر کل فروخت ہے۔ Box 7 VAT کو چھوڑ کر کل خریداری ہے۔ Box 8 یورپی یونین کے رکن ممالک کو فراہم کردہ سامان کی کل قیمت ہے (دوبارہ صرف NI)؛ Box 9 EU کے رکن ممالک سے حصول کی کل قیمت ہے (صرف NI)۔ اسکیم کی مختلف قسمیں ہیں - فلیٹ ریٹ اسکیم، کیش اکاؤنٹنگ، سالانہ اکاؤنٹنگ - وہ تبدیلی کس طرح آپ نمبرز پر پہنچتے ہیں لیکن باکس کی شکل پر نہیں۔

ڈس کلیمر میں ایک سافٹ ویئر انجینئر ہوں، چارٹرڈ اکاؤنٹنٹ نہیں۔ یہ مضمون ہے۔ ٹیکس مشورہ نہیں. VAT کی درجہ بندی، جزوی استثنیٰ، فلیٹ ریٹ اسکیم، ڈیجیٹل سروسز کے لیے جگہ کی فراہمی کے اصول، EU سامان اور خدمات کا بریکسٹ کے بعد کا علاج، اور NI پروٹوکول کے صحیح اصول وقت کے ساتھ ساتھ بدلتے ہیں اور آپ کے مخصوص حالات پر منحصر ہوتے ہیں۔ اس سے پہلے کہ آپ کسی حقیقی HMRC اکاؤنٹ کے خلاف ایسا کچھ بھی چلائیں، اپنی پہلی واپسی کے آخر سے آخر تک جائزہ لینے کے لیے برطانیہ میں رجسٹرڈ اکاؤنٹنٹ حاصل کریں۔ کسی بھی مخصوص ایج کیس پر مستند اصول کے لیے، gov.uk ویب سائٹ پر HMRC VAT نوٹس 700 اور متعلقہ نوٹس دیکھیں۔ آپ کے اکاؤنٹنٹ کے وقت کے ایک گھنٹہ کی قیمت خراب جمع کرانے کی قیمت سے بہت کم ہے۔

3. ڈیٹا ماڈل

نیچے کی طرف جانے والی ہر چیز کا انحصار دو میزوں کی شکل پر ہے: جاری کردہ رسیدیں (فروخت) اور ریکارڈ شدہ اخراجات (خریداری)۔ میں Postgres میں اپنا رکھتا ہوں لیکن وہی شکل MySQL یا SQLite پر کام کرتی ہے۔ کم از کم مفید سکیما:

CREATE TABLE invoices (
  id              BIGSERIAL PRIMARY KEY,
  invoice_number  TEXT NOT NULL UNIQUE,
  issued_at       DATE NOT NULL,
  customer_name   TEXT NOT NULL,
  customer_vat_no TEXT,
  customer_country CHAR(2) NOT NULL,
  net_amount      NUMERIC(14,2) NOT NULL,
  vat_amount      NUMERIC(14,2) NOT NULL,
  gross_amount    NUMERIC(14,2) NOT NULL,
  currency        CHAR(3) NOT NULL DEFAULT 'GBP',
  fx_rate_to_gbp  NUMERIC(18,8) NOT NULL DEFAULT 1,
  vat_rate        NUMERIC(5,2) NOT NULL,
  vat_treatment   TEXT NOT NULL,
  status          TEXT NOT NULL,
  paid_at         DATE,
  notes           TEXT,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE expenses (
  id              BIGSERIAL PRIMARY KEY,
  supplier_name   TEXT NOT NULL,
  supplier_vat_no TEXT,
  supplier_country CHAR(2) NOT NULL,
  incurred_at     DATE NOT NULL,
  net_amount      NUMERIC(14,2) NOT NULL,
  vat_amount      NUMERIC(14,2) NOT NULL,
  gross_amount    NUMERIC(14,2) NOT NULL,
  currency        CHAR(3) NOT NULL DEFAULT 'GBP',
  fx_rate_to_gbp  NUMERIC(18,8) NOT NULL DEFAULT 1,
  vat_rate        NUMERIC(5,2) NOT NULL,
  vat_treatment   TEXT NOT NULL,
  category        TEXT NOT NULL,
  receipt_url     TEXT,
  notes           TEXT,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

غیر واضح کالم ہیں۔ vat_treatment, fx_rate_to_gbp، اور ملک کے کوڈز۔ علاج ایک چھوٹا سا اینوم ہے جسے درجہ بندی کرنے والے اور انجن دونوں کے ذریعہ استعمال کیا جاتا ہے۔ کنٹری کوڈ ریورس چارج اور یورپی یونین کے حصول کی منطق چلاتا ہے۔ ایف ایکس ریٹ آپ کو غیر ملکی کرنسی کی رسیدوں کو ان کی اصل کرنسی میں رکھنے اور باکس کے ٹوٹل کے لیے GBP میں دوبارہ اسٹیٹ کرنے دیتا ہے۔

ان کالموں کو لیگیسی انوائسز ٹیبل پر بیک فل کرنا پروجیکٹ کا سب سے سست حصہ ہے۔ Claude Code منتقلی پیدا کر سکتا ہے؛ آپ کو ابھی بھی عجیب و غریب کنارے کے معاملات کو ہاتھ سے درجہ بندی کرنے کی ضرورت ہے۔

4. کیوں Claude Code (اور Xero / QuickBooks / FreeAgent نہیں)

زیادہ تر برطانیہ کے چھوٹے کاروباروں کے لیے جواب ہے - حقیقی طور پر - پیکیجڈ سافٹ ویئر استعمال کریں۔ Xero, QuickBooks, FreeAgent, Sage سبھی کے پاس HMRC سے تصدیق شدہ MTD جمع کرانے، مہذب UIs، اور اکاؤنٹنٹ ہیں جو انہیں پہلے سے جانتے ہیں۔ آپ کو اپنے VAT سسٹم کو رول نہیں کرنا چاہئے جب تک کہ آپ کے پاس کوئی واضح وجہ نہ ہو۔

میری وجوہات تنگ مگر حقیقی تھیں۔ میں پہلے ہی سافٹ ویئر کے کام کے لیے ہر روز Claude Code استعمال کرتا ہوں، اس لیے اسے VAT کے لیے بھی استعمال کرنے کی معمولی کوشش چھوٹی تھی۔ میری انوائس DB میری اپنی مشین پر رہتی ہے۔ میں ترجیح دیتا ہوں کہ اسے ساس کرایہ دار میں عکس بند نہ کیا جائے۔ میرا سپلائر مکس عجیب ہے (ریورس چارج کے ساتھ EU خدمات، ملتوی درآمد VAT، کبھی کبھار صفر ریٹیڈ ایج کیسز) اور ایک ہی مارک ڈاون فائل میں قواعد کو انکوڈنگ کے علاوہ ایک Python ماڈیول ان کو سنبھالنے کے لیے SaaS کو ترتیب دینے سے تیز تر نکلا۔ اور آڈٹ ٹریل جو مجھے گٹ ریپو سے ملتا ہے - ہر درجہ بندی کرنے والا پرامپٹ، ہر فرق، ہر دستخط شدہ مدت کا سنیپ شاٹ - بالکل وہی آڈٹ ٹریل ہے جو میں چاہتا ہوں۔

Claude Code تین وجوہات کی بناء پر اس کے لیے موزوں ہے۔ سب سے پہلے، یہ براہ راست ڈسک پر کسی پروجیکٹ کے خلاف کام کرتا ہے: یہ میری اسکیما، پرائی کوارٹر ڈرائی رن رپورٹس، رولز فائل، اور ازگر انجن کو پڑھ سکتا ہے، اور سیاق و سباق میں ترمیم کی تجویز پیش کر سکتا ہے۔ دوسرا، یہ بورنگ سہاروں میں اچھا ہے - ہجرت کے اسکرپٹ، CSV درآمد کنندگان، مفاہمت کی رپورٹس، پائٹسٹ فکسچر۔ تیسرا، جب یہ کسی سطر کی درجہ بندی کرتا ہے، تو یہ سادہ انگریزی میں اس کے استدلال کی وضاحت کرتا ہے، بالکل وہی جو میں واپسی پر دستخط کرنے سے پہلے جائزہ لینا چاہتا ہوں۔ نیچے دیے گئے ورک فلو ڈایاگرام کے نیچے فیصلہ میٹرکس اس ٹریڈ آف کا دیانت دار ورژن ہے۔

5. فن تعمیر اور ورک فلو

پائپ لائن میں پانچ سوئم لین ہیں۔ ماخذ انوائسز اور اخراجات کے جدولوں تک صرف پڑھنے کے لیے رسائی ہے نیز اسٹرائپ، وائز، اور بینک فیڈز سے CSV کے لیے ایک ڈراپ فولڈر۔ Ingest + نارملائز کریں۔ ایک چھوٹا کلاڈ سے تیار کردہ Python اسکرپٹ ہے جو ہر سورس اسکیما کو ایک کیننیکل ویو میں نقشہ بناتا ہے، HMRC ماہانہ شرح پر غیر ملکی کرنسی کو GBP میں تبدیل کرتا ہے، تاریخ کی حد کا فلٹر لگاتا ہے، اور ہر قطار کو ایک idempotent کے ساتھ مہر لگاتا ہے۔ run_key لہذا دوبارہ رنز محفوظ ہیں. درجہ بندی + مصالحت Claude Code درجہ بندی کرنے والا ہے: یہ ہر کینونیکل قطار پر چلتا ہے، a چنتا ہے۔ vat_treatment میں قواعد کا استعمال کرتے ہوئے دستاویزی enum سے vat-rules.md, ادائیگیوں کے خلاف رسیدوں کو ملاتا ہے، اور بے ضابطگیوں کو جھنڈا دیتا ہے (منفی نیٹ، غائب سپلائر VAT نمبر، ملک کے کوڈ سے مماثلت نہیں، ایسے سپلائرز جن کو VAT-رجسٹرڈ ہونا چاہیے لیکن وہ نہیں ہیں)۔ VAT انجن ایک خالص Python ماڈیول ہے جو کلاسیفائیڈ قطاروں کو پڑھتا ہے اور Box 1 سے Box 9 کا تعین کرتا ہے۔ فلیٹ ریٹ، کیش اور سالانہ اسکیم کی شاخیں واضح کوڈ کے راستے ہیں۔ جمع کروائیں + آڈٹ یہ HMRC MTD API کال ہے (OAuth2، فراڈ سے بچاؤ کے ہیڈرز، سینڈ باکس پہلے)، ایک انسانی منظوری کے قدم کے پیچھے ہے، جس میں دستخط شدہ مدت کے سنیپ شاٹ اور مکمل کلاسیفائر لاگ لکھا گیا ہے جو چھ سال تک برقرار رکھے جانے والے صرف آڈٹ فولڈر میں لکھا گیا ہے۔

6. Claude Code کے ساتھ مرحلہ وار تعمیر

یہ وہی ورک فلو ہے جو میں نے اصل میں استعمال کیا تھا۔ پانچ اشارے میں نے ان کو اس مضمون کے لیے صاف کیا۔ اصل گڑبڑ ہیں.

پرامپٹ 1 - نارملائزر۔ "دیکھو invoices اور expenses میں میزیں schema.sql. ایک ازگر ماڈیول بنائیں normalise.py جو دونوں ٹیبلز کو استعمال کرتے ہوئے پڑھتا ہے۔ psycopg (صرف پڑھنے کا کردار vat_reader)، تاریخ کی حد تک محدود ہے۔ 2026-01-01 کو 2026-03-31، اور کلیدوں کے ساتھ کیننیکل ڈکٹ کی ایک فہرست خارج کرتا ہے: id, source, date, party, gross, net, vat_amount, vat_rate, vat_treatment, country, currency, fx_rate, run_key. استعمال کریں۔ Decimal، فلوٹ نہیں. ایک docstring اور a __main__ بلاک جو خلاصہ پرنٹ کرتا ہے۔"

کلاڈ نے اس کے ساتھ ایک صاف ماڈیول واپس کیا۔ Decimalپیرامیٹرائزڈ SQL، a build_run_key() جو ہیشز (period_start، period_end، اسکیم، schema_version) کو ایک مستحکم ہیکس سٹرنگ، اور کلک پر مبنی CLI میں تبدیل کرتا ہے۔ میں نے فیلڈ کے دو ناموں میں ترمیم کی اور باقی کو قبول کر لیا۔

پرامپٹ 2 - درجہ بندی کرنے والا۔ "پڑھو vat-rules.md اور لکھیں classify.py. سے ہر ایک کینونیکل قطار کے لیے normalise.py، سیٹ vat_treatment میں سے ایک کو: معیاری, کم, صفر, مستثنیٰ, دائرہ سے باہر, ریورس چارج, eu-سامان, eu-سروسز, ملتوی درآمد. اگر قطار میں پہلے سے ہی کوئی خالی نہیں ہے۔ vat_treatment، اسے اکیلا چھوڑ دیں اور اسے بطور ریکارڈ کریں۔ محفوظ. دوسری صورت میں، ملک کے کوڈ، سپلائر VAT نمبر، زمرہ، اور رقم سے فیصلہ کریں، اور ایک جملہ لکھیں reason ہر قطار پر. بے ضابطگیاں (منفی جال، رجسٹریشن کی حد سے اوپر کے یو کے سپلائر کے لیے لاپتہ سپلائر VAT، ملک کی مماثلت) ایک الگ پر جائیں anomalies.json انسانی جائزہ کے لیے۔ ماخذ DB کو تبدیل نہ کریں۔"

درجہ بندی خود ایک چھوٹا، زیادہ تر قواعد پر مبنی فنکشن ہے جس میں مبہم اخراجات کے زمرے کے لیے ایک LLM کی حمایت یافتہ شاخ ہے۔ تنقیدی طور پر، یہ کبھی بھی ماخذ DB کو نہیں لکھتا ہے - یہ ایک درجہ بند JSON فائل کو خارج کرتا ہے جسے انجن پڑھتا ہے۔ اگر میں کسی درجہ بندی سے متفق نہیں ہوں، تو میں JSON میں ترمیم کرتا ہوں؛ اگلی ڈرائی رن اسے اٹھا لیتی ہے۔

پرامپٹ 3 - انجن۔ "لکھو engine.py ایک خالص فعل کے طور پر: def compute_boxes(rows: list[Row], scheme: Scheme) -> BoxTotals. کوئی I/O نہیں۔ کوئی LLM نہیں۔ BoxTotals Box 1 سے Box 9 کے ساتھ ایک منجمد ڈیٹا کلاس ہے۔ Decimal قدریں 2 ڈی پی۔ کے لیے واضح شاخیں شامل کریں۔ standard, flat_rate, cash، اور annual سکیمیں معیاری اسکیم جمع ہے: فروخت VAT Box 1 میں حصہ ڈالتی ہے، VAT سے Box 4 خریدتی ہے۔ ریورس چارج انوائسز Box 1 اور Box 4 دونوں میں اضافہ کرتے ہیں۔ ملتوی درآمد VAT Box 1 اور Box 4 دونوں میں اضافہ کرتی ہے۔ NI کاروباروں کے لیے EU کے حصول Box 2 اور Box 9 میں ہوتے ہیں۔ باکس کے مجموعے پر گول، کبھی بھی فی قطار نہیں۔ ہر شاخ کو اس کے قاعدے سے جوڑنے والا ایک اصول لکھیں۔"

فوری 4 - خشک چلنے والی رپورٹ۔ "لکھو dryrun.py کہ کال کرتا ہے compute_boxes() اور ایک مارک ڈاؤن رپورٹ کا اخراج کرتا ہے: مدت اور اسکیم کے ساتھ ہیڈر، کیننیکل لیبلز کے ساتھ Box 1 سے Box 9 تک کا ایک ٹیبل، ایک سیکشن فی کلاسیفائر بالٹی جس میں مجموعی طور پر ٹاپ 10 قطاریں، ایک بے ضابطگیوں کا سیکشن، اور ایک فوٹر run_key اور درجہ بند JSON کا SHA-256۔ میں محفوظ کریں۔ ./audit/<period>/dryrun.md."

فوری 5 - جمع کرانے والا۔ "لکھو submit.py HMRC MTD VAT API v1.0 کے خلاف۔ PKCE کے ساتھ OAuth2 authorisation_code کا بہاؤ استعمال کریں۔ سے رسائی ٹوکن پڑھیں ~/.vat/token.json; اگر میعاد ختم ہو جائے تو تازہ کریں۔ HMRC کے ذریعے دستاویزی طور پر فراڈ سے بچاؤ کے ہیڈرز کی ضرورت ہے۔ ان سے ھیںچو fraud_headers.py. سینڈ باکس کے لیے ڈیفالٹ https://test-api.service.hmrc.gov.uk. مراحل: GET /organisations/vat/{vrn}/obligations?status=O، مماثل مدت تلاش کریں، آپریٹر کو ڈرائی رن سمری دکھا کر تصدیق کرنے کا اشارہ کریں، پھر POST /organisations/vat/{vrn}/returns کے ساتھ finalised: true. پرنٹ کریں۔ receiptId. جب تک لائیو کال نہ کریں۔ HMRC_ENV=live سیٹ ہے اور آپریٹر کی اقسام جمع کروائیں۔."

پانچ اشارے، چار فائلیں، اور ایک چھوٹی مارک ڈاؤن رولز دستاویز۔ کل تعمیر کا وقت شاید مرکوز شاموں کا ایک ہفتہ تھا، جن میں سے زیادہ تر درجہ بندی کے اصول اور HMRC OAuth ڈانس تھے۔

7. VAT انجن

انجن جان بوجھ کر بورنگ حصہ ہے۔ یہ یونٹ ٹیسٹ کے ساتھ ایک خالص فنکشن ہے اور کوئی AI نہیں ہے۔ یہ اصل شکل ہے:

from dataclasses import dataclass
from decimal import Decimal, ROUND_HALF_UP

D2 = Decimal("0.01")

@dataclass(frozen=True)
class BoxTotals:
    box1: Decimal
    box2: Decimal
    box3: Decimal
    box4: Decimal
    box5: Decimal
    box6: Decimal
    box7: Decimal
    box8: Decimal
    box9: Decimal

def _q(x: Decimal) -> Decimal:
    return x.quantize(D2, rounding=ROUND_HALF_UP)

def compute_boxes(rows, scheme="standard", is_ni_business=False) -> BoxTotals:
    box1 = box2 = box4 = Decimal(0)
    box6 = box7 = box8 = box9 = Decimal(0)

    for r in rows:
        gbp_net = r.net * r.fx_rate
        gbp_vat = r.vat_amount * r.fx_rate

        if r.source == "invoice":
            box6 += gbp_net
            if r.vat_treatment in ("standard", "reduced"):
                box1 += gbp_vat
            elif r.vat_treatment == "eu-goods" and is_ni_business:
                box8 += gbp_net
        else:
            box7 += gbp_net
            if r.vat_treatment in ("standard", "reduced"):
                box4 += gbp_vat
            elif r.vat_treatment == "reverse-charge":
                notional = gbp_net * (r.vat_rate / Decimal(100))
                box1 += notional
                box4 += notional
            elif r.vat_treatment == "postponed-import":
                notional = gbp_net * (r.vat_rate / Decimal(100))
                box1 += notional
                box4 += notional
            elif r.vat_treatment == "eu-goods" and is_ni_business:
                notional = gbp_net * (r.vat_rate / Decimal(100))
                box2 += notional
                box4 += notional
                box9 += gbp_net

    box3 = box1 + box2
    box5 = box3 - box4
    return BoxTotals(
        _q(box1), _q(box2), _q(box3), _q(box4), _q(box5),
        _q(box6), _q(box7), _q(box8), _q(box9),
    )

دو باتیں قابلِ غور ہیں۔ سب سے پہلے، ہر باکس کے کل کو ایک بار آخر میں مقدار میں شمار کیا جاتا ہے۔ فی قطار راؤنڈنگ لیک پینی اور HMRC ان ٹوٹل کے بارے میں ناقابل معافی ہیں جو آپس میں نہیں ملتے ہیں۔ دوسرا، انجن مکمل طور پر متعین ہے: ایک ہی ان پٹ، ایک ہی آؤٹ پٹ، ہر بار۔ یہ وہ پراپرٹی ہے جو مجھے اس کی یونٹ ٹیسٹ کرنے اور ڈرائی رن پر بھروسہ کرنے دیتی ہے۔

def test_simple_quarter():
    rows = [
        Row("invoice", net=Decimal("24500.00"), vat_amount=Decimal("4900.00"),
            vat_rate=Decimal("20"), vat_treatment="standard", fx_rate=Decimal(1), source="invoice"),
        Row("expense", net=Decimal("3000.00"), vat_amount=Decimal("600.00"),
            vat_rate=Decimal("20"), vat_treatment="standard", fx_rate=Decimal(1), source="expense"),
    ]
    t = compute_boxes(rows)
    assert t.box1 == Decimal("4900.00")
    assert t.box4 == Decimal("600.00")
    assert t.box5 == Decimal("4300.00")
    assert t.box6 == Decimal("24500.00")
    assert t.box7 == Decimal("3000.00")

اس کی جگہ کے ساتھ، ہر رجعت CI میں پکڑی جاتی ہے اس سے پہلے کہ یہ خشک چلنے والی رپورٹ کو چھوئے۔ کلاڈ مزید ٹیسٹ لکھنے میں میری مدد کر سکتا ہے۔ یہ ان ٹیسٹوں کو پاس کیے بغیر انجن کو تبدیل نہیں کر سکتا۔

8. ڈیمو ویڈیو

ذیل میں ایک سہ ماہی کے لیے حقیقی (گمنام) رسیدوں اور اخراجات کے ڈیٹا بیس کے خلاف اختتام سے آخر تک چلنے والی پائپ لائن کا ایک مختصر واک تھرو ہے: نارملائز، درجہ بندی، ڈرائی رن، پھر ایک سینڈ باکس MTD جمع کروانا۔ پورا لوپ چند منٹ کا ہے۔

9. HMRC MTD جمع کروانا

یہ وہ حصہ ہے جس پر سب سے زیادہ تحریریں چمکتی ہیں۔ MTD VAT API خود اچھی طرح سے دستاویزی اور مفت ہے، لیکن آپ کو کال کرنے سے پہلے تین چیزیں حاصل کرنے کی ضرورت ہے۔ POST returns.

OAuth2 اور ٹوکنز۔ HMRC ڈویلپر ہب میں درخواست رجسٹر کریں۔ آپ کو ایک کلائنٹ ID، ایک کلائنٹ سیکریٹ، اور ایک ری ڈائریکٹ URI ملتا ہے۔ یہ روانی PKCE کے ساتھ authorisation_code ہے: HMRC رضامندی والے صفحہ پر براؤزر کھولیں، صارف اپنے سرکاری گیٹ وے کی اسناد کے ساتھ لاگ ان ہوتا ہے اور آپ کی درخواست کو اپنے VAT رجسٹریشن نمبر (VRN) کے خلاف اجازت دیتا ہے، HMRC اجازت کوڈ کے ساتھ واپس بھیج دیتا ہے، آپ اسے رسائی ٹوکن + ریفریش ٹوکن کے بدلے تبدیل کرتے ہیں۔ انہیں ڈسک پر سمجھدار اجازتوں کے ساتھ کیش کریں۔ رسائی ٹوکن قلیل المدتی ہے۔ ریفریش ٹوکن بہت لمبا ہے۔

فراڈ سے بچاؤ کے ہیڈرز۔ HMRC کو ہر API کال پر اصل ڈیوائس کی شناخت کرنے والے HTTP ہیڈرز کے ایک دستاویزی سیٹ کی ضرورت ہوتی ہے: ٹائم زون، اسکرین جیومیٹری، صارف IDs، عوامی IP، MAC ایڈریسز، کلائنٹ کنکشن کا طریقہ، وغیرہ۔ درست فہرست اور فارمیٹ HMRC ڈویلپر دستاویزات میں ہیں (دیکھیں HMRC VAT نوٹس 700 اور متعلقہ مصنفین کے لیے مخصوص اصول)۔ انہیں غلط سمجھیں اور آپ کو ایک ملے گا۔ 403 ایک مبہم غلطی کے ساتھ۔ انہیں درست کریں اور کال گزر جائے۔ میں انہیں اندر رکھتا ہوں۔ fraud_headers.py اور ٹیسٹ میں اپنی موجودگی کو یقینی بنائیں۔

پہلے سینڈ باکس۔ HMRC پر ایک مفت سینڈ باکس فراہم کرتا ہے۔ test-api.service.hmrc.gov.uk stub VRNs اور stub واجبات کے ساتھ۔ سینڈ باکس کے خلاف اپنی پوری پائپ لائن کو اس وقت تک چلائیں جب تک کہ آپ جعلی ریٹرن جمع نہ کر لیں، جعلی رسید کی شناخت حاصل نہ کر لیں، اور اپنی ذمہ داریوں کی منتقلی کی تصدیق نہ کر دیں۔ تبھی آپ پلٹ جاتے ہیں۔ HMRC_ENV=live. میرا جمع کنندہ لائیو کال کرنے سے انکار کرتا ہے جب تک کہ ماحولیاتی متغیر سیٹ نہ ہو اور آپریٹر کی قسمیں نہ ہوں۔ SUBMIT فوری طور پر. زندہ رہنے کے لیے خود کار طریقے سے عمل درآمد کا کوئی راستہ نہیں ہے۔ ایک برا لائیو جمع کرانے کی قیمت ایک اور سینڈ باکس تکرار کی لاگت سے بہت زیادہ ہے۔

اصل خوش راہ کال مختصر ہے: GET obligations کے ساتھ status=O اوپن پیریڈ کو تلاش کرنے کے لیے، ڈرائی رن رپورٹ ڈسپلے کریں، آپریٹر کو تصدیق کرنے کا اشارہ کریں، پھر POST returns نو باکس نمبروں کے ساتھ، periodKey ذمہ داری سے، اور finalised: true. جواب کو محفوظ کریں، آڈٹ فولڈر میں رسید کی شناخت لکھیں، اور آپ کا کام ہو گیا۔

10. حفاظت، آڈٹ، اور تعمیل

تین اصول میں آگے نہیں بڑھوں گا۔ پہلے، کلاڈ ریاضی میں نہیں ہے۔. درجہ بندی کرنے والا علاج تجویز کرتا ہے اور LLM Python اور قواعد میں ترمیم کر سکتا ہے، لیکن باکس کا مجموعہ یونٹ ٹیسٹ کے ساتھ خالص فنکشن کے ذریعے تیار کیا جاتا ہے۔ "AI نے یہ کیا" MTD کے تحت دفاع نہیں ہے۔ دوسرا، ہر عرضی انسان کی طرف سے دی جاتی ہے۔. ڈرائی رن رپورٹ سائن آف کے لیے سچائی کا ذریعہ ہے۔ اگر میں درجہ بند قطاروں اور انجن کوڈ میں سے کسی نمبر کی وضاحت نہیں کر سکتا تو میں جمع نہیں کرتا۔ تیسرا، آڈٹ ٹریل صرف ضمیمہ ہے۔. ہر کلاسیفائیڈ JSON، ہر ڈرائی رن رپورٹ، ہر پرامپٹ، ہر فرق، اور مدت کے لیے حتمی HMRC رسید کی ID لکھی جاتی ہے۔ ./audit/<period>/ اور پرائیویٹ گٹ ریپو کے لیے پرعزم ہے۔ HMRC کو چھ سال کا ریکارڈ درکار ہے۔ میرے دستخط شدہ سنیپ شاٹس ہیں۔

میں دو اور طریقوں کی سفارش کروں گا یہاں تک کہ اگر آپ باقی کو نہیں اپناتے ہیں۔ سورس-ڈی بی کنکشن کو کم از کم مراعات یافتہ صرف پڑھنے کے کردار کے طور پر چلائیں: نہیں۔ UPDATE، نہیں DELETE، نہیں DROP. HMRC کلائنٹ کو خفیہ رکھیں اور اپنی ہوم ڈائرکٹری میں خفیہ مینیجر یا 0600 فائل کا استعمال کرتے ہوئے رسائی ٹوکنز کو ریپو سے باہر رکھیں۔ بات یہ ہے کہ حادثات کو صرف پالیسی سے نہیں بلکہ تعمیرات سے ناممکن بنانا ہے۔

11. ایج کیسز

VAT ایک ریگولیٹڈ ٹیکس ہے جس میں 1973 سے برطانیہ کی ہر حکومت نے ترمیم کی ہے، جس میں پوسٹ بریکسٹ اوورلے اور سب سے اوپر شمالی آئرلینڈ پروٹوکول ہے۔ کنارے کے معاملات حقیقی ہیں۔ میرا انجن ہینڈل کرنے والوں کی ایک غیر مکمل فہرست:

• بریگزٹ اور شمالی آئرلینڈ۔ برطانیہ کے کاروبار اب Box 8 یا Box 9 کو نہیں بھرتے ہیں۔ NI کاروبار اب بھی NI پروٹوکول کے تحت سامان (خدمات نہیں) کے لیے کرتے ہیں۔ انجن لیتا ہے۔ is_ni_business ایک پیرامیٹر کے طور پر اور اس کے مطابق شاخیں مستند اصول کے لیے HMRC VAT نوٹس 700 دیکھیں۔
• ریورس چارج۔ برطانیہ سے باہر کسی سپلائر سے خریدی گئی خدمات (اور کچھ گھریلو تعمیراتی صنعت کی خدمات) کا حساب الٹا چارج کے تحت لیا جاتا ہے: آپ Box 1 میں تصوراتی آؤٹ پٹ VAT شامل کرتے ہیں اور Box 4 میں اسی رقم کا دوبارہ دعوی کرتے ہیں۔ نقدی پر خالص اثر صفر ہے۔ واپسی پر خالص اثر دو خانے ہیں جو ایک ساتھ چلتے ہیں۔
• ملتوی درآمد VAT۔ برطانیہ کے باہر سے درآمد شدہ سامان کے لیے، آپ درآمد VAT کو سرحد پر ادائیگی کرنے کے بجائے اپنی اگلی واپسی تک موخر کر دیتے ہیں۔ علاج واپسی پر ریورس چارج کی طرح لگتا ہے۔
• جزوی چھوٹ۔ اگر آپ قابل ٹیکس اور مستثنیٰ دونوں سپلائیز بناتے ہیں، تو آپ صرف اس حد تک ان پٹ VAT کا دوبارہ دعویٰ کر سکتے ہیں جس کا ٹیکس قابل سپلائیز سے تعلق ہو۔ معیاری اور خصوصی طریقے ہیں؛ یہ وہ گوشہ ہے جسے اکثر اکاؤنٹنٹ کی ضرورت ہوتی ہے۔ مارک ڈاؤن فائل میں جزوی استثنیٰ کے قواعد کو انکوڈ کرنے کی کوشش نہ کریں۔
• فلیٹ ریٹ اسکیم۔ آپ معیاری شرح پر VAT وصول کرتے ہیں لیکن مجموعی کاروبار کا ایک مقررہ فیصد HMRC ادا کرتے ہیں، اور آپ عام طور پر ان پٹ VAT کا دوبارہ دعوی نہیں کر سکتے۔ اس کے لیے انجن کی ایک الگ شاخ ہے اور فی قطار کی زیادہ تر درجہ بندی کو نظر انداز کرتا ہے۔
• ملٹی کرنسی انوائسز۔ ہر قطار کو متعلقہ تاریخ پر لاگو شرح پر GBP میں تبدیل کریں۔ HMRC ماہانہ اوسط شرحیں شائع کریں؛ آپ اسپاٹ ریٹ بھی استعمال کر سکتے ہیں۔ مستقل مزاج رہیں۔ دی fx_rate_to_gbp کالم فی قطار لاگو ہونے والی اصل شرح کو اسٹور کرتا ہے۔
• کریڈٹ نوٹ۔ کریڈٹ نوٹ ایک منفی رسید ہے۔ یہ Box 1 اور Box 6 (یا Box 4 اور Box 7 کو کم کرتا ہے اگر یہ خریداری کا کریڈٹ ہے)۔ یقینی بنائیں کہ آپ کی net_amount اور vat_amount منفی جا سکتا ہے اور یہ کہ انجن ان کو صحیح طریقے سے جمع کرتا ہے۔
• ڈپازٹس اور اسٹیج کی ادائیگی۔ ٹیکس پوائنٹ اس وقت ہو سکتا ہے جب ڈپازٹ موصول ہو، نہ کہ جب حتمی رسید جاری کی جائے۔ کیش اکاؤنٹنگ اس کو آسان بنا سکتی ہے۔
• وسط سہ ماہی کی شرح میں تبدیلی۔ تاریخی طور پر نایاب، لیکن ممکن ہے۔ فی قطار کی شرح کو ذخیرہ کریں، عالمی مستقل کے طور پر نہیں۔

12. لاگت

ایماندار نمبر۔ وقت کی تعمیر توجہ مرکوز شام کے بارے میں ایک ہفتہ تھا - اسے 25 سے 30 گھنٹے کہتے ہیں۔ اس میں سے زیادہ تر اسکیما نارملائزیشن، درجہ بندی کے اصول، اور انجن ٹیسٹ لکھنا تھا۔ HMRC OAuth ڈانس دوسرا سب سے بڑا حصہ تھا۔ چلتی لاگت فی سہ ماہی چھوٹا ہے: میری موجودہ Claude Code سبسکرپشن (دوسرے سافٹ ویئر کے کام کے لیے پہلے سے ادا کی گئی ہے)، کلاسیفائر ٹوکن کے استعمال میں چند پیسے، اور HMRC API کے لیے صفر پاؤنڈ۔ انجن اور آڈٹ لاگ مقامی طور پر میرے میک پر چلتے ہیں۔ جائزہ لینے کا وقت فی سہ ماہی تقریباً ایک گھنٹہ ہے، زیادہ تر میرے اکاؤنٹنٹ کے ساتھ ڈرائی رن پڑھنے میں گزرا۔ اس کا موازنہ پرانے ورک فلو کے تحت تقریباً آدھے دن کے اسپریڈشیٹ سے کریں اور بچایا ہوا وقت پہلے سال کے اندر تعمیراتی لاگت واپس کر دیتا ہے۔

اگر آپ نے اس کی قیمت ایک پروجیکٹ کے طور پر رکھی ہے جس کی تعمیر کے لیے آپ کسی اور کو ادائیگی کر رہے ہیں، تو آپ کنسلٹنسی کی شرحوں پر چار عدد بال پارک میں ہوں گے - یہی وجہ ہے کہ بیس سے پچاس پاؤنڈ ماہانہ میں پیک کیا ہوا SaaS زیادہ تر کاروباروں کے لیے تقریباً ہمیشہ ہی صحیح جواب ہوتا ہے۔ دلچسپ سوال یہ نہیں ہے کہ "کیا یہ Xero سے سستا ہے؟" - یہ عام طور پر نہیں ہے - لیکن "کیا یہ زیادہ درست، زیادہ قابل سماعت، اور میرے لیے استدلال کرنا آسان ہے؟"۔ میرے لیے جواب ہاں میں ہے۔

13. آگے کیا ہے، اور نتیجہ

اگلے ٹکڑے جو میں شامل کرنا چاہتا ہوں وہ ہیں: خودکار بینک فیڈ امپورٹ (اوپن بینکنگ AISP)، سپلائر پی ڈی ایف کے لیے OCR تاکہ رسید کا یو آر ایل ایک حقیقی اسکین لائن بن جائے، ایک طے شدہ cron + Slack منظوری کا بہاؤ اس لیے مجھے آخری تاریخوں کو یاد رکھنے کی ضرورت نہیں ہے، اور مارکیٹ پلیس بیچنے والوں کے لیے خود بلنگ کی توسیع۔ ان میں سے کوئی بھی پائپ لائن کی بنیادی شکل کو تبدیل نہیں کرتا ہے۔ وہ سب ایک ہی پانچ لین ڈایاگرام پر سجاوٹ ہیں۔

کم از کم میرے لیے سب سے بڑا سبق یہ ہے کہ ایک چھوٹا Claude Code پروجیکٹ ایک ریگولیٹڈ ورک فلو کے بورنگ نصف کو کتنی اچھی طرح سے ہینڈل کرتا ہے۔ بورنگ نصف زیادہ تر کام ہے: اسکیما نارملائزیشن، CSV امپورٹرز، مصالحتی رپورٹس، فکسچر، ایج کیس رولز، آڈٹ لاگنگ۔ کلاڈ اس سب میں بہترین ہے۔ تعییناتی نصف - اصل ریاضی، اصل جمع کرانا - یونٹ ٹیسٹ اور انسانی منظوری کے دروازے کے ساتھ سادہ ازگر میں رہتا ہے، بالکل وہیں جہاں اس کا تعلق ہے۔

دستبرداری، دوبارہ۔ یہ مضمون ٹیکس کا مشورہ نہیں ہے۔ اس سے پہلے کہ آپ کسی حقیقی HMRC اکاؤنٹ پر اس طرح کی کسی چیز کی نشاندہی کریں، اپنی پہلی واپسی کے اختتام سے آخر تک جائزہ لینے کے لیے برطانیہ میں رجسٹرڈ اکاؤنٹنٹ سے رجوع کریں۔ HMRC MTD سینڈ باکس کے خلاف چلائیں جب تک کہ آپ اور آپ کا اکاؤنٹنٹ دونوں پر اعتماد نہ ہوں۔ کسی مخصوص VAT علاج پر مستند اصول کے لیے، HMRC VAT نوٹس 700 اور متعلقہ نوٹس gov.uk ویب سائٹ پر دیکھیں۔ اگر آپ ان سب کا مختصر ورژن چاہتے ہیں۔ ساتھی بلاگ پوسٹ پانچ منٹ کا پڑھنا ہے؛ بصورت دیگر، سبسکرائب کریں اور میں اسٹیک کے پختہ ہونے پر لکھتا رہوں گا۔

اس مضمون کے لیے SEO سنیپ شاٹ

• SEO عنوان: Claude Code کے ساتھ VAT ریٹرن سسٹم بنائیں
• میٹا تفصیل: اپنے انوائسز اور اخراجات DB کو پڑھنے کے لیے Claude Code کا استعمال کریں، VAT کی درجہ بندی کریں، HMRC Box 1 سے 9 تک کی گنتی کریں، ڈرائی رن، پھر MTD کو جمع کرائیں - ڈیٹرمنسٹک انجن، انسانی منظوری۔
• بنیادی مطلوبہ الفاظ: claude-code, vat, hmrc, mtd, اکاؤنٹنگ, آٹومیشن, python, ai-agent, Finops, small-business
• ٹویٹر / ایکس (280 حروف سے کم): میری UK VAT ریٹرن کو Claude Code پروجیکٹ کے طور پر دوبارہ بنایا: Postgres انوائسز + اخراجات DB سے HMRC Box 1 سے 9 تک، ڈیٹرمنسٹک Python انجن، سینڈ باکس-پہلا MTD جمع کروائیں، انسانی منظوری کا دروازہ۔ مکمل تحریر + ورک فلو SVG + ڈیمو ویڈیو۔ ٹیکس کا مشورہ نہیں۔ #ClaudeCode #VAT #HMRC #MTD
• لنکڈ ان پوسٹ: میں نے اس سال اپنی سہ ماہی UK VAT واپسی کو ایک چھوٹے Claude Code پروجیکٹ کے طور پر دوبارہ بنایا ہے۔ یہ میرے انوائسز اور اخراجات کے ڈیٹا بیس کو صرف پڑھنے کے لیے پڑھتا ہے، ایک دستاویزی قواعد کی فائل کا استعمال کرتے ہوئے VAT ٹریٹمنٹ کے ذریعے ہر لائن کی درجہ بندی کرتا ہے، HMRC Box 1 سے 9 تک ایک ڈیٹرمنسٹک Python انجن کے ساتھ شمار کرتا ہے (ریاضی میں کوئی LLM نہیں)، اور صرف میرے سائن آف کرنے کے بعد یہ HMRC، HMRC-XPR-XPR-XPR-XPR-7 ہیڈز کے ذریعے جمع کرتا ہے۔ مکمل OAuth2 بہاؤ۔ پوری سہ ماہی میں اب تقریباً ایک گھنٹہ لگتا ہے۔ پرامپٹس، اسکیما، انجن کوڈ، ایج کیسز، اور ایماندارانہ لاگت کی کہانی کے ساتھ مکمل تحریر Workstation پر ہے۔ ٹیکس مشورہ نہیں؛ اپنی پہلی واپسی کا جائزہ لینے کے لیے اکاؤنٹنٹ حاصل کریں۔