الربط مع المرحلة الثانية للفوترة الإلكترونية عبر واجهة برمجية

المرحلة الثانية باختصار

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

الإشعارات الدائنة والمدينة تتبع نوع الفاتورة التي تصححها.

ما تتولاه وندرفاتورة

• ربط منشأتك بالهيئة مرة واحدة من لوحة التحكم، برمز التحقق لمرة واحدة (OTP) من بوابة فاتورة.
• تحديد نوع الفاتورة: المشتري الذي له رقم ضريبي سعودي صالح، أو التصدير، يعني فاتورة ضريبية؛ وغياب المشتري أو غياب رقمه يعني فاتورة مبسطة، ضمن أنواع الفواتير التي هُيئت لها منشأتك.
• إرسال كل فاتورة صادرة ومتابعتها، وإعادة المحاولة عند الأعطال المؤقتة، وعرض رسائل الهيئة نفسها عند رفض الفاتورة.
• حجز الفاتورة الضريبية عن المشتري حتى تُعتمد، فلا يتسلم المشتري مستندًا غير معتمد.

ما يفعله ربطك

1. أنشئ الفاتورة بـ POST /invoices مع external_reference.
2. اقرأ zatca في الرد: يبين deliverable هل ترسلها الآن.
3. إن لم تكن قابلة للتسليم بعد، اقرأ الفاتورة مجددًا بفواصل متزايدة حتى تصبح كذلك، أو حتى تصبح حالتها rejected.
4. عند rejected اعرض errors (رسائل الهيئة) على من يصحح البيانات في لوحة التحكم.

curl https://fatoora.tw.sa/api/v1/invoices/1024 \
  -H "Authorization: Bearer wbk_test_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

<?php
$response = $client->get('invoices/1024', ['http_errors' => false]);
$invoice = json_decode((string) $response->getBody(), true)['data']['invoice'] ?? null;

if ($invoice && $invoice['zatca']['deliverable']) {
    // Safe to hand to the buyer: send $invoice['public_url'].
}

const res = await fetch("https://fatoora.tw.sa/api/v1/invoices/1024", {
  headers: {
    Authorization: `Bearer ${process.env.WONDERFATOORA_API_KEY}`,
    Accept: "application/json",
  },
});
const { ok, data, error } = await res.json();
if (ok && data.invoice.zatca.deliverable) {
  // Safe to hand to the buyer: data.invoice.public_url
}

res = requests.get(
    "https://fatoora.tw.sa/api/v1/invoices/1024",
    headers={"Authorization": f"Bearer {os.environ['WONDERFATOORA_API_KEY']}",
             "Accept": "application/json"},
    timeout=30,
)
invoice = res.json().get("data", {}).get("invoice")
if invoice and invoice["zatca"]["deliverable"]:
    print(invoice["public_url"])

البيانات التي تحتاجها فواتيرك

• البائع: رقمك الضريبي وعنوانك الوطني، يُكملان مرة واحدة في ملف المنشأة.
• الفواتير الضريبية: الرقم الضريبي للمشتري وعنوانه الوطني الكامل (الشارع، ورقم المبنى من 4 أرقام، والحي، والمدينة، والرمز البريدي من 5 أرقام). أنشئ هؤلاء المشترين عبر POST /customers أو من لوحة التحكم، وأرسل معرّفاتهم. راجع العملاء.
• البنود الخاضعة للنسبة الصفرية أو المعفاة: رمز سبب الهيئة في vat_exemption_code.
• العملة الأجنبية: سعر صرف إلى الريال حتى تُبيَّن الضريبة بالريال.