دليل المطور – التوثيق الكامل لتكامل فواتير ضريبة المبيعات
نظرة عامة
تمكّن واجهة برمجة تطبيقات الفوترة الإلكترونية في الإمارات المطورين من ربط أنظمة ERP والمحاسبة (مثل Microsoft Dynamics NAV، Business Central، SAP، Oracle، إلخ) بمنصة الفوترة الإلكترونية المتوافقة مع الحكومة. توفر واجهة المصادقة الآمنة، ونقاط النهاية لإنشاء الفواتير، وإجراءات التحقق/معالجة الأخطاء لضمان الامتثال.
التوثيق الحالي: يغطي هذا الدليل فاتورة ضريبية قياسية التنفيذ للمعاملات بين الشركات (B2B). سيكون توثيق الفاتورة الضريبية المبسطة متاحًا قريبًا.
الرابط الأساسي: https://uae-e-invoicing.azurewebsites.net/api/v1
المصادقة
جميع استدعاءات API تتطلب رمز المصادقة (Bearer token) تم الحصول عليه من واجهة برمجة تطبيقات الرموز (Token API).
POST
auth/token/outbound
رؤوس الطلب
Content-Type: application/json
جسم الطلب
{
"client_id": "00000000-0000-0000-0000-000000000000",
"client_secret": "sample-client-secret-1234567890",
"client_uuid": "11111111-1111-1111-1111-111111111111"
}
استجابة ناجحة 200 OK
{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIsInpXVCJ9...",
"expiresIn": 3600,
"tokenType": "Bearer"
}
استخدام الرمز المميز: قم بتضمين الرمز في جميع الطلبات اللاحقة:
Authorization: Bearer {your_access_token}
تقديم فاتورة ضريبية قياسية فاتورة ضريبية قياسية
استخدم هذه النقطة الطرفية لتقديم فواتير الأعمال التجارية بين الشركات (B2B) التي تحتوي على تفاصيل ضريبية كاملة ومعلومات العميل.
POST
/outbound
الرؤوس
Content-Type: application/json
Authorization: Bearer {your_access_token}
مثال جسم الطلب
{
"invoiceNo": "INV-2025-000567",
"documentType": "388",
"documentDate": "12/31/2025",
"transactionType": "00000000",
"paymentType": "10",
"paymentDueDate": "12/31/2025",
"currency": "AED",
"currencyExchangeRate": 1.00,
"customerName": "John",
"customerCountry": "AE",
"customerCity": "Dubai",
"customerTRN": "100000000000003",
"customerState": "DXB",
"customerAddress": "Business Bay, Dubai, UAE",
"deliveryAddress1": "Office 602, Mai Tower",
"deliveryState": "DXB",
"deliveryCountry": "AE",
"deliveryCity": "Dubai",
"paymentAccountNo": "AE070331234567890123456",
"paymentAccountName": "Sample Trading LLC",
"paymentServiceProvider": "Sample Bank UAE",
"invoiceLines": [
{
"itemName": "Laptop",
"itemType": "Goods",
"vatCategory": "S",
"unitPrice": 100.00,
"unitOfMeasure": "EA",
"quantity": 1,
"lineDiscount": 5.00
}
]
}
الاستجابة الناجحة 201 Created
{
"success": true,
"message": "Invoice processing completed",
"header": {
"id": "7b5beb3f-e583-f011-b4cb-7c1e525d602c",
"success": true
},
"lines": {
"total": 1,
"successful": 1,
"failed": 0,
"details": [
{
"success": true,
"lineSequence": 1,
"id": "2a1031de-b4cb-f011-bec2-7c1e525d602c"
}
]
}
}
استجابة الخطأ 400 Bad Request
{
"success": false,
"message": "Validation failed"
}
رموز الأخطاء
| الكود |
الوصف |
| 200 |
تم إنشاء الرمز المميز بنجاح |
| 201 |
تم إنشاء الفاتورة بنجاح |
| 400 |
طلب غير صالح - معلمات مفقودة أو غير صالحة |
| 401 |
غير مصرح - رمز مميز غير صالح أو منتهي الصلاحية |
| 403 |
ممنوع - تم رفض الوصول |
| 409 |
تعارض - رقم الفاتورة موجود مسبقاً |
| 422 |
كيان غير معالج - فشل في قواعد التحقق |
| 500 |
خطأ داخلي في الخادم |
قواعد التحقق فاتورة ضريبية قياسية
- صيغة التاريخ: MM/DD/YYYY (مثال: 12/31/2025)
- رموز العملات: ISO 4217 (AED, USD, EUR)
- رموز الدول: ISO 3166-1 alpha-2 (AE, US)
- فئات ضريبة القيمة المضافة: S (قياسي), Z (صفر), E (معفي), O (خارج النطاق)
- وحدات القياس: EA (قطعة), KG (كيلوجرام), LTR (لتر), HR (ساعة), PC (قطعة)
- رقم السجل الضريبي للعميل: مطلوب للفواتير الضريبية القياسية - رقم تسجيل ضريبي مكون من 15 رقم
- تفاصيل الدفع: معلومات الحساب البنكي مطلوبة لمعاملات الأعمال التجارية بين الشركات (B2B)