ZATCA फतूरा पोर्टल एकीकरण

चरण 2 ई-इनवॉइसिंग अनुपालन के लिए संपूर्ण एपीआई गाइड

अंतिम अपडेट: 30 मार्च, 2026

📋 एकीकरण के लिए पूर्वापेक्षाएँ

वैध TRN के साथ सक्रिय ZATCA करदाता खाता
ZATCA-अनुमोदित प्रदाता से CSD प्रमाणपत्र
एपीआई विकास अनुभव वाली तकनीकी टीम
उत्पादन से पहले परीक्षण के लिए सैंडबॉक्स वातावरण तक पहुंच
UBL 2.1 प्रारूप के लिए XML जनरेशन क्षमता
TLV एन्कोडिंग और बेस64 के साथ 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 इनवॉइस के लिए 24 घंटे सबमिशन
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

⚙️ चरण-दर-चरण एकीकरण प्रक्रिया

✓ 1. ZATCA फतूरा पोर्टल में पंजीकरण करें और CSR प्राप्त करें

✓ 2. अनुमोदित प्रदाता से CSD प्रमाणपत्र खरीदें और स्थापित करें (5-10 कार्य दिवस)

✓ 3. ZATCA पोर्टल से एपीआई क्रेडेंशियल जेनरेट करें (client_id, client_secret)

✓ 4. उत्पादन से पहले सैंडबॉक्स वातावरण में सभी एपीआई कॉल का परीक्षण करें

✓ 5. UBL 2.1 प्रारूप में XML इनवॉइस जनरेशन लागू करें

✓ 6. क्रिप्टोग्राफिक स्टैंप के साथ QR कोड जेनरेट करें (TLV एन्कोडिंग + बेस64)

✓ 7. क्लियरेंस एंडपॉइंट (B2B) या रिपोर्टिंग एंडपॉइंट (B2C) के माध्यम से इनवॉइस जमा करें

✓ 8. ZATCA प्रतिक्रियाओं को उचित रूप से संभालें

✓ 9. अतुल्यकालिक प्रतिक्रियाओं के लिए वेबहुक या कॉलबैक यूआरएल लागू करें

✓ 10. सफल सैंडबॉक्स परीक्षण के बाद उत्पादन में जाएं

💻 नमूना एपीआई कॉल (PHP cURL)

क्लियरेंस एंडपॉइंट पर इनवॉइस जमा करने के लिए एक पूर्ण 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	सेवा अनुपलब्ध - रखरखाव या अधिभार	प्रतीक्षा करें और 5-10 मिनट के बाद पुनः प्रयास करें

🧪 सैंडबॉक्स वातावरण (परीक्षण)

लाइव होने से पहले हमेशा ZATCA सैंडबॉक्स में अपने एकीकरण का परीक्षण करें:

निःशुल्क परीक्षण CSD प्रमाणपत्र उपलब्ध
सभी एंडपॉइंट के लिए अनुकरणित एपीआई प्रतिक्रियाएं
कोई वास्तविक कर सत्यापन नहीं - परीक्षण के लिए सुरक्षित
उत्पादन के समान एपीआई संरचना

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

✅ उत्पादन के लिए सर्वोत्तम अभ्यास

समाप्ति से पहले स्वचालित टोकन रीफ्रेश लागू करें
ऑडिट ट्रेल के लिए डेटाबेस में सभी एपीआई प्रतिक्रियाएं संग्रहीत करें
असफल अनुरोधों के लिए एक्सपोनेंशियल बैकऑफ के साथ पुनः प्रयास तर्क लागू करें
दर सीमा की निगरानी करें और उच्च मात्रा के लिए क्यू सिस्टम लागू करें
अतुल्यकालिक स्थिति अपडेट के लिए वेबहुक का उपयोग करें
CSD प्रमाणपत्र समाप्ति रिमाइंडर रखें
उत्पादन परिनियोजन से पहले सैंडबॉक्स में सभी परिवर्तनों का परीक्षण करें
सभी एपीआई कॉल और प्रतिक्रियाओं के विस्तृत लॉग बनाए रखें

❓ अक्सर पूछे जाने वाले प्रश्न

Q: एपीआई प्रतिक्रिया में कितना समय लगता है?

A: क्लियरेंस एंडपॉइंट: 2-5 सेकंड (सिंक्रोनस)। रिपोर्टिंग एंडपॉइंट: सेकंड के भीतर प्रतिक्रिया (एसिंक्रोनस), लेकिन इनवॉइस स्थिति बाद में वेबहुक के माध्यम से अपडेट हो सकती है।

Q: फतूरा एपीआई के लिए दर सीमा क्या है?

A: मानक सीमा 10 अनुरोध प्रति सेकंड है। उच्च मात्रा के लिए, ZATCA समर्थन से संपर्क करें। बल्क सबमिशन के लिए क्यू सिस्टम लागू करें।

Q: क्या मैं एक ही एक्सेस टोकन का उपयोग कई अनुरोधों के लिए कर सकता हूँ?

A: हाँ, एक्सेस टोकन आमतौर पर 1 घंटे के बाद समाप्त हो जाते हैं। समाप्ति से पहले नया टोकन प्राप्त करने के लिए ऑटो-रीफ्रेश तर्क लागू करें।

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