आपके चालान और व्यय डेटाबेस से Claude Code के साथ एक VAT रिटर्न सिस्टम बनाना

यह दीर्घ-रूप वाला डीप-डाइव है। त्वरित, स्किम-पठनीय संस्करण के लिए, देखें साथी ब्लॉग पोस्ट.

1. मैंने इसे क्यों बनाया?

VAT-पंजीकरण सीमा से अधिक करयोग्य टर्नओवर वाले प्रत्येक यूके छोटे व्यवसाय को HMRC की Making Tax Digital (MTD) सेवा के माध्यम से VAT रिटर्न की गणना और जमा करना होता है - आमतौर पर त्रैमासिक। नौ क्रमांकित बक्से. आउटपुट VAT माइनस इनपुट VAT। शुद्ध राशि का भुगतान करें, या धनवापसी का दावा करें। सिद्धांत रूप में आसान; व्यवहार में दंड तब मिलता है जब आपके चालान Postgres में रहते हैं, आपकी व्यय रसीदें बीस अलग-अलग आपूर्तिकर्ताओं से पीडीएफ हैं, आपके बैंक विवरण वाइज और रिवोल्यूट से सीएसवी हैं, और आपकी विदेशी मुद्रा लाइनों को सही मासिक दर पर पाउंड में फिर से बताया जाना है।

कुछ वर्षों तक मैं एक विशाल स्प्रेडशीट, एक कैलेंडर अनुस्मारक और विश्वास की एक छोटी छलांग के साथ उलझा रहा। प्रत्येक तिमाही में लगभग आधा दिन लगा, जिसमें से अधिकांश डेटा गड़बड़ी थी - इनवॉइस डीबी से एक सीएसवी निर्यात करें, एक्सेल में पेस्ट करें, कुछ सौ पंक्तियों को हाथ से वर्गीकृत करें, सूत्रों की दोबारा जांच करें, नौ नंबरों को तीसरे पक्ष के MTD ब्रिज में कॉपी करें, सबमिट पर क्लिक करें। ऑडिट ट्रेल था "मुझ पर भरोसा करें, मेरे पास एक स्प्रेडशीट थी"। मध्य-तिमाही दर परिवर्तन ने इसे तोड़ दिया। रसीदें गायब हो गईं. एक ग़लत वर्गीकरण धक्का दे सकता है Box 5 सैकड़ों पाउंड की छूट.

मैंने इस वर्ष एक छोटी पाइपलाइन का पुनर्निर्माण किया Claude Code प्रोजेक्ट जो सीधे मेरे चालान और व्यय डेटाबेस से बात करता है, प्रत्येक पंक्ति को वर्गीकृत करता है, एक नियतात्मक पायथन इंजन के साथ 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 यूरोपीय संघ के सदस्य देशों (केवल NI) से अधिग्रहण का कुल मूल्य है। योजना के विभिन्न रूप हैं - फ्लैट-रेट योजना, नकद लेखांकन, वार्षिक लेखांकन - जो बदलते हैं कैसे आप संख्याओं पर तो पहुँचते हैं लेकिन बॉक्स के आकार पर नहीं।

अस्वीकरण. मैं एक सॉफ्टवेयर इंजीनियर हूं, चार्टर्ड अकाउंटेंट नहीं। यह लेख है कर सलाह नहीं. VAT वर्गीकरण के सटीक नियम, आंशिक छूट, फ्लैट-रेट योजना, डिजिटल सेवाओं के लिए आपूर्ति के स्थान के नियम, EU वस्तुओं और सेवाओं के ब्रेक्सिट के बाद के व्यवहार और NI प्रोटोकॉल सभी समय के साथ बदलते हैं और आपकी विशिष्ट परिस्थितियों पर निर्भर करते हैं। इससे पहले कि आप वास्तविक HMRC खाते के विरुद्ध ऐसा कुछ भी चलाएँ, यूके-पंजीकृत अकाउंटेंट से अपने पहले रिटर्न की शुरू से अंत तक समीक्षा करवाएँ। किसी विशिष्ट किनारे के मामले पर आधिकारिक नियम के लिए, HMRC VAT नोटिस 700 और gov.uk वेबसाइट पर संबंधित नोटिस देखें। आपके अकाउंटेंट के एक घंटे के समय की लागत खराब सबमिशन की लागत से बहुत कम है।

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 नहीं)

अधिकांश यूके छोटे व्यवसायों के लिए उत्तर है - वास्तव में - पैकेज्ड सॉफ़्टवेयर का उपयोग करें। ज़ीरो, क्विकबुक, फ्रीएजेंट, सेज सभी के पास HMRC-प्रमाणित MTD सबमिशन, अच्छे यूआई और अकाउंटेंट हैं जो उन्हें पहले से जानते हैं। जब तक आपके पास कोई स्पष्ट कारण न हो, आपको अपना स्वयं का VAT सिस्टम शुरू नहीं करना चाहिए।

मेरे कारण संकीर्ण लेकिन वास्तविक थे। मैं पहले से ही सॉफ्टवेयर कार्य के लिए हर दिन Claude Code का उपयोग करता हूं, इसलिए VAT के लिए भी इसका उपयोग करने का सीमांत प्रयास छोटा था। मेरे चालान डीबी मेरी अपनी मशीन पर रहते हैं; मैं पसंद करता हूं कि इसे SaaS किरायेदार में प्रतिबिंबित न किया जाए। मेरा आपूर्तिकर्ता मिश्रण अजीब है (रिवर्स चार्ज के साथ ईयू सेवाएं, स्थगित आयात VAT, कभी-कभी शून्य-रेटेड किनारे के मामले) और एक मार्कडाउन फ़ाइल के साथ-साथ एक पायथन मॉड्यूल में नियमों को एन्कोड करना उन्हें संभालने के लिए SaaS को कॉन्फ़िगर करने की तुलना में तेज़ निकला। और ऑडिट ट्रेल जो मुझे गिट रेपो से मिलता है - प्रत्येक क्लासिफायर प्रॉम्प्ट, प्रत्येक अंतर, प्रत्येक हस्ताक्षरित अवधि स्नैपशॉट - बिल्कुल वही ऑडिट ट्रेल है जो मैं चाहता हूं।

Claude Code तीन कारणों से इसके लिए उपयुक्त है। सबसे पहले, यह सीधे डिस्क पर एक प्रोजेक्ट के विरुद्ध काम करता है: यह मेरी स्कीमा, पूर्व-तिमाही ड्राई-रन रिपोर्ट, नियम फ़ाइल और पायथन इंजन को पढ़ सकता है, और संदर्भ में संपादन प्रस्तावित कर सकता है। दूसरा, यह उबाऊ मचान में अच्छा है - माइग्रेशन स्क्रिप्ट, सीएसवी आयातक, सुलह रिपोर्ट, पाइटेस्ट फिक्स्चर। तीसरा, जब यह किसी पंक्ति को वर्गीकृत करता है, तो यह स्पष्ट अंग्रेजी में अपना तर्क बताता है, जो कि मैं रिटर्न पर हस्ताक्षर करने से पहले समीक्षा करना चाहता हूं। नीचे दिए गए वर्कफ़्लो आरेख के निचले भाग में निर्णय मैट्रिक्स इस ट्रेड-ऑफ़ का ईमानदार संस्करण है।

5. वास्तुकला और कार्यप्रवाह

पाइपलाइन में पांच स्विम लेन हैं। स्रोत चालान और व्यय तालिकाओं तक केवल पढ़ने के लिए पहुंच है और साथ ही स्ट्राइप, वाइज और बैंक फ़ीड से सीएसवी के लिए एक ड्रॉप फ़ोल्डर भी है। निगलना + सामान्य बनाना एक छोटी क्लाउड-जनरेटेड पायथन स्क्रिप्ट है जो प्रत्येक स्रोत स्कीमा को एक कैनोनिकल दृश्य में मैप करती है, विदेशी मुद्रा को HMRC मासिक दर पर GBP में परिवर्तित करती है, एक दिनांक-सीमा फ़िल्टर लागू करती है, और प्रत्येक पंक्ति पर एक इडेम्पोटेंट के साथ मुहर लगाती है। run_key इसलिए दोबारा चलाना सुरक्षित है। वर्गीकृत करें + सामंजस्य स्थापित करें Claude Code क्लासिफायरियर है: यह प्रत्येक विहित पंक्ति पर चलता है, एक चुनता है vat_treatment नियमों का उपयोग करके प्रलेखित एनम से vat-rules.md, भुगतान के विरुद्ध चालान का समाधान करता है, और विसंगतियों (नकारात्मक नेट, लापता आपूर्तिकर्ता VAT नंबर, देश-कोड बेमेल, आपूर्तिकर्ता जो VAT-पंजीकृत होना चाहिए लेकिन नहीं हैं) को चिह्नित करता है। VAT इंजन एक शुद्ध पायथन मॉड्यूल है जो वर्गीकृत पंक्तियों को पढ़ता है और निश्चित रूप से 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, तैरना नहीं. एक डॉकस्ट्रिंग और एक शामिल करें __main__ ब्लॉक करें जो सारांश प्रिंट करता है।"

क्लाउड ने एक साफ़ मॉड्यूल लौटाया Decimal, पैरामीटरयुक्त SQL, a build_run_key() वह हैश (पीरियड_स्टार्ट, पीरियड_एंड, स्कीम, स्कीमा_वर्जन) एक स्थिर हेक्स स्ट्रिंग और एक क्लिक-आधारित सीएलआई में। मैंने दो फ़ील्ड नाम संपादित किए और बाकी स्वीकार कर लिए।

संकेत 2 - वर्गीकारक. "पढ़ना vat-rules.md और लिखा classify.py. से प्रत्येक विहित पंक्ति के लिए normalise.py, तय करना vat_treatment इनमें से एक को: मानक, कम किया हुआ, शून्य, मुक्त करें, बाहर का दायरा, रिवर्स-चार्ज, ईयू-माल, ईयू-सेवाएँ, स्थगित-आयात. यदि पंक्ति में पहले से ही एक गैर-रिक्त है 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 प्राधिकरण_कोड प्रवाह का उपयोग करें। से एक्सेस टोकन पढ़ें ~/.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 इंजन

इंजन जानबूझकर उबाऊ हिस्सा है. यह यूनिट परीक्षणों और बिना एआई के एक शुद्ध फ़ंक्शन है। यह वास्तविक आकार है:

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")

इसके साथ, प्रत्येक प्रतिगमन को ड्राई-रन रिपोर्ट को छूने से पहले सीआई में पकड़ लिया जाता है। क्लाउड मुझे और अधिक परीक्षण लिखने में मदद कर सकता है; यह उन परीक्षणों को पारित किए बिना इंजन नहीं बदल सकता।

8. डेमो वीडियो

नीचे एक तिमाही के लिए वास्तविक (अनाम) चालान और व्यय डेटाबेस के विरुद्ध शुरू से अंत तक चलने वाली पाइपलाइन का एक छोटा सा पूर्वाभ्यास दिया गया है: सामान्यीकरण, वर्गीकृत, ड्राई-रन, फिर एक सैंडबॉक्स MTD सबमिशन। पूरा लूप कुछ मिनटों का है।

9. HMRC MTD सबमिशन

यह वह हिस्सा है जिस पर अधिकतर लेख प्रकाश डालते हैं। MTD VAT POST returns.

OAuth2 और टोकन। HMRC डेवलपर हब में एक एप्लिकेशन पंजीकृत करें; आपको एक क्लाइंट आईडी, एक क्लाइंट सीक्रेट और एक रीडायरेक्ट यूआरआई मिलता है। प्रवाह PKCE के साथ प्राधिकरण_कोड है: ब्राउज़र को HMRC सहमति पृष्ठ पर खोलें, उपयोगकर्ता अपने सरकारी गेटवे क्रेडेंशियल्स के साथ लॉग इन करता है और आपके आवेदन को उनके VAT पंजीकरण संख्या (VRN) के विरुद्ध अधिकृत करता है, HMRC एक प्राधिकरण कोड के साथ वापस रीडायरेक्ट करता है, आप इसे एक्सेस टोकन + रीफ्रेश टोकन के लिए एक्सचेंज करते हैं। डिस्क पर समझदार अनुमतियों के साथ उन्हें कैश करें। एक्सेस टोकन अल्पकालिक है; ताज़ा टोकन बहुत लंबा है.

धोखाधड़ी-रोकथाम शीर्षलेख. HMRC को प्रत्येक API कॉल पर मूल डिवाइस की पहचान करने वाले HTTP हेडर के एक दस्तावेजी सेट की आवश्यकता होती है: समय क्षेत्र, स्क्रीन ज्यामिति, उपयोगकर्ता आईडी, सार्वजनिक आईपी, मैक पते, क्लाइंट कनेक्शन विधि, आदि। सटीक सूची और प्रारूप HMRC डेवलपर दस्तावेज़ में हैं (HMRC VAT नोटिस 700 और आधिकारिक नियम के लिए संबंधित धोखाधड़ी-रोकथाम विनिर्देश देखें)। उन्हें गलत समझें और आपको एक मिलेगा 403 एक अस्पष्ट त्रुटि के साथ. उन्हें ठीक कर लें और कॉल शुरू हो जाएगी। मैं उन्हें अंदर रखता हूं fraud_headers.py और परीक्षणों में अपनी उपस्थिति का दावा करते हैं।

पहले सैंडबॉक्स. HMRC एक निःशुल्क सैंडबॉक्स प्रदान करता है test-api.service.hmrc.gov.uk स्टब वीआरएन और स्टब दायित्वों के साथ। अपनी पूरी पाइपलाइन को सैंडबॉक्स के विरुद्ध शुरू से अंत तक चलाएं जब तक कि आपने एक नकली रिटर्न जमा नहीं कर दिया हो, एक नकली रसीद आईडी प्राप्त नहीं कर ली हो, और अपने दायित्वों की पुष्टि नहीं कर ली हो। तभी तुम पलटते हो HMRC_ENV=live. जब तक पर्यावरण चर सेट नहीं किया जाता है और ऑपरेटर टाइप नहीं किया जाता है, तब तक मेरा सबमिटर लाइव कॉल करने से इंकार कर देता है SUBMIT संकेत पर. जीने के लिए कोई स्वचालित निष्पादन पथ नहीं है। एक ख़राब लाइव सबमिशन की लागत एक और सैंडबॉक्स पुनरावृत्ति की लागत से बहुत अधिक है।

वास्तविक हैप्पी-पाथ कॉल संक्षिप्त है: GET obligations साथ status=O खुली अवधि का पता लगाने के लिए, ड्राई-रन रिपोर्ट प्रदर्शित करें, फिर ऑपरेटर को पुष्टि करने के लिए कहें POST returns नौ बॉक्स नंबरों के साथ, periodKey दायित्व से, और finalised: true. प्रतिक्रिया सहेजें, ऑडिट फ़ोल्डर में रसीद आईडी लिखें, और आपका काम हो गया।

10. सुरक्षा, लेखापरीक्षा और अनुपालन

तीन नियम जिनसे मैं आगे नहीं बढ़ूंगा. पहला, क्लाउड अंकगणित में नहीं है. क्लासिफायरियर उपचार का सुझाव देता है और LLM पायथन और नियमों को संपादित कर सकता है, लेकिन बॉक्स योग यूनिट परीक्षणों के साथ एक शुद्ध फ़ंक्शन द्वारा निर्मित होते हैं। MTD के तहत "एआई ने यह किया" कोई बचाव नहीं है। दूसरा, प्रत्येक समर्पण एक मानव द्वारा निर्धारित है. ड्राई-रन रिपोर्ट साइन-ऑफ़ के लिए सत्य का स्रोत है। यदि मैं वर्गीकृत पंक्तियों और इंजन कोड से किसी संख्या की व्याख्या नहीं कर सकता, तो मैं प्रस्तुत नहीं करता। तीसरा, ऑडिट ट्रेल केवल परिशिष्ट है. प्रत्येक वर्गीकृत JSON, प्रत्येक ड्राई-रन रिपोर्ट, प्रत्येक संकेत, प्रत्येक अंतर और अवधि के लिए अंतिम HMRC रसीद आईडी को लिखा जाता है ./audit/<period>/ और एक निजी गिट रेपो के लिए प्रतिबद्ध है। HMRC के लिए छह साल के रिकॉर्ड की आवश्यकता होती है; मेरे हस्ताक्षरित स्नैपशॉट हैं।

दो और प्रथाएँ मैं सुझाऊँगा भले ही आप बाकी को न अपनाएँ। स्रोत-डीबी कनेक्शन को कम-से-कम-विशेषाधिकार वाली केवल पढ़ने योग्य भूमिका के रूप में चलाएँ: नहीं UPDATE, नहीं DELETE, नहीं DROP. अपने होम डायरेक्टरी में एक गुप्त प्रबंधक या 0600 फ़ाइल का उपयोग करके HMRC क्लाइंट को गुप्त रखें और एक्सेस टोकन को रेपो से बाहर रखें। मुद्दा सिर्फ नीति से नहीं, बल्कि निर्माण से दुर्घटनाओं को असंभव बनाने का है।

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 अधिकांश व्यवसायों के लिए लगभग हमेशा सही उत्तर होता है। दिलचस्प सवाल यह नहीं है कि "क्या यह ज़ीरो से सस्ता है?" - यह आमतौर पर नहीं है - लेकिन "क्या यह अधिक सटीक, अधिक सुनने योग्य और मेरे लिए इसके बारे में तर्क करना आसान है?" मेरे लिए इसका उत्तर हां है.

13. आगे क्या है और निष्कर्ष क्या है

अगले टुकड़े जो मैं जोड़ना चाहता हूं वे हैं: स्वचालित बैंक-फ़ीड आयात (ओपन बैंकिंग एआईएसपी), आपूर्तिकर्ता पीडीएफ के लिए ओसीआर ताकि रसीद यूआरएल एक वास्तविक स्कैन की गई लाइन बन जाए, एक निर्धारित क्रॉन + स्लैक अनुमोदन प्रवाह ताकि मुझे समय सीमा याद न रहे, और बाज़ार विक्रेताओं के लिए एक स्व-बिलिंग एक्सटेंशन। इनमें से कोई भी पाइपलाइन के मूल आकार को नहीं बदलता है। वे सभी एक ही पांच-लेन आरेख पर सजावट हैं।

कम से कम मेरे लिए बड़ा सबक यह है कि एक छोटा Claude Code प्रोजेक्ट एक विनियमित वर्कफ़्लो के उबाऊ आधे हिस्से को कितनी अच्छी तरह संभालता है। अधिकांश काम उबाऊ हिस्सा है: स्कीमा सामान्यीकरण, सीएसवी आयातक, समाधान रिपोर्ट, फिक्स्चर, एज-केस नियम, ऑडिट लॉगिंग। क्लाउड इन सबमें उत्कृष्ट है। नियतात्मक आधा - वास्तविक गणित, वास्तविक सबमिशन - यूनिट परीक्षणों और एक मानव अनुमोदन गेट के साथ सादे पायथन में रहता है, ठीक वहीं जहां यह होता है।

अस्वीकरण, फिर से. यह लेख कर संबंधी सलाह नहीं है. इससे पहले कि आप वास्तविक HMRC खाते पर ऐसा कुछ इंगित करें, यूके-पंजीकृत अकाउंटेंट से अपने पहले रिटर्न की शुरू से अंत तक समीक्षा करवाएं। HMRC MTD सैंडबॉक्स के विरुद्ध तब तक दौड़ें जब तक आप और आपका अकाउंटेंट दोनों आश्वस्त न हो जाएं। किसी विशिष्ट VAT उपचार पर आधिकारिक नियम के लिए, HMRC VAT नोटिस 700 और gov.uk वेबसाइट पर संबंधित नोटिस देखें। यदि आप इन सबका संक्षिप्त संस्करण चाहेंगे, तो साथी ब्लॉग पोस्ट पाँच मिनट का पाठ है; अन्यथा, सदस्यता लें और स्टैक परिपक्व होने पर मैं लिखना जारी रखूंगा।

इस आलेख के लिए SEO स्नैपशॉट

• एसईओ शीर्षक: Claude Code के साथ एक VAT रिटर्न सिस्टम बनाएं
• मेटा विवरण: अपने चालान और व्यय DB को पढ़ने के लिए Claude Code का उपयोग करें, VAT को वर्गीकृत करें, HMRC Box 1 की गणना 9 तक करें, ड्राई-रन करें, फिर MTD को सबमिट करें - नियतात्मक इंजन, मानव अनुमोदन।
• प्राथमिक कीवर्ड: क्लाउड-कोड, वैट, एचएमआरसी, एमटीडी, अकाउंटिंग, ऑटोमेशन, पायथन, एआई-एजेंट, फिनॉप्स, लघु-व्यवसाय
• ट्विटर/एक्स (280 अक्षरों से कम): मेरे यूके VAT रिटर्न को Claude Code प्रोजेक्ट के रूप में फिर से बनाया गया: Postgres चालान + व्यय DB से HMRC Box 1 से 9, नियतात्मक पायथन इंजन, सैंडबॉक्स-प्रथम MTD सबमिट, मानव अनुमोदन गेट। पूर्ण लेखन + वर्कफ़्लो एसवीजी + डेमो वीडियो। कर सलाह नहीं. #क्लाउडकोड #VAT #HMRC #MTD
• लिंक्डइन पोस्ट: मैंने इस वर्ष एक छोटे Claude Code प्रोजेक्ट के रूप में अपने त्रैमासिक यूके VAT रिटर्न का पुनर्निर्माण किया। यह मेरे चालान और व्यय डेटाबेस को केवल पढ़ने के लिए पढ़ता है, एक दस्तावेजी नियम फ़ाइल का उपयोग करके VAT उपचार द्वारा प्रत्येक पंक्ति को वर्गीकृत करता है, एक नियतात्मक पायथन इंजन (अंकगणित में कोई LLM नहीं) के साथ HMRC Box 1 की गणना करता है, और ड्राई-रन पर हस्ताक्षर करने के बाद ही यह HMRC MTD API - सैंडबॉक्स पहले, धोखाधड़ी-रोकथाम हेडर, पूर्ण OAuth2 प्रवाह के माध्यम से सबमिट करता है। पूरी तिमाही में अब लगभग एक घंटा लगता है। संकेतों, स्कीमा, इंजन कोड, एज केस और ईमानदार लागत कहानी के साथ पूरा लेख Workstation पर है। कर सलाह नहीं; अपने पहले रिटर्न की समीक्षा करने के लिए एक एकाउंटेंट से पूछें।