mrsool / zatca

An unofficial Ruby library for generating ZATCA e-invoices, QR Codes, and submitting e-invoices to ZATCA's servers.
MIT License
36 stars 11 forks source link

Need help with discount fields when reporting invoice #32

Open Anas-Nabulsi opened 2 months ago

Anas-Nabulsi commented 2 months ago

I have a confusion regarding how to handle discounts at the invoice level versus the line item level. Currently, applying the discount solely to the invoice line items without reflecting it at the document level doesn't trigger any warnings or errors. However, when the total discount from the invoice lines is added to the discount at the document level and allowance_total_amount, these warning appears in zatca response:

{
  "type": "WARNING",
   "code": "BR-S-08",
   "category": "EN_16931",
   "message": "لكل رمز من فئات ضريبة القيمة المضافة (BT-119) الذي يكون فيه الرمز الخاصّ بفئة ضريبة القيمة المضافة (BT-118) “خاضع للضريبة بالنسبة الأساسية“، يجب أن يكون المبلغ الخاضع للضريبة ضمن فئة ضريبة القيمة المضافة (BT-116) مساويًا لمجموع المبالغ الصافية على مستوى بند الفاتورة (BT-131) مطروحًا منه مجموع مبالغ الخصم على مستوى المستند(BT-92) بالإضافة إلى مجموع مبالغ الرسوم على مستوى المستند (BT-99) في الحالات التي تكون فيها الرموز الخاصّة بفئة ضريبة القيمة المضافة (BT-151, BT-95, BT-102) “خاضعة للضريبة بالنسبة الأساسية“.، ونسبة ضريبة القيمة المضافة للعناصر (BT-152,BT-96,BT-103) يجب أن تساوي نسبة ضريبة القيمة المضافة للعنصر (BT-119).",
    "status": "WARNING"
},
 {
    "type": "WARNING",
    "code": "BR-CO-13",
     "category": "EN_16931",
     "message": "المبلغ الإجمالي للفاتورة غير شامل ضريبة القيمة المضافة (BT-109) = Σ صافي المبلغ على مستوى بند الفاتورة (BT-131) - مجموع الخصومات على مستوى المستند (BT-107) + مجموع الرسوم على مستوى المستند (BT-108).",
      "status": "WARNING"
 }

Despite there being only one discount amount per invoice line (in my case that I'm testing), this same discount amount is present in both "discount_amount" and "allowance_total_amount" at the document level so as per the documentation it's correct.

Here's the relevant part of the xml for the invoice that gets a pass without errors or warnings (notice discount is only on invoice line)

    <cac:AllowanceCharge>
        <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
        <cbc:AllowanceChargeReason>discount</cbc:AllowanceChargeReason>
        <cbc:Amount currencyID="SAR">0.00</cbc:Amount>
        <cac:TaxCategory>
            <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5305">S</cbc:ID>
            <cbc:Percent>15</cbc:Percent>
            <cac:TaxScheme>
                <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5153">VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:TaxCategory>
        <cac:TaxCategory>
            <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5305">S</cbc:ID>
            <cbc:Percent>15</cbc:Percent>
            <cac:TaxScheme>
                <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5153">VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:TaxCategory>
    </cac:AllowanceCharge>

....

    <cac:LegalMonetaryTotal>
        <cbc:LineExtensionAmount currencyID="SAR">286.67</cbc:LineExtensionAmount>
        <cbc:TaxExclusiveAmount currencyID="SAR">286.67</cbc:TaxExclusiveAmount>
        <cbc:TaxInclusiveAmount currencyID="SAR">329.68</cbc:TaxInclusiveAmount>
        <cbc:AllowanceTotalAmount currencyID="SAR">0.00</cbc:AllowanceTotalAmount>
        <cbc:PrepaidAmount currencyID="SAR">0.00</cbc:PrepaidAmount>
        <cbc:PayableAmount currencyID="SAR">329.68</cbc:PayableAmount>
    </cac:LegalMonetaryTotal>

...

    <cac:InvoiceLine>
        <cbc:ID>1</cbc:ID>
        <cbc:InvoicedQuantity unitCode="PCE">1.000000</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="SAR">234.50</cbc:LineExtensionAmount>
        <cac:TaxTotal>
            <cbc:TaxAmount currencyID="SAR">35.18</cbc:TaxAmount>
            <cbc:RoundingAmount currencyID="SAR">269.68</cbc:RoundingAmount>
        </cac:TaxTotal>
        <cac:Item>
            <cbc:Name>...</cbc:Name>
            <cac:ClassifiedTaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>15.00</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:ClassifiedTaxCategory>
        </cac:Item>
        <cac:Price>
            <cbc:PriceAmount currencyID="SAR">234.50</cbc:PriceAmount>
            <cac:AllowanceCharge>
                <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
                <cbc:AllowanceChargeReason>discount</cbc:AllowanceChargeReason>
                <cbc:Amount currencyID="SAR">100.50</cbc:Amount>
            </cac:AllowanceCharge>
        </cac:Price>
    </cac:InvoiceLine>
    <cac:InvoiceLine>
        <cbc:ID>2</cbc:ID>
        <cbc:InvoicedQuantity unitCode="PCE">1.000000</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="SAR">52.17</cbc:LineExtensionAmount>
        <cac:TaxTotal>
            <cbc:TaxAmount currencyID="SAR">7.83</cbc:TaxAmount>
            <cbc:RoundingAmount currencyID="SAR">60.00</cbc:RoundingAmount>
        </cac:TaxTotal>
        <cac:Item>
            <cbc:Name>...</cbc:Name>
            <cac:ClassifiedTaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>15.00</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:ClassifiedTaxCategory>
        </cac:Item>
        <cac:Price>
            <cbc:PriceAmount currencyID="SAR">52.17</cbc:PriceAmount>
            <cac:AllowanceCharge>
                <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
                <cbc:AllowanceChargeReason>discount</cbc:AllowanceChargeReason>
                <cbc:Amount currencyID="SAR">0.00</cbc:Amount>
            </cac:AllowanceCharge>
        </cac:Price>
    </cac:InvoiceLine>

And this is the xml that gets the warnings mentioned

    <cac:AllowanceCharge>
        <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
        <cbc:AllowanceChargeReason>discount</cbc:AllowanceChargeReason>
        <cbc:Amount currencyID="SAR">100.50</cbc:Amount>
        <cac:TaxCategory>
            <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5305">S</cbc:ID>
            <cbc:Percent>15</cbc:Percent>
            <cac:TaxScheme>
                <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5153">VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:TaxCategory>
        <cac:TaxCategory>
            <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5305">S</cbc:ID>
            <cbc:Percent>15</cbc:Percent>
            <cac:TaxScheme>
                <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5153">VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:TaxCategory>
    </cac:AllowanceCharge>

...

    <cac:LegalMonetaryTotal>
        <cbc:LineExtensionAmount currencyID="SAR">286.67</cbc:LineExtensionAmount>
        <cbc:TaxExclusiveAmount currencyID="SAR">286.67</cbc:TaxExclusiveAmount>
        <cbc:TaxInclusiveAmount currencyID="SAR">329.68</cbc:TaxInclusiveAmount>
        <cbc:AllowanceTotalAmount currencyID="SAR">100.50</cbc:AllowanceTotalAmount>
        <cbc:PrepaidAmount currencyID="SAR">0.00</cbc:PrepaidAmount>
        <cbc:PayableAmount currencyID="SAR">329.68</cbc:PayableAmount>
    </cac:LegalMonetaryTotal>

...

    <cac:InvoiceLine>
        <cbc:ID>1</cbc:ID>
        <cbc:InvoicedQuantity unitCode="PCE">1.000000</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="SAR">234.50</cbc:LineExtensionAmount>
        <cac:TaxTotal>
            <cbc:TaxAmount currencyID="SAR">35.18</cbc:TaxAmount>
            <cbc:RoundingAmount currencyID="SAR">269.68</cbc:RoundingAmount>
        </cac:TaxTotal>
        <cac:Item>
            <cbc:Name>...</cbc:Name>
            <cac:ClassifiedTaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>15.00</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:ClassifiedTaxCategory>
        </cac:Item>
        <cac:Price>
            <cbc:PriceAmount currencyID="SAR">234.50</cbc:PriceAmount>
            <cac:AllowanceCharge>
                <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
                <cbc:AllowanceChargeReason>discount</cbc:AllowanceChargeReason>
                <cbc:Amount currencyID="SAR">100.50</cbc:Amount>
            </cac:AllowanceCharge>
        </cac:Price>
    </cac:InvoiceLine>

    <cac:InvoiceLine>
        <cbc:ID>2</cbc:ID>
        <cbc:InvoicedQuantity unitCode="PCE">1.000000</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="SAR">52.17</cbc:LineExtensionAmount>
        <cac:TaxTotal>
            <cbc:TaxAmount currencyID="SAR">7.83</cbc:TaxAmount>
            <cbc:RoundingAmount currencyID="SAR">60.00</cbc:RoundingAmount>
        </cac:TaxTotal>
        <cac:Item>
            <cbc:Name>...</cbc:Name>
            <cac:ClassifiedTaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>15.00</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:ClassifiedTaxCategory>
        </cac:Item>
        <cac:Price>
            <cbc:PriceAmount currencyID="SAR">52.17</cbc:PriceAmount>
            <cac:AllowanceCharge>
                <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
                <cbc:AllowanceChargeReason>discount</cbc:AllowanceChargeReason>
                <cbc:Amount currencyID="SAR">0.00</cbc:Amount>
            </cac:AllowanceCharge>
        </cac:Price>
    </cac:InvoiceLine>
obahareth commented 1 month ago

I am not sure what is causing the error but you can view the relevant validation criteria here:

You can just search this repo for those error codes and it will help you point you to the right direction.