واجهة برمجة Aqid ERP

واجهة REST بإصدارات للدفاتر: أصدر الفواتير والفواتير الإلكترونية لزاتكا من نظامك، وسجّل المدفوعات، واستخرج التقارير، واعلم بكل تغيير عبر webhook. والعقد الكامل وثيقة OpenAPI تقرؤها وتجرّبها.

المرجع التفاعلي للواجهة وثيقة OpenAPI (JSON)

العنوان الأساسي: https://aqiderp.com/api/v1
الصيغة: JSON عبر HTTPS. المبالغ نصوص عشرية دائماً مثل "1150.00"، والخادم يجري كل الحسابات.
المصادقة: مفتاح API (Bearer mzk_live_… أو mzk_test_…) بصلاحية قراءة أو كتابة أو كلتيهما، أو رمز وصول OAuth منحته شركة لتطبيقك.
الباقات: الواجهة متاحة في باقتي النمو والمميزة. الأسعار

البداية السريعة

أنشئ مفتاحاً في التطبيق من المبيعات ← واجهة الفوترة ← مفاتيح API. يُعرض مرة واحدة ونحتفظ ببصمته فقط. ابدأ بمفتاح اختبار: عملياته تُفحص وتُسعَّر ولا يُحفظ منها شيء ولا يُرسل إلى زاتكا.

1. تحقّق من المفتاح

curl -s https://aqiderp.com/api/v1/whoami \
  -H "Authorization: Bearer $AQID_API_KEY"

2. اعثر على شركتك (الكيان)

curl -s https://aqiderp.com/api/v1/entities \
  -H "Authorization: Bearer $AQID_API_KEY"

3. أنشئ مسودة فاتورة

curl -s -X POST https://aqiderp.com/api/v1/entities/$ENTITY_ID/invoices \
  -H "Authorization: Bearer $AQID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-467a-9f9c-1b0c0f5a1e11" \
  -d '{"contactId":"'$CONTACT_ID'","issueDate":"2026-10-16",
       "lines":[{"description":"Consulting","qty":"2","unitPrice":"500.00","taxCode":"SA-STD"}]}'

4. اعتمدها: الرقم والقيد، وفي السعودية تحقق زاتكا ورمز QR

curl -s -X POST https://aqiderp.com/api/v1/invoices/$INVOICE_ID/approve \
  -H "Authorization: Bearer $AQID_API_KEY"

يعيد الاعتماد رقم الفاتورة المتسلسل بلا فجوات وقيدها وبيانات رمز QR. ثم تُعتمد الفاتورة السعودية أو تُبلَّغ لدى زاتكا، وتصلك النتيجة عبر webhook.

ما تشترك فيه كل الطلبات

مفاتيح الاختبار

مفتاح mzk_test_ يقرأ كالمفتاح الحي. وعمليات الكتابة على الفواتير وعروض الأسعار والإشعارات الدائنة والفواتير الإلكترونية تُفحص وتُسعَّر وتجيب "livemode": false؛ فلا يُحفظ شيء ولا يُرقَّم ولا يُرسل.

منع التكرار

أرسل ترويسة Idempotency-Key مع عمليات الكتابة. فالطلب المكرر يعيد الاستجابة الأولى مع Idempotency-Replayed: true، فلا تصنع إعادة المحاولة بعد انقطاع فاتورة ثانية.

التصفح

القوائم بمؤشر: مرّر limit ثم nextCursor من الصفحة التي لديك. والسجلات المضافة أثناء التصفح لا تُتخطّى ولا تتكرر.

الأخطاء

بصيغة RFC 7807 application/problem+json مع رمز آلي (BAD_VAT وZATCA_VALIDATION وUPGRADE_REQUIRED…). ورفض زاتكا يسرد ملاحظات زاتكا نفسها.

حدود الطلبات

دلو رموز لكل مفتاح: 120 طلباً تتجدد خلال 60 ثانية افتراضياً. تحمل الاستجابات X-RateLimit-Limit وX-RateLimit-Remaining، ويضيف الرد 429 ترويسة Retry-After.

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

المبالغ نصوص عشرية، ورموز الضريبة تسمّي النسبة (SA-STD لنسبة 15% السعودية). وفواتير العملات الأجنبية تأخذ العملة وسعر الصرف، وتذهب الفاتورة السعودية إلى زاتكا بضريبتها بالريال.

الموارد

الفواتير	`GET/POST /v1/entities/{entityId}/invoices · POST /v1/invoices/{id}/approve`
فواتير زاتكا الإلكترونية	`POST /v1/entities/{entityId}/einvoices · POST …/einvoices/validate · GET /v1/einvoices/{id}/xml`
جهات الاتصال	`GET/POST /v1/contacts · PATCH /v1/contacts/{id}`
المدفوعات	`POST /v1/entities/{entityId}/payments · POST /v1/payments/{id}/allocations`
فواتير الموردين	`GET/POST /v1/entities/{entityId}/bills · POST /v1/bills/{id}/approve`
القيود اليدوية	`GET/POST /v1/entities/{entityId}/journals`
الحسابات البنكية وكشوفها	`GET/POST /v1/entities/{entityId}/bank-accounts · POST /v1/bank-accounts/{id}/statements`
التقارير	`GET /v1/entities/{entityId}/reports/{profit-and-loss \| balance-sheet \| cash-flow \| vat-return}`
الموظفون وقسائم الرواتب	`GET/POST /v1/entities/{entityId}/employees · GET /v1/payslips/{id}/pdf`
المستودعات والمخزون	`GET/POST /v1/entities/{entityId}/warehouses · GET …/stock-levels`

وأيضاً عروض الأسعار والإشعارات الدائنة والمدينة وأوامر الشراء والمصروفات والتحويلات البنكية والأصناف ومراكز التكلفة والمشاريع والفروع ونسب الضريبة. ويسرد المرجع التفاعلي كل مسار وحقل.

فوترة زاتكا الإلكترونية من نظامك

يستطيع نظام فوترة أو نقطة بيع أو متجر إلكتروني إرسال مبيعاته إلى الواجهة واستلام فواتير متوافقة مع زاتكا: تُفحص أولاً (POST …/einvoices/validate يعرض ملاحظات زاتكا دون إصدار)، ثم تُرقَّم وتُوقَّع وتُعتمد (B2B) أو تُبلَّغ (B2C) في طلب واحد، مع ملف XML الموقّع للتنزيل.

الفوترة الإلكترونية (هيئة الزكاة)

Webhooks

سجّل نقطة استقبال في صفحة واجهة الفوترة واختر الأحداث. التسليم مرة واحدة على الأقل مع إعادة المحاولة بتباعد متزايد؛ أزل التكرار بترويسة AqidERP-Event-Id. ويجب أن تكون النقطة متاحة للعموم.

invoice.approved · invoice.paid · invoice.voided · credit_note.approved · bill.approved · payment.received · payment.sent · quote.accepted · quote.declined · einvoice.cleared · einvoice.reported · einvoice.rejected · contact.created · contact.updated · bank_transfer.posted

كل تسليم موقّع: تحمل ترويسة AqidERP-Signature طابعاً زمنياً وHMAC-SHA256 لـ "<الطابع>.<المحتوى الخام>" بسرّ نقطتك. تحقّق منه بمقارنة ثابتة الزمن وارفض الطوابع القديمة:

import { createHmac, timingSafeEqual } from "node:crypto";

// header: the AqidERP-Signature header, "t=<unix>,v1=<hex>"
export function verify(secret, rawBody, header, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(parts.v1 ?? "", "utf8");
  return a.length === b.length && timingSafeEqual(a, b);
}

تطبيقات OAuth

التطبيق الذي لم تكتبه الشركة، كنقطة بيع أو موصل متجر، يأخذ رمزاً بدل المفتاح: تسجّله الشركة من الإعدادات ← المطوّرون، ويعيد تدفق رمز التفويض مع PKCE (إلزامي لكل عميل) رمز وصول بالصلاحيات المطلوبة فقط، مثل invoices:write contacts:read.

GET https://aqiderp.com/oauth/authorize?response_type=code&client_id=mzc_…
    &redirect_uri=https://your-app.example/callback&scope=invoices:write%20contacts:read
    &state=…&code_challenge=…&code_challenge_method=S256

POST https://aqiderp.com/api/oauth/token   (grant_type=authorization_code, code_verifier=…)

ابنِ على دفاترك

ابدأ الآن مجانًا الوصول إلى الواجهة ضمن باقتي النمو والمميزة