البداية

البدء السريع

أنشئ مفتاحًا، وأرسل أول طلب، ثم أرسل فاتورة للتخليص.

أولًا: أنشئ مفتاحًا

سجّل الدخول إلى KWN بصفتك مالك الشركة، أو مستخدمًا يدير الإعدادات.
افتح الإعدادات ← التكاملات ← مفاتيح الواجهة البرمجية واختر مفتاح جديد.
سمِّه باسم النظام الذي سيستخدمه، وحدّد النطاقات التي يحتاجها — في هذا الدليل المبيعات: اعتماد وجهات الاتصال: كتابة.
انسخ المفتاح. يظهر مرة واحدة فقط؛ ولا تحتفظ KWN إلا بقيمة مجزّأة (hash) منه. احفظه في مخزن الأسرار لديك، ولا تضعه أبدًا في الشيفرة المصدرية أو في المتصفح.

تحمل الشركة عشرة مفاتيح نشطة على الأكثر. ولا يكون المفتاح أقوى أبدًا من الشخص الذي أنشأه، ولا يصل إلى تطبيق خارج خطة الشركة.

ثانيًا: أرسل أول طلب

لا يحتاج GET /me إلى أي نطاق. يجيب بالشركة التي يخصها المفتاح وما يحق له — وهو الطلب الذي ترسله كلما كان المفتاح جديدًا.

bash

curl -sS https://app.kwn.tax/api/v1/me \
  -H "X-Api-Key: $KWN_API_KEY"

json

{
  "merchant": { "id": "cm…", "name": "Al Noor Trading", "legalName": "Al Noor Trading L.L.C.", "trn": "100234567800003" },
  "key": { "id": "cm…", "name": "Shop connector", "prefix": "kwn_live_3f2", "scopes": ["sales:approve", "contacts:read"], "createdAt": "2026-10-21T08:12:00Z" },
  "capabilities": ["sales.read", "sales.write", "sales.approve", "contacts.read", "products.read"],
  "apps": ["sales", "contacts"],
  "eInvoicing": { "mode": "LIVE", "available": true }
}

ثالثًا: أضف عميلًا

يحتاج كل طلب POST ينشئ سجلًا إلى ترويسة Idempotency-Key، حتى لا تُنشئ إعادة المحاولة سجلًا مرتين. وexternalId هو معرّف السجل في نظامك؛ ابحث عنه لاحقًا بـ ?externalId=.

bash

curl -sS -X POST https://app.kwn.tax/api/v1/contacts \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "CUST-1042",
    "name": "Gulf Office Supplies L.L.C.",
    "isCompany": true,
    "trn": "100398765400003",
    "email": "accounts@gulfoffice.example",
    "city": "Dubai",
    "emirate": "DUBAI",
    "country": "AE"
  }'

رابعًا: أرسل فاتورة للتخليص

طلب واحد يتحقق من الفاتورة ويحفظها في المبيعات ويعتمدها ويرسلها إلى الهيئة الاتحادية للضرائب. ويستهلك رصيد فاتورة واحدًا، مرة واحدة — فإرسال externalId نفسه مجددًا لا يستهلك رصيدًا ثانيًا.

bash

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
  }'

http

HTTP/1.1 201 Created
{ "id": "cm…", "externalId": "INV-2026-00042", "number": "INV-2026-0042",
  "status": "PENDING", "total": 2625, "duplicate": false, "resubmitted": false, … }

خامسًا: تابع حالتها

التخليص غير متزامن. اقرأ الفاتورة الإلكترونية حتى تصبح CLEARED أو REJECTED أو FAILED — أو اعرضها كقائمة مع updatedSince لالتقاط كل التغييرات دفعة واحدة (الصفحات والمزامنة).

bash

curl -sS https://app.kwn.tax/api/v1/einvoices/<id> \
  -H "X-Api-Key: $KWN_API_KEY"
# …until "status" is CLEARED, REJECTED or FAILED