ZATCA ফাতুরা পোর্টাল ইন্টিগ্রেশন

ফেজ ২ ই-ইনভয়েসিং কমপ্লায়েন্সের জন্য সম্পূর্ণ এপিআই গাইড

সর্বশেষ আপডেট: ৩০ মার্চ, ২০২৬

📋 ইন্টিগ্রেশনের পূর্বশর্ত

বৈধ TRN সহ সক্রিয় ZATCA ট্যাক্সপেয়ার অ্যাকাউন্ট
ZATCA-অনুমোদিত প্রদানকারীর কাছ থেকে CSD সার্টিফিকেট
এপিআই ডেভেলপমেন্ট অভিজ্ঞতা সহ টেকনিক্যাল টিম
প্রোডাকশনের আগে পরীক্ষার জন্য স্যান্ডবক্স পরিবেশ অ্যাক্সেস
UBL 2.1 ফরম্যাটের জন্য XML জেনারেশন ক্ষমতা
TLV এনকোডিং এবং বেস৬৪ সহ QR কোড জেনারেশন

🔗 ফাতুরা এপিআই এন্ডপয়েন্ট

Endpoint Name	Endpoint URL	Method	Description
ক্লিয়ারেন্স (B2B)	https://api.fatoora.zatca.gov.sa/api/v1/invoice/clearance	POST	B2B ইনভয়েসের জন্য রিয়েল-টাইম ভ্যালিডেশন
রিপোর্টিং (B2C)	https://api.fatoora.zatca.gov.sa/api/v1/invoice/reporting	POST	B2C ইনভয়েসের জন্য ২৪ ঘণ্টা সাবমিশন
CSR জেনারেশন	https://api.fatoora.zatca.gov.sa/api/v1/csr	POST	সার্টিফিকেট সাইনিং রিকোয়েস্ট জেনারেট করুন
কমপ্লায়েন্স চেক	https://sandbox.fatoora.zatca.gov.sa/api/v1/compliance	POST	সাবমিশনের আগে XML ভ্যালিডেট করুন

🔐 অথেনটিকেশন (OAuth 2.0)

ফাতুরা এপিআই ক্লায়েন্ট ক্রেডেনশিয়াল সহ OAuth 2.0 ব্যবহার করে। CSD সার্টিফিকেট ইনস্টল করার পরে আপনাকে ZATCA পোর্টাল থেকে ক্রেডেনশিয়াল পেতে হবে:

আপনার ট্যাক্সপেয়ার অ্যাকাউন্ট দিয়ে ZATCA ফাতুরা পোর্টালে লগইন করুন
ডেভেলপার সেটিংস → এপিআই ক্রেডেনশিয়ালে নেভিগেট করুন
নতুন client_id এবং client_secret জেনারেট করুন
ক্রেডেনশিয়াল নিরাপদে সংরক্ষণ করুন
OAuth 2.0 এন্ডপয়েন্টের মাধ্যমে access_token পেতে ক্রেডেনশিয়াল ব্যবহার করুন
সব এপিআই কলের জন্য অথোরাইজেশন হেডারে access_token অন্তর্ভুক্ত করুন

টোকেন এন্ডপয়েন্ট: https://api.fatoora.zatca.gov.sa/oauth2/token

⚙️ ধাপে ধাপে ইন্টিগ্রেশন প্রক্রিয়া

✓ ১. ZATCA ফাতুরা পোর্টালে নিবন্ধন করুন এবং CSR প্রাপ্ত করুন

✓ ২. অনুমোদিত প্রদানকারীর কাছ থেকে CSD সার্টিফিকেট ক্রয় এবং ইনস্টল করুন (৫-১০ কার্যদিবস)

✓ ৩. ZATCA পোর্টাল থেকে এপিআই ক্রেডেনশিয়াল জেনারেট করুন (client_id, client_secret)

✓ ৪. প্রোডাকশনের আগে স্যান্ডবক্স পরিবেশে সব এপিআই কল পরীক্ষা করুন

✓ ৫. UBL 2.1 ফরম্যাটে XML ইনভয়েস জেনারেশন বাস্তবায়ন করুন

✓ ৬. ক্রিপ্টোগ্রাফিক স্ট্যাম্প সহ QR কোড জেনারেট করুন (TLV এনকোডিং + বেস৬৪)

✓ ৭. ক্লিয়ারেন্স এন্ডপয়েন্ট (B2B) বা রিপোর্টিং এন্ডপয়েন্টে (B2C) ইনভয়েস জমা দিন

✓ ৮. ZATCA রেসপন্স সঠিকভাবে হ্যান্ডেল করুন

✓ ৯. অ্যাসিঙ্ক্রোনাস রেসপন্সের জন্য ওয়েবহুক বা কলব্যাক ইউআরএল বাস্তবায়ন করুন

✓ ১০. সফল স্যান্ডবক্স পরীক্ষার পরে প্রোডাকশনে যান

💻 নমুনা এপিআই কল (PHP cURL)

ক্লিয়ারেন্স এন্ডপয়েন্টে ইনভয়েস জমা দেওয়ার জন্য সম্পূর্ণ পিএইচপি কার্ল উদাহরণ:

<?php
// ZATCA ফাতুরা এপিআই - ক্লিয়ারেন্স ইনভয়েস সাবমিশন
$access_token = "YOUR_ACCESS_TOKEN";
$xml_invoice_data = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Invoice>...</Invoice>";
$qr_base64 = "Base64EncodedQRDataHere";

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.fatoora.zatca.gov.sa/api/v1/invoice/clearance",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $access_token,
        "Content-Type: application/json",
        "Accept-Language: en"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "invoice" => base64_encode($xml_invoice_data),
        "qr_code" => $qr_base64
    ])
]);

$response = curl_exec($curl);
$http_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$curl_error = curl_error($curl);
curl_close($curl);

if ($http_code == 200) {
    $result = json_decode($response, true);
    echo "Invoice Status: " . $result["status"];
} else {
    echo "Error: HTTP $http_code - $curl_error";
}
?>

📨 ZATCA এপিআই রেসপন্স বোঝা

CLEARED

ZATCA ইনভয়েস গ্রহণ করেছে। আপনি ক্রেতার সাথে শেয়ার করতে পারেন।

Action: ডেলিভারির সাথে এগিয়ে যান

REJECTED

ইনভয়েস ভ্যালিডেশন ব্যর্থ হয়েছে। XML স্ট্রাকচার এবং ফিল্ড চেক করুন।

Action: সংশোধন করে নতুন ইনভয়েস জমা দিন

REPORTED

ইনভয়েস রিপোর্টিংয়ের জন্য গৃহীত হয়েছে (কোনো রিয়েল-টাইম ভ্যালিডেশন নেই)।

Action: আর কোনো পদক্ষেপ প্রয়োজন নেই

PENDING

ইনভয়েস পর্যালোচনাধীন। চূড়ান্ত অবস্থার জন্য অপেক্ষা করুন।

Action: আপডেট পাওয়ার জন্য ওয়েবহুক বাস্তবায়ন করুন

⚠️ এরর হ্যান্ডলিং এবং স্ট্যাটাস কোড

HTTP Code	Meaning	Solution
200	সফল - ইনভয়েস সঠিকভাবে প্রক্রিয়াকৃত	স্বাভাবিক প্রবাহ চালিয়ে যান
400	খারাপ অনুরোধ - অবৈধ XML ফরম্যাট বা অনুপস্থিত ফিল্ড	UBL 2.1 স্কিমার বিরুদ্ধে XML ভ্যালিডেট করুন
401	অননুমোদিত - অথেনটিকেশন ব্যর্থ	access_token বৈধতা চেক করুন এবং মেয়াদ উত্তীর্ণ হলে পুনরায় জেনারেট করুন
403	নিষিদ্ধ - CSD সার্টিফিকেট মেয়াদোত্তীর্ণ বা অবৈধ	তাৎক্ষণিকভাবে CSD সার্টিফিকেট পুনর্নবীকরণ করুন
429	রেট লিমিট অতিক্রম - অনেক অনুরোধ	এক্সপোনেনশিয়াল ব্যাকঅফ বাস্তবায়ন করুন
500	অভ্যন্তরীণ সার্ভার ত্রুটি - ZATCA সার্ভার সমস্যা	এক্সপোনেনশিয়াল ব্যাকঅফ সহ পুনরায় চেষ্টা করুন
503	সার্ভিস অনুপলব্ধ - রক্ষণাবেক্ষণ বা ওভারলোড	অপেক্ষা করুন এবং ৫-১০ মিনিট পর পুনরায় চেষ্টা করুন

🧪 স্যান্ডবক্স এনভায়রনমেন্ট (টেস্টিং)

লাইভে যাওয়ার আগে সবসময় ZATCA স্যান্ডবক্সে আপনার ইন্টিগ্রেশন পরীক্ষা করুন:

বিনামূল্যে টেস্ট CSD সার্টিফিকেট উপলব্ধ
সব এন্ডপয়েন্টের জন্য সিমুলেটেড এপিআই রেসপন্স
কোনো বাস্তব ট্যাক্স ভ্যালিডেশন নেই - পরীক্ষার জন্য নিরাপদ
প্রোডাকশনের মতো একই এপিআই স্ট্রাকচার

🔗 https://sandbox.fatoora.zatca.gov.sa

✅ প্রোডাকশনের জন্য সেরা অনুশীলন

মেয়াদ শেষ হওয়ার আগে স্বয়ংক্রিয় টোকেন রিফ্রেশ বাস্তবায়ন করুন
অডিট ট্রেইলের জন্য ডাটাবেসে সব এপিআই রেসপন্স সংরক্ষণ করুন
ব্যর্থ অনুরোধের জন্য এক্সপোনেনশিয়াল ব্যাকঅফ সহ পুনরায় চেষ্টা লজিক বাস্তবায়ন করুন
রেট লিমিট মনিটর করুন এবং উচ্চ ভলিউমের জন্য কিউ সিস্টেম বাস্তবায়ন করুন
অ্যাসিঙ্ক্রোনাস স্ট্যাটাস আপডেটের জন্য ওয়েবহুক ব্যবহার করুন
CSD সার্টিফিকেট মেয়াদ শেষ হওয়ার রিমাইন্ডার রাখুন
প্রোডাকশন ডেপ্লয়মেন্টের আগে স্যান্ডবক্সে সব পরিবর্তন পরীক্ষা করুন
সব এপিআই কল এবং রেসপন্সের বিস্তারিত লগ সংরক্ষণ করুন

❓ প্রায়শই জিজ্ঞাসিত প্রশ্ন

Q: এপিআই রেসপন্স পেতে কত সময় লাগে?

A: ক্লিয়ারেন্স এন্ডপয়েন্ট: ২-৫ সেকেন্ড (সিঙ্ক্রোনাস)। রিপোর্টিং এন্ডপয়েন্ট: সেকেন্ডের মধ্যে রেসপন্স (অ্যাসিঙ্ক্রোনাস), কিন্তু ইনভয়েস স্ট্যাটাস পরে ওয়েবহুকের মাধ্যমে আপডেট হতে পারে।

Q: ফাতুরা এপিআইয়ের রেট লিমিট কত?

A: স্ট্যান্ডার্ড লিমিট প্রতি সেকেন্ডে ১০টি অনুরোধ। উচ্চ ভলিউমের জন্য, ZATCA সাপোর্টের সাথে যোগাযোগ করুন। বাল্ক সাবমিশনের জন্য কিউ সিস্টেম বাস্তবায়ন করুন।

Q: একই অ্যাক্সেস টোকেন কি একাধিক অনুরোধের জন্য ব্যবহার করা যাবে?

A: হ্যাঁ, অ্যাক্সেস টোকেন সাধারণত ১ ঘন্টা পরে মেয়াদোত্তীর্ণ হয়। মেয়াদ শেষ হওয়ার আগে নতুন টোকেন পাওয়ার জন্য অটো-রিফ্রেশ লজিক বাস্তবায়ন করুন।

Q: আমার ইনভয়েস রিজেক্ট হলে কী হবে?

A: আপনি রিজেক্ট করা ইনভয়েস সম্পাদনা করতে পারবেন না। আপনার সিস্টেমে সমস্যাটি সংশোধন করুন এবং একটি নতুন ইনভয়েস নম্বর সহ একটি নতুন ইনভয়েস জমা দিন।

Q: স্যান্ডবক্সের জন্য টেস্ট CSD সার্টিফিকেট কিভাবে পাব?

A: ZATCA স্যান্ডবক্স বিনামূল্যে টেস্ট CSD সার্টিফিকেট প্রদান করে। আপনি বাণিজ্যিক প্রদানকারীদের কাছ থেকে কেনা ছাড়াই সরাসরি স্যান্ডবক্স পোর্টাল থেকে সেগুলি জেনারেট করতে পারেন।

Q: সিঙ্ক্রোনাস এবং অ্যাসিঙ্ক্রোনাস এপিআইয়ের মধ্যে পার্থক্য কী?

A: ক্লিয়ারেন্স সিঙ্ক্রোনাস - আপনি তাৎক্ষণিক রেসপন্সের জন্য অপেক্ষা করেন। রিপোর্টিং অ্যাসিঙ্ক্রোনাস - আপনি জমা দেন এবং স্বীকৃতি পান, কিন্তু চূড়ান্ত অবস্থা পরে ওয়েবহুকের মাধ্যমে আসে।

Q: ফাতুরা এপিআইয়ের জন্য কি স্ট্যাটিক আইপি প্রয়োজন?

A: না, স্ট্যাটিক আইপি প্রয়োজন নেই। তবে, নিশ্চিত করুন আপনার সার্ভারের আউটবাউন্ড আইপি ZATCA ফায়ারওয়াল দ্বারা ব্লক করা নেই।

Q: কি ওয়েবহুক ইউআরএল ফরম্যাট গ্রহণযোগ্য?

A: ZATCA শুধুমাত্র HTTPS এন্ডপয়েন্ট গ্রহণ করে। ইউআরএল সর্বজনীনভাবে অ্যাক্সেসযোগ্য হতে হবে। ইনভয়েস স্ট্যাটাস আপডেট সহ JSON পেলোড গ্রহণ করতে POST পদ্ধতি ব্যবহার করুন।

📚 সম্পর্কিত ZATCA সংস্থান

📘 Complete Guide 🔐 CSD Certificate ⚖️ Clearance vs Reporting 📄 Tax Invoice Format