المطوّرون

ابنِ ما تحتاجه على واجهة NextEAM API.

هي واجهة REST API نفسها التي بُنيت عليها شاشات NextEAM، وتُقدَّم تحت المسار ⁨/api⁩ في مساحة عملك. سجّل الدخول للحصول على رمز JWT، واشترك في الأحداث عبر Webhooks موقّعة، وغذِّ Power BI أو أي عميل OData بمفتاح API محدود النطاق. واجهة واحدة، ولا واجهة موازية.

كيفية المصادقة Webhooks

المصادقة

رمز JWT واحد محصور بمساحة عملك.

يحمل كل طلب رمز Bearer يصدره POST ⁨/api/auth/login⁩. يحدد الرمز نفسه مساحة العمل والمستخدم اللذين يخصّهما، فلا يوجد رأس للمنشأة تُرسله: لا يستطيع أي طلب القراءة أو الكتابة إلا في مساحة عمله.

سجّل الدخول عبر عنوان مساحة عملك (https://<workspace>.nexteam.me) أو عبر nexteam.me مع تمرير workspaceSlug في المحتوى. يتلقى الحساب المفعَّل فيه التحقق الثنائي { mfaRequired: true, partialToken } بدلاً من الرمز؛ استبدله عبر POST ⁨/api/auth/verify-totp⁩ مع الرمز المكوّن من ستة أرقام.

تنتهي صلاحية الرموز بعد 8 ساعات افتراضياً، وتُبطَل فوراً عند تسجيل الخروج من كل الأجهزة أو عند إبطالها من قِبل المسؤول. سجّل الدخول مجدداً للحصول على رمز جديد؛ لا توجد نقطة نهاية للتجديد.

الرأس المطلوبسطران

Authorization: Bearer <accessToken>
Accept: application/json

تنطبق الأدوار والصلاحيات على استدعاءات API تماماً كما تنطبق داخل التطبيق: رمز الفني لا يستطيع اعتماد أمر شراء، ورمز المشاهد لا يستطيع الكتابة.

أمثلة برمجية

curl وJavaScript وPython، والواجهة واحدة.

curl11 سطراً

# 1. Sign in. The token is scoped to your workspace and your user.
curl -s -X POST https://<workspace>.nexteam.me/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"..."}'
# -> {"accessToken":"eyJ...","user":{...}}

# 2. Call the API with it.
curl -s "https://<workspace>.nexteam.me/api/work-orders?status=OPEN&pageSize=50" \
  -H "Authorization: Bearer eyJ..." \
  -H "Accept: application/json"
# -> {"items":[...],"total":312,"page":1,"pageSize":50}

JavaScript (fetch)13 سطراً

const base = 'https://<workspace>.nexteam.me/api';

const { accessToken } = await fetch(`${base}/auth/login`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password }),
}).then((r) => r.json());

const page = await fetch(`${base}/work-orders?status=OPEN&pageSize=50`, {
  headers: { Authorization: `Bearer ${accessToken}` },
}).then((r) => r.json());

console.log(`${page.total} open work orders`);

Python (requests)15 سطراً

import requests

base = "https://<workspace>.nexteam.me/api"
token = requests.post(
    f"{base}/auth/login",
    json={"email": email, "password": password},
).json()["accessToken"]

page = requests.get(
    f"{base}/work-orders",
    params={"status": "OPEN", "pageSize": 50},
    headers={"Authorization": f"Bearer {token}"},
).json()

print(f"{page['total']} open work orders")

تسليم Webhook (من NextEAM إلى نقطة النهاية لديك)10 أسطر

POST https://your-app.example.com/webhooks/nexteam HTTP/1.1
Content-Type: application/json
X-Webhook-Signature: sha256=3f1a...   (HMAC-SHA256 of the raw body, keyed with your secret)

{
  "eventType": "work_order.completed",
  "tenantId": "...",
  "occurredAt": "2026-09-22T08:14:22.110Z",
  "payload": { ... }
}

لا توجد حزمة SDK رسمية. الواجهة JSON عادي عبر HTTPS، فأي عميل HTTP يعمل معها؛ والأمثلة أعلاه هي بالضبط ما تفعله واجهة NextEAM الأمامية نفسها.

الموارد الأساسية

موارد REST تحت المسار ⁨/api⁩.

تقبل القوائم معامِلَي الترقيم (page وpageSize) بحد أقصى 200 صف وتُجيب بـ { items, total, page, pageSize }. تُرفض الحقول غير المعروفة في الاستعلام أو المحتوى بالرمز 400، فلا يوسّع خطأ إملائي عامل تصفية دون علمك. وكل مورد محصور بمساحة العمل الموجودة في الرمز.

الموارد الأساسية
المورد	نقطة النهاية	الأفعال
الأصول	`/api/assets`	GET, POST, PATCH, DELETE
أوامر العمل	`/api/work-orders`	GET, POST, PATCH, DELETE
جداول الصيانة الوقائية	`/api/pm-schedules`	GET, POST, PATCH, DELETE
قطع الغيار	`/api/spare-parts`	GET, POST, PATCH, DELETE
أوامر الشراء	`/api/purchase-orders`	GET, POST, PATCH
فواتير المورّدين	`/api/vendor-invoices`	GET, POST
العقود	`/api/contracts`	GET, POST, PATCH, DELETE
المستخدمون والأدوار	`/api/users`	GET, POST, PATCH, DELETE
سجل التدقيق	`/api/audit-logs`	GET (قراءة فقط)
اشتراكات Webhook	`/api/admin/webhooks`	GET, POST, PATCH, DELETE
مفاتيح API	`/api/admin/api-keys`	GET, POST

القائمة الكاملة للمسارات موجودة في وثيقة OpenAPI أدناه. تقبل تغييرات حالة أوامر العمل الرأس X-Idempotency-Key (من 16 إلى 64 حرفاً) حتى لا يُطبَّق الطلب المُعاد مرتين.

Webhooks

تسليمات موقّعة، ويُعاد إرسالها عند الإخفاق.

يشترك مسؤول المنشأة بنقطة نهاية في الأحداث من الإدارة ← Webhooks (عبر POST ⁨/api/admin/webhooks⁩ مع جسم JSON يحوي { name, url, eventTypes }). يُعرض سر التوقيع مرة واحدة عند الإنشاء، ويمكن تدويره عبر POST ⁨/api/admin/webhooks⁩/:id/regenerate-secret.

كل تسليم موقّع: يحمل الرأس X-Webhook-Signature القيمة ⁨sha256=⁩ متبوعة بتوقيع HMAC-SHA256 لمحتوى الطلب الخام باستخدام سر الاشتراك. تحقّق منه قبل الوثوق بالمحتوى.

التحقق من التوقيع (Node)9 أسطر

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

// rawBody is the request body BEFORE any JSON parsing.
const expected =
  'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
const given = String(req.headers['x-webhook-signature'] ?? '');
const ok =
  given.length === expected.length &&
  timingSafeEqual(Buffer.from(given), Buffer.from(expected));

تُعاد محاولة أي استجابة غير 2xx أو انتهاء مهلة 10 ثوانٍ بعد دقيقة، ثم 5 و15 و60 دقيقة، ثم 4 ساعات، أي خمس محاولات على مدى خمس ساعات تقريباً، ثم يُوسم التسليم بالحالة FAILED. تُدرج كل المحاولات في GET ⁨/api/admin/webhooks⁩/:id/deliveries، ويرسل POST ⁨/api/admin/webhooks⁩/:id/test-fire حدث work_order.created تجريبياً لتتأكد من عمل المستقبِل لديك قبل وصول حدث حقيقي.

الأحداث GET /api/admin/webhooks/event-catalog

work_order.created
work_order.assigned
work_order.completed
purchase_requisition.submitted
purchase_requisition.approved
contract.activated
contract.expiring
permit.activated
permit.closed
calibration.recorded
calibration.failed
invoice.issued
invoice.paid
invoice.overdue
payment.recorded
approval_request.created
approval_request.step_advanced
approval_request.approved
approval_request.rejected
meter.reading_recorded
meter.threshold_crossed

تُرفض نقاط النهاية التي تشير إلى عناوين خاصة أو محلية أو ذات ارتباط محلي، ويُسقط التسليم الذي يتبع إعادة توجيه إلى أصل آخر رأس التوقيع.

مفاتيح API وتغذية BI

مفاتيح للقراءة فقط لأدوات Power BI وMetabase وعملاء OData.

لا تحل مفاتيح API محل تسجيل الدخول؛ وُجدت لأدوات BI التي لا تستطيع الاحتفاظ برمز JWT: ينشئ مسؤول المنشأة مفتاحاً من الإدارة ← مفاتيح API (عبر POST ⁨/api/admin/api-keys⁩)، ويحصر نطاقه بالكيانات المسموح له بقراءتها، ويحدد له تاريخ انتهاء، وينسخ المفتاح ⁨bi_live_⁩… مرة واحدة، فلن يُعرض مجدداً.

أرسله في الرأس X-API-Key. يبث GET ⁨/api/bi⁩/:entity ملف CSV مع ترقيم صفحات بالمفاتيح (⁨?after=<id>⁩، حتى 5000 صف في الصفحة، مع الرأسين X-BI-Next-Cursor وX-BI-Row-Count). ويقدّم GET ⁨/api/bi/odata⁩ وثيقة خدمة OData، ووثيقة البيانات الوصفية عبر ⁨/api/bi/odata⁩/$metadata، لأدوات Power BI وExcel.

تغذية BIسطران

curl -s "https://<workspace>.nexteam.me/api/bi/work_orders?limit=5000" \
  -H "X-API-Key: bi_live_..." -o work_orders.csv

الكيانات التي يمكن حصر المفتاح بها

work_orders
assets
invoices
payments
audit_log
pm_schedules
spare_parts
contracts
vendors

يُجيب المفتاح المُبطَل أو المنتهي بالرمز 401؛ ويُجيب المفتاح الصالح الذي يطلب كياناً خارج نطاقه بالرمز 403. وتُحد التغذية بـ 300 طلب في الدقيقة لكل عنوان IP.

حدود المعدل والأخطاء

سخيّة افتراضياً، وصارمة مع بيانات الاعتماد.

API، لكل عنوان IP
الحد
600 طلب / دقيقة
تسجيل الدخول، لكل حساب
الحد
5 محاولات / 15 دقيقة
تغذية BI، لكل عنوان IP
الحد
300 طلب / دقيقة

تحمل الاستجابات الرؤوس X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset؛ ويُجيب تجاوز الحد بالرمز 429 مع الرأس Retry-After. أخطاء التحقق تُرجع 400 مع تسمية الحقول المخالفة؛ والرمز المفقود أو المنتهي 401؛ والدور الذي لا يملك الصلاحية 403؛ وتعارض قيد الفرادة (رمز مكرر مثلاً) 409.

OpenAPI

المرجع المولَّد.

يولّد الخادم وثيقة OpenAPI 3 من وحدات التحكم لديه ويقدّم واجهة Swagger UI على ⁨/api/docs⁩، والوثيقة الخام على ⁨/api/docs-json⁩. تكون معطَّلة في مساحات العمل الإنتاجية ما لم يضبط المشغّل EXPOSE_SWAGGER=true، ومفعَّلة في كل بيئة غير إنتاجية.

تحتاج وثيقة مساحة عملك الإنتاجية؟ اطلبها منا وسنشاركك التصدير الحالي مع دليل API المرافق.

التكاملات

ابنِ على REST وWebhooks.

كل تكامل تقدّمه NextEAM (ترحيل إلى ERP، ومزامنة التذاكر، ولوحات BI) يستخدم الواجهة الموصوفة في هذه الصفحة ولا شيء غيرها. هذا هو الضمان: ما تستطيع بناءه هو ما نبني به نحن.

أنظمة ERP (SAP وOracle Fusion)
طلبات الشراء وأوامر الشراء وفواتير المورّدين موارد عادية: اقرأها بالرمز، واكتب مواءمة مراكز التكلفة عبر PATCH، واستجب لحدث purchase_requisition.approved أو invoice.issued عبر Webhook. أما موصّل ERP نفسه فيُحدَّد نطاقه ويُسلَّم معك أثناء التهيئة.
مكتب الخدمة وتقنية المعلومات
التذاكر وأصول تقنية المعلومات وعمليات الاكتشاف كلها متاحة تحت ⁨/api⁩، فيستطيع عميل الجرد دفع ما يجده بالطريقة نفسها التي يعمل بها استيراد CSV.
ذكاء الأعمال والتقارير
وجّه Power BI أو Metabase أو Excel إلى تغذية مفتاح API للحصول على مستخرجات حيّة محصورة بمساحة العمل، دون ملفات تصدير تحتاج إلى جدولة.

تبني شيئاً؟ أخبرنا.

يحصل شركاء التكامل على مهندس حلول يرافقهم في التنفيذ، ومراجعة قبل دخول التكامل حيّز الإنتاج.

تحدّث إلى مهندسنا developers@nexteam.me