العملاء في الواجهة البرمجية

نقاط النهاية

عميل موجود بمعرّفه

أرسل معرّف عميل من عملاء منشأتك. المعرّف التابع لمنشأة أخرى يُعامل تمامًا كمعرّف غير موجود: 422 customer_not_found.

JSON

نسخ تم النسخ

{
  "issue_date": "2026-11-03",
  "customer": { "id": 381 },
  "items": [{ "description": "Monthly plan", "quantity": 1, "unit_price": 99 }]
}

عميل من البيانات المباشرة

أرسل بيانات المشتري بدل المعرّف فتحفظها وندرفاتورة عميلًا جديدًا (ويسري حد العملاء في باقتك). المشتري الذي له رقم ضريبي يُحفظ منشأة، ومن لا رقم له يُحفظ فردًا. الإنشاء من البيانات المباشرة لا يحتاج إلا invoices:write.

JSON

نسخ تم النسخ

{
  "issue_date": "2026-11-03",
  "customer": {
    "name": "Example Trading Co.",
    "vat_number": "300000000000003",
    "email": "billing@example.com",
    "phone": "0500000000",
    "address_line1": "King Fahd Rd",
    "city": "Riyadh",
    "postal_code": "12345",
    "country": "SA"
  },
  "items": [{ "description": "Monthly plan", "quantity": 1, "unit_price": 99 }]
}

دون عميل

اترك customer، أو لا ترسل name، لعملية بيع لمستهلك دون اسم. تكون الفاتورة فاتورة ضريبية مبسطة.

المشترون من المنشآت والهيئة

الفاتورة لمشترٍ له رقم ضريبي سعودي صالح هي فاتورة ضريبية قياسية. في المنشأة المرتبطة بالهيئة تُعتمد قبل وصولها إلى المشتري، وتشترط الهيئة العنوان الوطني الكامل للمشتري:

البيانات المباشرة في الفاتورة لا تحمل رقم المبنى ولا الحي. للمشترين من المنشآت، أنشئ العميل مرة واحدة عبر POST /customers (أو من لوحة التحكم) بعنوانه الكامل وأرسل معرّفه. أما المشتري خارج المملكة فيحتاج الشارع والمدينة.

الأرقام الضريبية

الرقم الضريبي السعودي 15 خانة يبدأ بـ 3 وينتهي بـ 3، والرقم غير الصحيح يُرفض بـ 422. للمشتري خارج المملكة اجعل country رمز دولته (مثل AE) وأرسل رقمه الضريبي هناك، ولا يخضع للصيغة السعودية.