المفاهيم

الاصطلاحات

الأسماء والمبالغ والتواريخ والمعرّفات، بالطريقة نفسها في كل مسار.

JSON

• الأجسام بصيغة JSON، وأسماء الحقول بنمط camelCase، والقيم التعدادية بأسمائها ("emirate": "DUBAI").
• الحقل الذي تتركه في طلب التعديل يحتفظ بقيمته.

المبالغ والضريبة

• كل مبلغ رقم JSON بالدرهم الإماراتي. لا تسجّل KWN أي شيء بعملة أخرى.
• أسعار الوحدات لا تشمل الضريبة. ونسبة الضريبة رقم مئوي: 5 (أساسية) أو 0 (نسبة صفرية).
• تُقرَّب المجاميع إلى خانتين عشريتين، سطرًا بسطر، كما تطبعها الفاتورة الضريبية. أرسل expectedTotal لتُرفض الفاتورة الإلكترونية بدل تخليصها إن لم يطابق مجموعها مجموعك.

التواريخ

• اليوم التقويمي بصيغة YYYY-MM-DD، ويُقرأ يومًا بتوقيت الإمارات.
• اللحظات مثل createdAt وupdatedSince بتوقيت UTC وبصيغة ISO 8601.

معرّفاتك: externalId

يمكن أن تحمل السجلات التي تنشئها معرّف نظامك في externalId: من 1 إلى 100 حرف ASCII ظاهر، فريد لكل شركة ونوع سجل، ويبقى دائمًا. ابحث عن السجل به عبر ?externalId=. والسجل الثاني بالمعرّف نفسه يُرفض 409 EXTERNAL_ID_TAKEN. وهو إلزامي في POST /einvoices: به يُعرف التكرار.

الإجراءات آمنة للتكرار

الإجراء على مستند قائم — تأكيد أو اعتماد أو إصدار أو ترحيل أو إلغاء — يجيب بـ { "alreadyDone": …, "document": … }. وإن أُرسل مرة أخرى لا يفعل شيئًا مرتين ويجيب alreadyDone: true.