توثيق زرار Zoho المخصص

كل طلب يتطلب عنصرين معًا:

توكن مفقود أو غير صحيح يُرجع 401 — وعدم تطابق organization_id يُرجع 401 كمان، بنفس الرسالة بالظبط. الاختلاف بينهم مقصود إنه مايبانش: لو رجّعنا كود مختلف، الكود نفسه كان هيبقى دليل إن التوكن صحيح. لا يوجد طبقة مصادقة أخرى (لا JWT ولا صفحة API keys).

حدود معدل الطلبات (rate limit) تُطبَّق لكل توكن، وليس لكل IP — نظرًا لأن خوادم Zoho تشارك نفس عناوين الـ IP بين شركات متعددة.

النموذج الأساسي: سكريبت الـ Deluge الخاص بك يبني ويرسل العقد كاملًا — أنت من يحدد المستلم وتاريخ الإصدار والبنود، بدلًا من إرسال رقم الفاتورة وترك TaxBridge يستعلم من Zoho مرة أخرى. هذا يوفر نداءات API على حسابك وحساب Zoho، ويتيح لك تشكيل بياناتك كما تريد. يتحقق TaxBridge من العقد ويحوّله مباشرة إلى نفس الصيغة التي يستهلكها محرّك بناء المستند الضريبي — دون إعادة تفسير.

الحقول المشتركة

{
  "contract_version": 1,
  "organization_id": "20012345678",
  "zoho_invoice_id": "123456",
  "invoice_number": "INV-001",
  "issue_date": "2026-07-19",
  "currency_code": "EGP",
  "exchange_rate": 1,
  "receiver": {
    "name": "شركة العميل",
    "id": "123456789",
    "address": { "governate": "Cairo", "regionCity": "Nasr City",
                 "street": "١٢ شارع الطيران", "postalCode": "11765" }
  },
  "customer_id": "3616396000000392101",
  "lines": [
    { "description": "خدمة", "quantity": 2, "unit_price": 250,
      "discount": 50, "discount_rate": 10,
      "eta_item_code": "EG-XXXXXXXXX-001", "unit_type": "EA" }
  ],
  "extra_discount": 0,
  "po_reference": "PO-2026-01",
  "triggered_by": "user@company.com"
}

إشعارات المدين تتطلب إضافيًا referenced_invoice_number (الفاتورة الأصلية — يجب أن تكون مقبولة على الضرائب مسبقًا). إشعارات الدائن تقبله اختياريًا — يمكن إرسال إشعار دائن مستقل بدون فاتورة مرجعية (ETA تعتبره optional لنوع "C"). إشعارات المدين وحدها تقبل أيضًا reason اختياريًا.

ما الذي يوقف المستند قبل رفعه

المستند المرفوع للضرائب لا يمكن تصحيحه — يحتاج إلغاءً أو إشعار خصم. لذلك تُرفض هذه الحالات قبل الرفع، لا بعده:

نظام منفصل تمامًا عن الفواتير — بلا توقيع رقمي (الضرائب أجّلت التحقق من التوقيع للإيصالات). العقد مشابه لكن أبسط:

{
  "contract_version": 1,
  "organization_id": "20012345678",
  "zoho_receipt_id": "789012",
  "receipt_number": "RC-001",
  "issue_date": "2026-07-19",
  "currency_code": "EGP",
  "buyer": { "id": "", "name": "" },
  "payment_method": "cash",
  "lines": [
    { "description": "قهوة", "quantity": 2, "unit_price": 25 }
  ]
}

مستند مرفوض يُرجع ردًا عاديًا (وليس خطأ HTTP) لكي تستمر الدفعة — كل رسالة رفض تأتي ثنائية اللغة:

{
  "zoho_id": "12345",
  "status": "validation_error",
  "reasons": [
    "الحقل 'receiver' مطلوب / Field 'receiver' is required"
  ]
}

كل قيم status

عالِج القيم دي كلها — القيمة اللي مش في القائمة دي لا يُرجعها الـ API. الأربعة الأولى فقط تعني «وصل للضرائب».

كل رد — سواء نجح أو رُفض — يحمل جزء usage يوضح استهلاكك الحالي:

"usage": {
  "plan": "starter",
  "daily_used": 2,            "daily_limit": 20,
  "receipt_daily_used": 0,    "receipt_daily_limit": 20,
  "monthly_used": 4,          "monthly_limit": null,
  "receipt_monthly_used": 1,  "receipt_monthly_limit": null
}

الحد اليومي هو القيد الوحيد المطبَّق. الفواتير والإيصالات لكل منهما عدّاد يومي مستقل بنفس رقم الباقة (تجربة 5 · Starter 20 · Professional 100 · Enterprise 500) — فالإيصالات لا تستهلك رصيد الفواتير. يُحسب بالمستندات الفعلية لا بضغطات الزر، فيمكنك استخدام أي عدد من ضغطات الإرسال الجماعي. إشعارات الدائن والمدين لا تُحتسب على أي عدّاد. الحدود الشهرية لم تعد مطبَّقة (monthly_limit = null) وتُرسل للعلم فقط.

كل الـ endpoints الجماعية تقبل حتى 50 مستندًا في الطلب الواحد. عند بناء تكامل مخصص بأكثر من 50 مستندًا، قسّمها إلى دفعات بنفسك — تمامًا كما تفعل سكريبتات TaxBridge الجاهزة (تقسّم أي عدد تلقائيًا إلى دفعات من 50 وتُجمّع نتيجة واحدة).

{ "total": 42, "queued": 40, "results": [ /* one entry per document */ ] }