vat calculator

VatCalculator

تعامل مع جميع الأمور الصعبة المتعلقة بلوائح الضرائب/ضريبة القيمة المضافة الخاصة بالاتحاد الأوروبي، بالطريقة التي ينبغي أن تكون عليها. يتكامل مع Laravel وCashier — أو في تطبيق PHP مستقل . تم إنشاؤه في الأصل بواسطة مارسيل بوسيوت.

 // Easy to use !
VatCalculator:: calculate ( 24.00 , $ countryCode = ' DE ' );
VatCalculator:: calculate ( 24.00 , $ countryCode , $ postalCode );
VatCalculator:: calculate ( 71.00 , ' DE ' , ' 41352 ' , $ isCompany = true );
VatCalculator:: getTaxRateForLocation ( ' NL ' );

// Check validity of a VAT number
VatCalculator:: isValidVATNumber ( ' NL123456789B01 ' );

تحذير

لا تقدم هذه الحزمة أي وعود بشأن الضرائب المحسوبة بشكل صحيح. لا تزال مسؤولاً عن التأكد من صحة أي ضريبة محسوبة لحالة الاستخدام الخاصة بك. إذا لم تكن متأكدًا مما إذا كانت ضريبة معينة صحيحة أم لا، فمن الأفضل أن تتحدث إلى محاسب.

متطلبات

• PHP 7.3 أو أعلى
• (اختياري) Laravel 6.0 أو أعلى

تثبيت

تثبيت الحزمة مع الملحن:

composer require mpociot/vat-calculator

مستقل

يمكنك أيضًا استخدام هذه الحزمة بدون Laravel. ما عليك سوى إنشاء مثيل جديد لـ VatCalculator واستخدامه. تستخدم جميع الأمثلة التوثيقية كود Laravel Facade، لذا تأكد من عدم استدعاء التوابع كما لو كانت طرقًا ثابتة.

 use Mpociot  VatCalculator  VatCalculator ;

$ vatCalculator = new VatCalculator ();
$ vatCalculator -> setBusinessCountryCode ( ' DE ' );
$ grossPrice = $ vatCalculator -> calculate ( 49.99 , $ countryCode = ' LU ' );

الترقية

برجاء الرجوع إلى the upgrade guide عند ترقية المكتبة.

الاستخدام

احسب السعر الإجمالي

لحساب السعر الإجمالي، استخدم طريقة calculate مع السعر الصافي ورمز البلد كمعلمات.

 $ grossPrice = VatCalculator:: calculate ( 24.00 , ' DE ' );

المعلمة الثالثة هي الرمز البريدي للعميل.

كمعلمة رابعة، يمكنك تمرير قيمة منطقية تشير إلى ما إذا كان العميل شركة أم شخصًا خاصًا. إذا كان العميل شركة، ويجب عليك التحقق من صحة رقم ضريبة القيمة المضافة، فسيتم إرجاع السعر الصافي.

 $ grossPrice = VatCalculator:: calculate ( 24.00 , ' DE ' , ' 12345 ' , $ isCompany = true );

تلقي المزيد من المعلومات

بعد حساب السعر الإجمالي، يمكنك استخراج المزيد من المعلومات من VatCalculator.

 $ grossPrice = VatCalculator:: calculate ( 24.00 , ' DE ' ); // 28.56
$ taxRate = VatCalculator:: getTaxRate (); // 0.19
$ netPrice = VatCalculator:: getNetPrice (); // 24.00
$ taxValue = VatCalculator:: getTaxValue (); // 4.56

تلقي جميع معدلات الضرائب لبلد معين

للحصول على مصفوفة تتضمن كافة معدلات الضرائب المتاحة لبلد معين، استخدم الأسلوب getTaxRatesForCountry .

VatCalculator:: getTaxRatesForCountry ( ' DE ' ); // [ "high" = > 0.19 , "low" = > 0.07 ]

التحقق من صحة أرقام ضريبة القيمة المضافة في الاتحاد الأوروبي

قبل التحقق من صحة أرقام ضريبة القيمة المضافة لعملائك، يمكنك استخدام طريقة shouldCollectVAT للتحقق مما إذا كان رمز البلد يتطلب منك جمع ضريبة القيمة المضافة في المقام الأول.

 if (VatCalculator:: shouldCollectVAT ( ' DE ' )) {
    // This country code requires VAT collection ...
}

للتحقق من صحة أرقام ضريبة القيمة المضافة لعملائك، يمكنك استخدام طريقة isValidVATNumber . يجب أن يكون رقم ضريبة القيمة المضافة بالتنسيق المحدد بواسطة VIES. سيتم اقتطاع أرقام ضريبة القيمة المضافة المحددة وستتم إزالة الأحرف / المسافات البيضاء غير ذات الصلة تلقائيًا.

تعتمد هذه الخدمة على SOAP API لجهة خارجية والتي يوفرها الاتحاد الأوروبي. إذا، لأي سبب من الأسباب، واجهة برمجة التطبيقات هذه غير متاحة، فسيتم طرح VATCheckUnavailableException .

 try {
    $ validVAT = VatCalculator:: isValidVATNumber ( ' NL 123456789 B01 ' );
} catch ( VATCheckUnavailableException $ e ) {
    // The VAT check API is unavailable ...
}

وبدلاً من ذلك، من الممكن أيضًا التحقق من صحة تنسيق رقم ضريبة القيمة المضافة المحدد بواسطة VIES. يعد هذا مفيدًا إذا كنت لا تريد انتظار الرد من SOAP API.

 // This check will return false because no connection to VIES could be made ...
$ validVAT = VatCalculator:: isValidVATNumber ( ' NL 123456789 B01 ' );

// This check will return true because only the format is checked ...
$ validVAT = VatCalculator:: isValidVatNumberFormat ( ' NL 123456789 B01 ' );

احصل على تفاصيل رقم ضريبة القيمة المضافة في الاتحاد الأوروبي

للحصول على تفاصيل رقم ضريبة القيمة المضافة، يمكنك استخدام طريقة getVATDetails . يجب أن يكون رقم ضريبة القيمة المضافة بالتنسيق المحدد بواسطة VIES. سيتم اقتطاع أرقام ضريبة القيمة المضافة المحددة وستتم إزالة الأحرف / المسافات البيضاء غير ذات الصلة تلقائيًا.

تعتمد هذه الخدمة على واجهة برمجة تطبيقات SOAP التابعة لجهة خارجية والتي يوفرها الاتحاد الأوروبي. إذا، لأي سبب من الأسباب، واجهة برمجة التطبيقات هذه غير متاحة، فسيتم طرح VATCheckUnavailableException .

 try {
    $ vat_details = VatCalculator:: getVATDetails ( ' NL 123456789 B01 ' );
    print_r ( $ vat_details );
    / * Outputs
    stdClass Object
    (
        [ countryCode ] = > NL
        [ vatNumber ] = > 123456789 B01
        [ requestDate ] = > 2017 - 04 - 06 + 02 : 00
        [ valid ] = > false
        [ name ] = > Name of the company
        [ address ] = > Address of the company
    )
    * /
} catch ( VATCheckUnavailableException $ e ) {
    // The VAT check API is unavailable ...
}

أرقام ضريبة القيمة المضافة في المملكة المتحدة

يتم تنسيق أرقام ضريبة القيمة المضافة في المملكة المتحدة بشكل مختلف قليلاً:

 try {
    $ vat_details = VatCalculator:: getVATDetails ( ' GB 553557881 ' );
    print_r ( $ vat_details );
    / * Outputs
    array ( 3 ) {
        [ "name" ] = >
            string ( 26 ) "Credite Sberger Donal Inc."
        [ "vatNumber" ] = >
            string ( 9 ) "553557881"
        [ "address" ] = >
            array ( 3 ) {
                [ "line1" ] = >
                    string ( 18 ) "131B Barton Hamlet"
                [ "postcode" ] = >
                    string ( 8 ) "SW97 5CK"
                [ "countryCode" ] = >
                    string ( 2 ) "GB"
            }
    }
    * /
} catch ( VATCheckUnavailableException $ e ) {
    // The VAT check API is unavailable ...
}

لارافيل

إعدادات

بشكل افتراضي، تحتوي حاسبة ضريبة القيمة المضافة على جميع قواعد ضريبة القيمة المضافة في الاتحاد الأوروبي المحددة مسبقًا، بحيث يمكن تحديثها بسهولة، إذا تغيرت لبلد معين.

إذا كنت بحاجة إلى تحديد معدلات أخرى لضريبة القيمة المضافة، فيمكنك القيام بذلك عن طريق نشر التكوين وإضافة المزيد من القواعد.

تحذير
تأكد من تعيين رمز بلد عملك في ملف التكوين، للحصول على حساب ضريبة القيمة المضافة الصحيح عند البيع لعملاء الأعمال في بلدك.

لنشر ملفات التكوين، قم بتشغيل الأمر vendor:publish

php artisan vendor:publish --provider= " MpociotVatCalculatorVatCalculatorServiceProvider "

سيؤدي هذا إلى إنشاء vat_calculator.php في دليل التكوين الخاص بك.

معالجة أخطاء الصابون

إذا حدثت أخطاء SOAP لأي سبب من الأسباب عندما تكون واجهة برمجة تطبيقات VIES معيبة، فستتم معالجة هذه الأخطاء بأمان وسيتم إرجاع false . ومع ذلك، إذا كنت تريد صراحةً أن تكون على دراية بأي أخطاء في SOAP، فيمكنك توجيه VatCalculator لرميها باعتبارها VATCheckUnavailableException . سيحتوي VATCheckUnavailableException بعد ذلك على الرسالة المحددة لخطأ SOAP.

اضبط الخيار على true في ملف التكوين الخاص بك:

 <?php

return [
    ' forward_soap_faults ' => true ,
];

يمكنك أيضًا تعيين مهلة لعميل SOAP. بشكل افتراضي، يقوم SOAP بإحباط الطلب إلى VIES بعد 30 ثانية. إذا كنت لا تريد الانتظار كل هذه المدة، فيمكنك تقليل المهلة إلى 10 ثوانٍ على سبيل المثال:

 <?php

return [
    ' soap_timeout ' => 10 ,
];

قاعدة التحقق من صحة ValidVatNumber

يأتي VatCalculator أيضًا مزودًا بقاعدة التحقق من صحة ValidVatNumber لأرقام ضريبة القيمة المضافة. يمكنك استخدام هذا عند إدخال التحقق من طلب نموذج أو مثيل مدقق مستقل:

 use Mpociot  VatCalculator  Rules  ValidVatNumber ;

$ validator = Validator:: make (Input:: all (), [
    ' first_name ' => ' required ' ,
    ' last_name ' => ' required ' ,
    ' company_vat ' => [ ' required ' , new ValidVatNumber ],
]);

if ( $ validator -> passes ()) {
    // Input is correct ...
}

تحذير

يُرجع ملحق أداة التحقق من الصحة false عندما لا يتوفر معرف ضريبة القيمة المضافة (VAT ID Check SOAP API).

التكامل شريط أمين الصندوق

ملحوظة

في الوقت الحالي، لا تتوافق هذه الحزمة مع الإصدار 13 من Cashier Stripe أو الإصدارات الأحدث لأنها لا تزال تعتمد على طريقة taxPercentage القديمة التي تمت إزالتها من Cashier v13. لا يزال بإمكانك استخدامه على إصدارات Cashier Stripe الأقدم في هذه الأثناء.

إذا كنت تريد استخدام هذه الحزمة مع Laravel Cashier Stripe، فيمكنك السماح لنموذجك القابل للفوترة باستخدام سمة BillableWithinTheEU . نظرًا لأن هذه السمة تتجاوز طريقة taxPercentage للسمة Billable ، يتعين علينا أن نخبر نموذجنا صراحةً بالقيام بذلك.

 use Laravel  Cashier  Billable ;
use Mpociot  VatCalculator  Traits  BillableWithinTheEU ;
use Laravel  Cashier  Contracts  Billable as BillableContract ;

class User extends Model implements BillableContract
{
    use Billable, BillableWithinTheEU {
        BillableWithinTheEU::taxPercentage insteadof Billable;
    }

    protected $ dates = [ ' trial_ends_at ' , ' subscription_ends_at ' ];
}

باستخدام السمة BillableWithinTheEU ، يتمتع النموذج القابل للفوترة بأساليب جديدة لتعيين معدل الضريبة للنموذج القابل للفوترة.

اضبط كل شيء في أمر واحد:

• setTaxForCountry($countryCode, $company = false)

أو استخدم النهج الأكثر قابلية للقراءة والتسلسل:

• useTaxFrom($countryCode) — استخدم معدل الضريبة المحدد في البلدان
• asIndividual() — النموذج القابل للفوترة ليس شركة (افتراضي)
• asBusiness() — النموذج القابل للفوترة هو شركة صالحة

لذا، لتعيين نسبة الضريبة الصحيحة قبل اشتراك عميلك، ضع في اعتبارك سير العمل التالي:

 $ user = User:: find ( 1 );

// For individuals use :
$ user -> useTaxFrom ( ' NL ' );

// For business customers with a valid VAT ID , use :
$ user -> useTaxFrom ( ' NL ' )-> asBusiness ();

$ user -> subscription ( ' monthly ' )-> create ( $ creditCardToken );

سجل التغيير

قم بمراجعة سجل التغيير في هذا المستودع للتعرف على جميع التغييرات الأخيرة.

المشرفون

تتم صيانة VatCalculator بواسطة Dries Vints. تم إنشاؤه في الأصل بواسطة مارسيل بوسيوت.

رخصة

VatCalculator هو برنامج مفتوح المصدر مرخص بموجب ترخيص MIT.