ब्लॉग
आपके चालान और व्यय डेटाबेस से Claude Code के साथ एक VAT रिटर्न सिस्टम बनाना
मैं कैसे एक Postgres चालान तालिका और आपूर्तिकर्ता PDF के एक फ़ोल्डर से HMRC
इस पृष्ठ पर
एक छोटा, स्किम-पठनीय साथी। कोड, प्रॉम्प्ट, स्कीमा, एक HMRC लंबा लेख.
त्रैमासिक VAT मेरे महीने का सबसे खराब हिस्सा था
प्रत्येक तिमाही में, यूके के छोटे व्यवसाय को एक VAT रिटर्न तैयार करना होता है: संख्याओं के नौ बक्से (बिक्री, खरीद, VAT देय, VAT पुनः प्राप्त करने योग्य, EU सामान, यदि आप उत्तरी आयरलैंड में हैं, कुल, शुद्ध) और उन्हें HMRC Making Tax Digital (MTD) के माध्यम से जमा करें। वर्षों तक, मेरा इस तरह दिखता था: Postgres में इनवॉइस तालिका खोलें, एक CSV निर्यात करें, इसे एक्सेल में पेस्ट करें, कुछ सौ पंक्तियों को हाथ से वर्गीकृत करें, सूत्र चलाएं, नौ नंबरों को तीसरे पक्ष के MTD ब्रिज में कॉपी करें, सबमिट पर क्लिक करें, आशा है।
इसने काम किया, लेकिन यह धीमा और नुकसानदेह था। रसीदें गायब हो गईं. मध्य-तिमाही दर परिवर्तन ने सूत्रों को तोड़ दिया। एक VAT वर्गीकरण में कोई त्रुटि हो सकती है Box 5 सैकड़ों पाउंड से. और ऑडिट ट्रेल था "मुझ पर विश्वास करो, मेरे पास एक स्प्रेडशीट थी"।
इस वर्ष मैंने एक छोटे Claude Code प्रोजेक्ट के रूप में पूरी चीज़ का पुनर्निर्माण किया जो मेरे चालान + व्यय DB को पढ़ता है, प्रत्येक पंक्ति को वर्गीकृत करता है, नौ बक्से की गणना करता है, एक पीडीएफ को ड्राई-रन करता है, और उसके बाद ही HMRC MTD को सबमिट करता है - एक मानव अनुमोदन गेट के साथ। यह ब्लॉग लघु संस्करण है. लंबे लेख में संकेत, पायथन, HMRC OAuth प्रवाह और गेटचास हैं।
वॉकथ्रू देखें
वास्तविक (अनाम) चालान + व्यय डीबी के विरुद्ध शुरू से अंत तक चलने वाली VAT रिटर्न पाइपलाइन का एक छोटा सा पूर्वाभ्यास।
पांच चरणों वाली पाइपलाइन
- जोड़ना। Claude Code को मिलता है केवल पढ़ने के लिए मेरे चालान और व्यय तालिकाओं से डीबी कनेक्शन। इसमें स्रोत डेटा तक कभी भी लिखने की पहुंच नहीं होती है। स्ट्राइप, वाइज, रिवोल्यूट और कुछ बैंक फ़ीड से सीएसवी डाले गए हैं
./imports/. - सामान्यीकरण. क्लाउड एक छोटी पायथन स्क्रिप्ट तैयार करता है और चलाता है जो प्रत्येक स्रोत स्कीमा को एक कैनोनिकल दृश्य में मैप करता है:
id, date, supplier_or_customer, gross, net, vat_amount, vat_rate, vat_treatment, country_code, currency, source, run_key. HMRC मासिक दर का उपयोग करके विदेशी मुद्रा को GBP में परिवर्तित किया जाता है। पूरी अवधि एक निष्क्रिय व्यक्ति द्वारा संचालित होती हैrun_keyइसलिए पुनः चलाना सुरक्षित है। - वर्गीकृत करें + सामंजस्य स्थापित करें। क्लाउड प्रत्येक पंक्ति को VAT उपचार में वर्गीकृत करता है - मानक 20%, कम 5%, शून्य, छूट, दायरे से बाहर, रिवर्स-चार्ज, EU सामान, EU सेवाएँ, स्थगित आयात VAT - एक छोटे का उपयोग करके
vat-rules.mdमैं रेपो में रखता हूँ. यह भुगतान और फ़्लैग विसंगतियों (नकारात्मक शुद्ध मात्रा, लापता आपूर्तिकर्ता VAT नंबर, देश-कोड बेमेल, आपूर्तिकर्ता जो VAT-पंजीकृत नहीं हैं) के खिलाफ चालान का मिलान भी करता है। - गणना करें. एक शुद्ध-फ़ंक्शन पायथन मॉड्यूल - गणित में कोई LLM नहीं - वर्गीकृत पंक्तियों को पढ़ता है और Box 9 के माध्यम से Box 1, साथ ही मार्कडाउन में एक ड्राई-रन रिपोर्ट तैयार करता है। फ्लैट-रेट योजना, नकद लेखांकन और वार्षिक लेखा शाखाएँ स्पष्ट कोड पथ हैं, त्वरित निर्देश नहीं।
- जमा करना। मेरे (या मेरे अकाउंटेंट) द्वारा ड्राई-रन पर हस्ताक्षर करने के बाद ही पाइपलाइन HMRC MTD API पर कॉल करती है। OAuth2 टोकन. धोखाधड़ी-रोकथाम शीर्षलेख.
GET obligationsखुली अवधि खोजने के लिए.POST returnsसाथfinalised: true. तबGET liabilitiesयह पुष्टि करने के लिए कि मुझे क्या देना है और कब देना है।
ज़ीरो / क्विकबुक / फ्रीएजेंट के बजाय Claude Code क्यों
ईमानदारी से कहें तो, अधिकांश छोटे व्यवसायों के लिए, एक पैकेज्ड अकाउंटेंट SaaS सही उत्तर है। उनके पास HMRC प्रमाणन, सहायता टीमें हैं और आपका अकाउंटेंट उन्हें पहले से ही जानता है। तो मैंने ऐसा क्यों किया?
- मैं पहले से ही हर दिन Claude Code का उपयोग करता हूं सॉफ्टवेयर कार्य के लिए. VAT पाइपलाइन को असेंबल करने के लिए इसका उपयोग करने की सीमांत लागत भी कम है।
- मेरा डेटा स्थानीय है. चालान डीबी मेरी मशीन को कभी नहीं छोड़ता। क्लासिफायरियर पंक्तियों पर चलता है; गणित स्थानीय पायथन है; केवल अंतिम नौ नंबर HMRC पर जाते हैं। कोई SaaS किरायेदार नहीं, कोई तीसरा पक्ष नहीं।
- मैं वर्गीकरण नियमों पर पूर्ण नियंत्रण चाहता था। मेरा कुछ आपूर्तिकर्ता मिश्रण अजीब है (ईयू सेवाएं, स्थगित आयात VAT, शून्य-रेटेड किनारे के कुछ मामले)। उन नियमों को एनकोड करना
vat-rules.md+ मेरे लिए SaaS को कॉन्फ़िगर करने की तुलना में Python मॉड्यूल तेज़ है। - ऑडिट ट्रेल मेरा है. प्रत्येक क्लाउड प्रॉम्प्ट और प्रत्येक अंतर हस्ताक्षरित अवधि स्नैपशॉट के साथ एक केवल-परिशिष्ट लॉग में प्रतिबद्ध है। यदि HMRC कभी पूछे, तो मैं सेकंडों में सटीक गणना कर सकता हूँ।
यदि आप पहले से ही Claude Code का उपयोग नहीं करते हैं या आप आधी रात को पायथन पढ़ने का आनंद नहीं लेंगे, तो कृपया Xero / QuickBooks / FreeAgent का उपयोग करें। यह आपके स्वयं के VAT सिस्टम को रोल करने की अनुशंसा नहीं है। यह एक कहानी है कि जब आप ऐसा करते हैं तो क्या संभव है।
LLM कहाँ है और कहाँ नहीं है
यह वह हिस्सा है जिसके बारे में मैं ज़ोर से बोलना चाहता हूँ। क्लाउड VAT अंकगणित में नहीं है. क्लाउड लाइनों को वर्गीकृत करता है, सामंजस्य का सुझाव देता है, और गणित करने वाले नियतात्मक पायथन मॉड्यूल को उत्पन्न और संपादित करता है। Box 9 के माध्यम से Box 1 की वास्तविक गणना इकाई परीक्षणों के साथ एक शुद्ध कार्य है। HMRC सबमिशन के लिए मानव अनुमोदन गेट की आवश्यकता होती है। ड्राई-रन रिपोर्ट साइन-ऑफ़ के लिए सत्य का स्रोत है। यदि मैं कोड और वर्गीकृत पंक्तियों को देखकर यह नहीं समझा सकता कि कोई संख्या ऐसी क्यों है, तो मैं प्रस्तुत नहीं करता।
यह एक कठिन नियम है क्योंकि वित्त विनियमित है, और "एआई ने यह किया" MTD के तहत कोई बचाव नहीं है। लंबा लेख अपने स्वयं के कार्यान्वयन में इस रेखा को कैसे खींचना है, इसके बारे में अधिक विस्तार से बताया गया है।
इसे बनाने में मुझे कितना खर्च आया और इसे चलाने में मुझे कितना खर्च आया
निर्माण का समय लगभग एक सप्ताह की केंद्रित शाम थी - ज्यादातर स्कीमा सामान्यीकरण, क्लासिफायर नियम और इंजन के लिए परीक्षण लिखने पर खर्च किया गया। HMRC MTD OAuth नृत्य सबसे धीमा भाग था; सबसे पहले सैंडबॉक्स के विरुद्ध दौड़ना हर मिनट के लायक था।
चलाने के लिए, प्रत्येक तिमाही में मेरी लागत लगभग होती है: मेरी Claude Code सदस्यता (पहले से ही अन्य काम के लिए भुगतान की गई) और क्लासिफायर के लिए टोकन उपयोग में कुछ पैसे। HMRC API स्वयं निःशुल्क है। VAT इंजन और ऑडिट लॉग मेरे Mac पर स्थानीय रूप से चलते हैं।
महत्वपूर्ण अस्वीकरण
मैं एक इंजीनियर हूं, चार्टर्ड अकाउंटेंट नहीं। यह लेख कर संबंधी सलाह नहीं है. इससे पहले कि आप अपने वास्तविक HMRC खाते के विरुद्ध ऐसा कुछ भी चलाएँ, यूके-पंजीकृत अकाउंटेंट से अपने पहले रिटर्न की शुरू से अंत तक समीक्षा करवाएँ। HMRC MTD का प्रयोग करें सैंडबॉक्स जब तक आप और आपका अकाउंटेंट दोनों खुश न हों। एक ख़राब VAT सबमिशन की लागत एक अकाउंटेंट के एक घंटे के समय की लागत से बहुत अधिक है।
लंबा संस्करण पढ़ें
यदि आप पूरी तस्वीर चाहते हैं - सटीक क्रिएट टेबल स्कीमा, Claude Code संकेत, यूनिट परीक्षणों के साथ नियतात्मक पायथन इंजन, HMRC MTD OAuth प्रवाह, धोखाधड़ी-रोकथाम हेडर, और किनारे के मामलों पर एक संपूर्ण अनुभाग (ब्रेक्सिट / NI प्रोटोकॉल, रिवर्स चार्ज, आंशिक छूट, फ्लैट-रेट योजना, मध्य-तिमाही दर परिवर्तन, बहु-मुद्रा चालान, क्रेडिट नोट, जमा) - पढ़ें लंबा लेख. यह वह संस्करण है जिसे मैं शुरू करने से पहले पढ़ना चाहता था।
देखें यूट्यूब वॉकथ्रू, अनुवर्ती ट्यूटोरियल (ऑटो-आयात बैंक फ़ीड, रसीदों के लिए ओसीआर, अनुसूचित क्रॉन + स्लैक अनुमोदन) के लिए सदस्यता लें, और याद रखें: कर सलाह नहीं, अकाउंटेंट साइन-ऑफ आवश्यक है।
ब्लॉग से और
Observability Is Not Optional: Make It a Business Standard
Why fragmented monitoring creates blind spots, duplicate spend, and slow incidents — and how to make centralised observability a non-negotiable company standard.
WSL Vault for Compliance: One Tenant Never Opens Another’s Secrets
How WSL Vault keeps app, team, and environment tenants cryptographically isolated — so a stolen root-style token cannot empty the estate — and why dual-tenant control beats secrets sprawl.
Workstation AI Shop: Promoting the AI Sales Storefront Through int → test → acc → prod
Workstation AI Shop sells GPU machines with a fully autonomous AI Sales Agent that configures the basket. See how Ring Promoter moves each build through int → test → acc → prod — with Orbit screenshots release engineers and stakeholders share.