الأدلة

الفوترة الإلكترونية

خلّص الفواتير الضريبية التي يصدرها نظامك لدى الهيئة الاتحادية للضرائب، عبر KWN، بطلب واحد.

تشترط الفوترة الإلكترونية في الإمارات الإبلاغ عن كل فاتورة ضريبية عبر مزوّد خدمة معتمد. وترسل KWN عبر تاكس ستار. ويأخذ POST /einvoices الفاتورة كما أصدرها نظامك تمامًا؛ ولا تتعامل أنت مع صيغة المزوّد أبدًا.

ما الذي يفعله طلب واحد

1. يتحقق من الطلب: يجب أن يكون الرقم الضريبي للبائع رقم هذه الشركة (SELLER_TRN_MISMATCH)، وأن توجد أسطر، ومع expectedTotal يجب أن يطابقه مجموع الفاتورة حتى الفلس (EINVOICE_TOTAL_MISMATCH).
2. يجد المشتري: عبر customerId، أو customer بمطابقة الرقم الضريبي ثم الاسم المطابق تمامًا، وإلا يُنشئه. ولا تُستبدل بيانات جهة اتصال قائمة أبدًا.
3. يُنشئ الفاتورة في المبيعات برقم KWN، مع الاحتفاظ برقمك مرجعًا، ويعتمدها.
4. يستهلك رصيد فاتورة واحدًا ويضع الفاتورة في الطابور نحو المزوّد. والشركة التي نفد رصيدها تُرفض بـ NO_CREDITS.
5. يجيب 201 بالفاتورة الإلكترونية في حالة PENDING.

أي رفض لا يترك أثرًا: لا جهة اتصال، ولا مسودة، ولا رصيد مستهلك.

curl -sS -X POST https://app.kwn.tax/api/v1/einvoices \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "INV-2026-00042",
    "sellerTrn": "100234567800003",
    "issueDate": "2026-10-15",
    "customer": {
      "name": "Al Noor Trading L.L.C.", "isCompany": true, "trn": "100398765400003",
      "address": "Office 1204, Bay Square", "city": "Dubai", "emirate": "DUBAI", "country": "AE"
    },
    "lines": [
      { "description": "Bookkeeping, October 2026", "quantity": 1, "unitPrice": 2500, "taxRate": 5 }
    ],
    "expectedTotal": 2625
  }'

الحالات

اقرأ واحدة عبر GET /einvoices/{id}، أو اعرض كل التغييرات عبر GET /einvoices?updatedSince=….

إرسال الفاتورة نفسها مجددًا

• externalId نفسه بالمحتوى نفسه يجيب بالفاتورة الأولى، 200 مع duplicate: true، ولا يستهلك رصيدًا ثانيًا.
• الفاتورة المرفوضة إذا أُرسلت مصحّحة بالـ externalId نفسه يُعاد تقديمها: 200 مع resubmitted: true، وتبقى على رصيدها الواحد.
• externalId نفسه بمحتوى مختلف، والأولى غير مرفوضة، يُرفض 409 EXTERNAL_ID_CONFLICT.

قبل التشغيل الفعلي

• أرسل GET /me: يجب أن تكون eInvoicing.available قيمة true. وتبقى false حتى تسجّل KWN الشركة لدى المزوّد (وإلا CLEARANCE_UNAVAILABLE). وقيمة eInvoicing.mode هي LIVE في بيئة التشغيل؛ وMOCK تعني خادم اختبار لا يصل منه شيء إلى الهيئة.
• يجب أن تكون بيانات الفوترة الإلكترونية للشركة مكتملة في KWN — الاسم القانوني والعنوان والرقم الضريبي (ويذكر EINVOICE_FIELDS_MISSING الناقص).
• يحتاج المفتاح إلى sales:approve.
• راقب الرصيد: كل فاتورة مخلّصة تستهلك واحدًا؛ وتعيد الشركة شحنه من KWN.

المشتري الذي لا يملك رقمًا ضريبيًا — شخص عادي — تُخلَّص فاتورته عبر المسار المبسّط، كما يفعل التطبيق مع فواتيره.