بناء نظام إرجاع VAT باستخدام Claude Code من قاعدة بيانات الفواتير والنفقات الخاصة بك

هذا هو الغوص العميق الطويل. للحصول على نسخة أسرع وقابلة للقراءة، راجع مشاركة مدونة مصاحبة.

1. لماذا بنيت هذا

يتعين على كل شركة صغيرة في المملكة المتحدة يتجاوز حجم مبيعاتها الخاضع للضريبة حد تسجيل VAT أن تقوم بحساب وتقديم عائد VAT - عادةً كل ثلاثة أشهر - من خلال خدمة Making Tax Digital (MTD) الخاصة بـ HMRC. تسعة صناديق مرقمة. إخراج VAT ناقص إدخال VAT. ادفع المبلغ الصافي، أو قم بالمطالبة باسترداد المبلغ. سهل من الناحية النظرية. عقاب عملي عندما تكون فواتيرك موجودة في Postgres، وإيصالات النفقات الخاصة بك عبارة عن ملفات PDF من عشرين موردًا مختلفًا، وكشوف حساباتك المصرفية بتنسيق CSV من Wise وRevolut، ويجب إعادة قيد خطوط العملة الأجنبية بالجنيه الاسترليني بالسعر الشهري المناسب.

لبضع سنوات كنت أتعامل مع جدول بيانات ضخم، وتذكير بالتقويم، وقفزة صغيرة من الإيمان. استغرق كل ربع سنة ما يقرب من نصف يوم، وكان معظمها عبارة عن مشاحنات حول البيانات - قم بتصدير ملف CSV من قاعدة بيانات الفواتير، ولصقه في برنامج Excel، وتصنيف بضع مئات من الصفوف يدويًا، والتحقق مرة أخرى من الصيغ، ونسخ تسعة أرقام إلى جسر MTD لجهة خارجية، ثم انقر فوق إرسال. مسار التدقيق كان "ثق بي، كان لدي جدول بيانات". لقد كسرته التغيرات في أسعار الفائدة في منتصف الربع. اختفت الإيصالات. تصنيف واحد في غير محله يمكن أن يدفع Box 5 بمئات الجنيهات.

لقد قمت بإعادة بناء خط الأنابيب هذا العام باعتباره صغيرًا Claude Code مشروع يتحدث إلى قاعدة بيانات الفواتير والنفقات الخاصة بي مباشرة، ويصنف كل سطر، ويحسب Box 1 إلى Box 9 باستخدام محرك Python الحتمي، ويجري عملية الإرجاع الجافة كتقرير Markdown، ولا يتم إرساله إلى HMRC MTD إلا ​​بعد تسجيل الخروج البشري. يستغرقني الربع بأكمله الآن حوالي ساعة، معظمها أقوم بمراجعة التجربة التجريبية مع المحاسب الخاص بي. مسار التدقيق هو git repo. يتم اختبار الرياضيات بالوحدة. المصنف هو ملف Markdown موثق. التقديم مسور.

هذه المقالة هي النسخة الطويلة. المطالبات، Python، المخطط، تدفق HMRC OAuth، حالات الحافة. إذا كنت تريد النسخة القصيرة أولاً، فاقرأ مدونة رفيقة.

2. التمهيدي HMRC MTD (وإخلاء المسؤولية)

Making Tax Digital لـ VAT هو مطلب HMRC بأن تحتفظ الشركات المسجلة في VAT بالسجلات الرقمية وتقدم العوائد من خلال برنامج متوافق عبر API موثق بدلاً من كتابة الأرقام في نموذج الويب gov.uk. 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، والإعفاء الجزئي، ونظام السعر الثابت، وقواعد مكان التوريد للخدمات الرقمية، والمعاملة بعد خروج بريطانيا من الاتحاد الأوروبي لسلع وخدمات الاتحاد الأوروبي، وبروتوكول 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)

بالنسبة لمعظم الشركات الصغيرة في المملكة المتحدة، فإن الإجابة هي - بصدق - استخدام البرامج المجمعة. Xero وQuickBooks وFreeAgent وSage جميعها لديها تقديم MTD معتمد من HMRC وواجهات مستخدم مناسبة ومحاسبين يعرفونها بالفعل. يجب ألا تقوم بتشغيل نظام VAT الخاص بك إلا إذا كان لديك سبب واضح.

كانت أسبابي ضيقة ولكنها حقيقية. أنا بالفعل أستخدم Claude Code كل يوم للعمل البرمجي، لذلك كان الجهد الهامشي لاستخدامه أيضًا مع VAT صغيرًا. توجد قاعدة بيانات الفواتير الخاصة بي على جهازي الخاص؛ أفضّل ألا يتم عكسه في مستأجر SaaS. مزيج الموردين الخاص بي غريب (خدمات الاتحاد الأوروبي ذات الرسوم العكسية، والاستيراد المؤجل VAT، وحالات الحافة العرضية ذات التصنيف الصفري) وترميز القواعد في ملف Markdown واحد بالإضافة إلى وحدة Python تبين أنها أسرع من تكوين SaaS للتعامل معها. ومسار التدقيق الذي أحصل عليه من git repo - كل موجه مصنف، وكل فرق، وكل لقطة لفترة موقعة - هو بالضبط مسار التدقيق الذي أريده.

إن Claude Code مناسب تمامًا لهذا لثلاثة أسباب. أولاً، يعمل مباشرة ضد مشروع على القرص: يمكنه قراءة المخطط الخاص بي، وتقارير التشغيل التجريبي للربع السابق، وملف القواعد، ومحرك بايثون، واقتراح التعديلات في السياق. ثانيًا، إنه جيد في السقالات المملة - نصوص الترحيل، ومستوردي CSV، وتقارير التسوية، وتركيبات pytest. ثالثًا، عندما يصنف سطرًا ما، فإنه يشرح منطقه باللغة الإنجليزية البسيطة، وهو بالضبط ما أريد مراجعته قبل التوقيع على الإرجاع. إن مصفوفة القرار الموجودة في الجزء السفلي من مخطط سير العمل أدناه هي النسخة الصادقة من هذه المقايضة.

5. الهندسة المعمارية وسير العمل

يحتوي خط الأنابيب على خمسة ممرات للسباحة. مصدر هو حق الوصول للقراءة فقط إلى جداول الفواتير والمصروفات بالإضافة إلى مجلد إسقاط لملف CSV من خلاصات Stripe وWise والبنك. استيعاب + تطبيع عبارة عن برنامج نصي صغير من نوع Python تم إنشاؤه بواسطة Claude والذي يقوم بتعيين كل مخطط مصدر في عرض أساسي واحد، وتحويل العملة الأجنبية إلى GBP بمعدل HMRC الشهري، وتطبيق مرشح النطاق الزمني، وختم كل صف بعلامة Idempotent 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، أ build_run_key() التي تقوم بالتجزئة (period_start،period_end، المخطط، schema_version) في سلسلة سداسية ثابتة، وCLI قائم على النقر. لقد قمت بتحرير اسمين للحقول وقبلت الباقي.

موجه 2 - المصنف. "يقرأ vat-rules.md والكتابة classify.py. لكل صف متعارف عليه من normalise.py، تعيين vat_treatment إلى واحد من: معيار, مخفض, صفر, معفى, خارج النطاق, الشحن العكسي, سلع الاتحاد الأوروبي, خدمات الاتحاد الأوروبي, تأجيل الاستيراد. إذا كان الصف يحتوي بالفعل على غير فارغ vat_treatment، اتركه وشأنه وقم بتسجيله باسم محفوظ. بخلاف ذلك، اختر رمز البلد ورقم المورد VAT والفئة والمبلغ واكتب جملة واحدة reason على كل صف. يتم نقل الحالات الشاذة (الصافي السلبي، المورد المفقود VAT لمورد المملكة المتحدة فوق حد التسجيل، عدم تطابق البلد) إلى قسم منفصل anomalies.json للمراجعة البشرية. لا تقم بتغيير قاعدة البيانات المصدر."

المصنف نفسه عبارة عن وظيفة صغيرة تعتمد في الغالب على القواعد مع فرع واحد مدعوم من LLM لفئات النفقات الغامضة. والأهم من ذلك، أنه لا يكتب أبدًا إلى قاعدة البيانات المصدر - فهو يصدر ملف JSON مصنفًا يقرأه المحرك. إذا لم أتفق مع التصنيف، أقوم بتحرير JSON؛ الجولة الجافة التالية تلتقطها.

موجه 3 - المحرك. "يكتب engine.py كوظيفة نقية: def compute_boxes(rows: list[Row], scheme: Scheme) -> BoxTotals. لا يوجد إدخال/إخراج. لا يوجد LLM. BoxTotals عبارة عن فئة بيانات مجمدة من Box 1 إلى Box 9 as Decimal القيم إلى 2 موانئ دبي. إضافة فروع صريحة ل standard, flat_rate, cash، و annual المخططات. المخطط القياسي هو الاستحقاق: تساهم مبيعات VAT في Box 1، وشراء VAT إلى Box 4. تتم إضافة فواتير الرسوم العكسية إلى كل من Box 1 وBox 4. يضيف الاستيراد المؤجل VAT إلى كل من Box 1 وBox 4. عمليات الاستحواذ في الاتحاد الأوروبي لشركات NI تتم في Box 2 وBox 9. قم بالتقريب إلى إجماليات الصندوق، وليس لكل صف أبدًا. واكتب عقيدة تربط كل فرع بحكمه."

موجه 4 - تقرير التشغيل الجاف. "يكتب dryrun.py هذا يدعو compute_boxes() ويصدر تقرير تخفيض السعر: رأس بالفترة والمخطط، وجدول من Box 1 إلى Box 9 مع التسميات الأساسية، وقسم لكل مجموعة مصنف يسرد أعلى 10 صفوف حسب الإجمالي، وقسم الحالات الشاذة، وتذييل مع run_key وSHA-256 من JSON المصنف. حفظ ل ./audit/<period>/dryrun.md."

موجه 5 - مقدم. "يكتب submit.py ضد HMRC MTD VAT API v1.0. استخدم تدفق OAuth2 Authorization_code مع PKCE. اقرأ رمز الوصول من ~/.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 يتم تعيين وأنواع المشغلين يُقدِّم."

خمس مطالبات وأربعة ملفات ومستند صغير لقواعد Markdown. ربما كان إجمالي وقت الإنشاء عبارة عن أسبوع من الأمسيات المركزة، وكان معظمها عبارة عن قواعد المصنف ورقصة 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")

مع وجود هذا في مكانه، يتم اكتشاف كل انحدار في CI قبل أن يمس تقرير التشغيل التجريبي. يستطيع كلود مساعدتي في كتابة المزيد من الاختبارات؛ ولا يمكنه تغيير المحرك دون اجتياز تلك الاختبارات.

8. فيديو تجريبي

يوجد أدناه عرض تفصيلي قصير لخط الأنابيب الذي يعمل من البداية إلى النهاية مقابل قاعدة بيانات حقيقية (مجهولة المصدر) للفواتير والنفقات لمدة ربع سنة: التطبيع، والتصنيف، والتشغيل الجاف، ثم إرسال صندوق الحماية MTD. الحلقة بأكملها مدتها بضع دقائق.

9. تقديم HMRC MTD

هذا هو الجزء الذي تتجاهله معظم الكتابات. إن MTD VAT API نفسه موثق جيدًا ومجاني، ولكن هناك ثلاثة أشياء تحتاج إلى الحصول عليها بشكل صحيح قبل الاتصال POST returns.

OAuth2 والرموز. سجل تطبيقًا في مركز مطوري HMRC؛ تحصل على معرف العميل وسر العميل وURI لإعادة التوجيه. التدفق هو Authorisation_code مع PKCE: افتح المتصفح على صفحة موافقة HMRC، ويقوم المستخدم بتسجيل الدخول باستخدام بيانات اعتماد البوابة الحكومية الخاصة به ويأذن بتطبيقك مقابل رقم تسجيل VAT (VRN)، ويعيد HMRC التوجيه مرة أخرى باستخدام رمز التفويض، ويمكنك استبداله برمز وصول + رمز تحديث. قم بتخزينها مؤقتًا بأذونات معقولة على القرص. رمز الوصول قصير الأجل؛ رمز التحديث أطول بكثير.

رؤوس منع الاحتيال. يتطلب HMRC مجموعة موثقة من رؤوس HTTP التي تحدد الجهاز الأصلي في كل مكالمة API: المنطقة الزمنية، وهندسة الشاشة، ومعرفات المستخدم، وIP العام، وعناوين MAC، وطريقة اتصال العميل، وما إلى ذلك. القائمة والتنسيق الدقيقان موجودان في وثائق مطور HMRC (راجع إشعار HMRC VAT 700 ومواصفات منع الاحتيال ذات الصلة للقاعدة الموثوقة). أخطئ في فهمهم وستحصل على 403 مع خطأ غامض. احصل عليهم بشكل صحيح وستتم المكالمة. أنا أحتفظ بهم في fraud_headers.py والتأكيد على تواجدهم في الاختبارات.

رمل أولا. يوفر HMRC وضع حماية مجانيًا في test-api.service.hmrc.gov.uk مع VRNs كعب الروتين والتزامات كعب الروتين. قم بتشغيل خط الأنابيب بالكامل من البداية إلى النهاية في وضع الحماية حتى تقدم إقرارًا مزيفًا، وتتلقى معرف إيصال مزيفًا، وتؤكد نقل التزاماتك. عندها فقط تقلب HMRC_ENV=live. يرفض المرسل الاتصال المباشر ما لم يتم تعيين متغير البيئة وأنواع المشغل SUBMIT في الموجه. لا يوجد مسار تنفيذ تلقائي للعيش. تعد تكلفة الإرسال المباشر السيئ واحدًا أعلى بكثير من تكلفة تكرار وضع الحماية مرة أخرى.

نداء المسار السعيد الفعلي قصير: GET obligations مع status=O للعثور على الفترة المفتوحة، قم بعرض تقرير التشغيل التجريبي، ثم اطلب من المشغل التأكيد، ثم POST returns مع أرقام المربع التسعة، و periodKey من الإلزام، و finalised: true. احفظ الرد، واكتب معرف الإيصال في مجلد التدقيق، وبذلك تكون قد انتهيت.

10. السلامة والتدقيق والامتثال

ثلاث قواعد لن أتحرك عليها. أولاً، كلود ليس في الحساب. يقترح المصنف علاجات ويمكن لـ LLM تحرير Python والقواعد، ولكن يتم إنتاج إجماليات الصندوق بواسطة وظيفة خالصة مع اختبارات الوحدة. "لقد فعلها الذكاء الاصطناعي" ليس دفاعًا بموجب MTD. ثانية، كل تقديم مسور من قبل الإنسان. تقرير التشغيل التجريبي هو مصدر الحقيقة للتوقيع. إذا لم أتمكن من شرح رقم من الصفوف المبوبة وكود المحرك، فلن أقدم. ثالث، مسار التدقيق هو إلحاق فقط. تتم كتابة كل JSON مصنف، وكل تقرير تشغيل تجريبي، وكل مطالبة، وكل فرق، ومعرف إيصال HMRC النهائي للفترة في ./audit/<period>/ وملتزمون بمستودع git الخاص. يتطلب HMRC ست سنوات من السجلات؛ الألغام هي لقطات موقعة.

ممارستان أخريان أوصي بهما حتى لو لم تعتمد الباقي. قم بتشغيل اتصال قاعدة البيانات المصدر كدور للقراءة فقط ذو امتيازات أقل: لا UPDATE، لا DELETE، لا DROP. احتفظ بسرية عميل HMRC ورموز الوصول خارج الريبو باستخدام مدير سري أو ملف 0600 في الدليل الرئيسي الخاص بك. والمغزى هنا هو جعل الحوادث مستحيلة من خلال البناء، وليس فقط من خلال السياسة.

11. حالات الحافة

VAT هي ضريبة منظمة تم تحريرها من قبل كل حكومة في المملكة المتحدة منذ عام 1973، مع تراكب ما بعد خروج بريطانيا من الاتحاد الأوروبي وبروتوكول أيرلندا الشمالية في الأعلى. حالات الحافة حقيقية. قائمة غير شاملة لتلك التي يتعامل معها محركي:

• خروج بريطانيا من الاتحاد الأوروبي وأيرلندا الشمالية. لم تعد الشركات في بريطانيا العظمى تملأ Box 8 أو Box 9. لا تزال شركات NI تقوم بذلك مقابل السلع (وليس الخدمات) بموجب بروتوكول NI. يأخذ المحرك is_ni_business كمعلمة والفروع وفقا لذلك. راجع إشعار HMRC VAT رقم 700 لمعرفة القاعدة الموثوقة.
• تهمة عكسية. يتم احتساب الخدمات المشتراة من مورد خارج المملكة المتحدة (وبعض خدمات صناعة البناء والتشييد المحلية) ضمن الرسوم العكسية: يمكنك إضافة الناتج الافتراضي VAT إلى Box 1 واستعادة نفس المبلغ في Box 4. صافي التأثير على النقد هو صفر؛ التأثير الصافي على العودة هو صندوقان يتحركان معًا.
• تأجيل استيراد VAT. بالنسبة للسلع المستوردة من خارج المملكة المتحدة، يمكنك تأجيل استيراد VAT إلى إرجاعك التالي بدلاً من دفعه على الحدود. يبدو العلاج مشابهًا للرسوم العكسية عند العودة.
• الإعفاء الجزئي. إذا قمت بإجراء توريدات خاضعة للضريبة ومعفاة، فيمكنك فقط استعادة المدخلات VAT إلى الحد الذي يتعلق بالتوريدات الخاضعة للضريبة. هناك طرق قياسية وخاصة؛ هذه هي الزاوية التي تحتاج في أغلب الأحيان إلى محاسب. لا تحاول ترميز قواعد الإعفاء الجزئي في ملف Markdown.
• مخطط المعدل الثابت. أنت تتقاضى 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. يتم تشغيل المحرك وسجل التدقيق محليًا على جهاز Mac الخاص بي. وقت المراجعين لكل ربع سنة حوالي ساعة أمضيتها في قراءة التقرير التجريبي مع المحاسب الخاص بي. قارن ذلك بما يقرب من نصف يوم من الجدل حول جداول البيانات في ظل سير العمل القديم، والوقت الذي تم توفيره يسدد تكلفة الإنشاء خلال السنة الأولى.

إذا قمت بتسعير هذا كمشروع كنت تدفع لشخص آخر لبناءه، فستكون في الملعب المكون من أربعة أرقام من حيث أسعار الاستشارات - وهذا هو السبب في أن SaaS المعبأة بسعر يتراوح بين عشرين إلى خمسين جنيهًا شهريًا هي دائمًا الإجابة الصحيحة لمعظم الشركات. السؤال المثير للاهتمام ليس "هل هذا أرخص من Xero؟" - عادةً لا يكون الأمر كذلك - ولكن "هل هو أكثر دقة، وأكثر قابلية للتدقيق، وأسهل بالنسبة لي للتفكير فيه؟". بالنسبة لي الجواب هو نعم.

13. ما هو التالي، والخاتمة

الأجزاء التالية التي أريد إضافتها هي: استيراد موجز البنك التلقائي (Open Banking AISP)، والتعرف الضوئي على الحروف لملفات PDF للموردين بحيث يصبح عنوان URL للإيصال عبارة عن سطر ممسوح ضوئيًا فعليًا، وتدفق موافقة cron + Slack المجدول حتى لا أضطر إلى تذكر المواعيد النهائية، وامتداد الفواتير الذاتية لبائعي السوق. لا شيء من هذا يغير الشكل الأساسي لخط الأنابيب. كلها زخارف على نفس المخطط المكون من خمسة حارات.

الدرس الأكبر، بالنسبة لي على الأقل، هو مدى نجاح مشروع Claude Code الصغير في التعامل مع النصف الممل من سير العمل المنظم. النصف الممل هو معظم العمل: تطبيع المخطط، ومستوردو CSV، وتقارير التسوية، والتركيبات، وقواعد حالة الحافة، وتسجيل التدقيق. كلود ممتاز في كل ذلك. النصف الحتمي - الرياضيات الفعلية، والتقديم الفعلي - يبقى في لغة بايثون البسيطة مع اختبارات الوحدة وبوابة الموافقة البشرية، حيث ينتمي بالضبط.

إخلاء المسؤولية، مرة أخرى. هذه المقالة ليست نصيحة ضريبية. قبل أن تشير إلى أي شيء كهذا في حساب HMRC حقيقي، اطلب من محاسب مسجل في المملكة المتحدة مراجعة عائدك الأول بشكل شامل. قم بالمنافسة في وضع الحماية HMRC MTD حتى تشعر بالثقة أنت والمحاسب الخاص بك. للحصول على القاعدة الرسمية بشأن أي علاج محدد لـ VAT، راجع إشعار HMRC VAT رقم 700 والإشعارات ذات الصلة على موقع الويب gov.uk. إذا كنت ترغب في الحصول على نسخة قصيرة من كل هذا، فإن مشاركة مدونة مصاحبة هي قراءة مدتها خمس دقائق. بخلاف ذلك، قم بالاشتراك وسأواصل الكتابة مع نضوج المكدس.

لقطة SEO لهذه المقالة

• عنوان تحسين محركات البحث: قم ببناء نظام إرجاع VAT باستخدام Claude Code
• الوصف التعريفي: استخدم Claude Code لقراءة قاعدة بيانات الفواتير والنفقات الخاصة بك، وتصنيف VAT، وحساب HMRC Box 1 إلى 9، والتشغيل الجاف، ثم إرساله إلى MTD - المحرك الحتمي، والموافقة البشرية.
• الكلمات الرئيسية الأساسية: كود كلود، ضريبة القيمة المضافة، HMRC، MTD، المحاسبة، الأتمتة، بايثون، وكيل AI، Finops، الأعمال التجارية الصغيرة
• تويتر / X (أقل من 280 حرفًا): إعادة بناء إرجاع UK VAT الخاص بي كمشروع Claude Code: فواتير Postgres + نفقات DB إلى HMRC Box 1 إلى 9، محرك Python الحتمي، إرسال MTD الأول في وضع الحماية، بوابة الموافقة البشرية. كتابة كاملة + سير العمل SVG + فيديو تجريبي. ليست نصيحة ضريبية. #كلود كود #VAT #HMRC #MTD
• مشاركة لينكد إن: لقد قمت بإعادة بناء عائد VAT ربع السنوي الخاص بي في المملكة المتحدة كمشروع Claude Code صغير هذا العام. يقرأ قاعدة بيانات الفواتير والنفقات الخاصة بي للقراءة فقط، ويصنف كل سطر حسب معالجة VAT باستخدام ملف قواعد موثق، ويحسب HMRC Box 1 إلى 9 باستخدام محرك Python الحتمي (لا يوجد LLM في الحساب)، وفقط بعد أن أقوم بالتوقيع على التشغيل الجاف، يتم إرساله من خلال HMRC MTD API - وضع الحماية أولاً، ورؤوس منع الاحتيال، وتدفق OAuth2 الكامل. يستغرق الربع بأكمله الآن حوالي ساعة. الكتابة الكاملة مع المطالبات والمخطط ورمز المحرك وحالات الحافة وقصة التكلفة الصادقة موجودة على Workstation. ليست نصيحة ضريبية؛ احصل على محاسب لمراجعة عائدك الأول.