تخط إلى المحتوى الرئيسي
العودة إلى الرئيسية

دليل API / CLI / MCP

اربط Warrantee مع ERP والمتاجر والسكريبتات والأنظمة الداخلية والوكلاء

سجل الدخول لإنشاء مفتاحانضم كبائع

دليل التكامل الكامل

كل تكامل إنتاجي يبدأ من حساب Warrantee مسجل. أنشئ رمزاً محدود الصلاحيات من الإعدادات، احفظه كسِر، ثم استخدمه مع REST API أو السكريبتات أو الوكلاء المتوافقين مع MCP.

  1. 1سجل الدخول أو أنشئ حساب Warrantee.
  2. 2افتح الإعدادات ثم API / CLI / MCP.
  3. 3أنشئ رمز تكامل محدد الصلاحيات وانسخه مرة واحدة.
  4. 4احفظه في مدير أسرار أو متغير بيئة.
  5. 5استخدم الرمز كـ x-api-key لطلبات API أو CLI أو الوكلاء.
  6. 6راقب الاستخدام ودوّر المفاتيح وألغ الرموز غير المستخدمة.

الرابط الأساسي

https://warrantee.io/api/v1

المصادقة

الوصول للواجهة محصور بمستخدمي Warrantee المسجلين. لتكاملات ERP أو المتاجر أو الخوادم، لا تحفظ اسم مستخدم Warrantee أو كلمة مروره في النظام الخارجي. سجل الدخول مرة واحدة في Warrantee، أنشئ رمز تكامل مخصص، ثم أرسل هذا الرمز كـ x-api-key.

لا مشاركة لأسماء المستخدمين أو كلمات المرور

يسجل مسؤول التكامل الدخول إلى Warrantee فقط لإنشاء رموز التكامل أو عرضها أو إلغائها أو تدويرها. لا تستخدم بريد الدخول أو كلمة مرورك في تكاملات API أو CLI أو MCP. يجب أن يحفظ النظام المتصل رمز التكامل فقط، ويمكن تحديد صلاحياته وحدود طلباته وتاريخ انتهائه وإلغائه.

الموصى به لتكاملات الخوادم

x-api-key: YOUR_SERVER_INTEGRATION_TOKEN

جلسات التطبيق المسجلة

Authorization: Bearer YOUR_SUPABASE_ACCESS_TOKEN

حدود الطلبات: 100 طلب في الدقيقة لكل مستخدم مسجل أو رمز تكامل، مع حدود إضافية على IP لمنع الإساءة.

نموذج الأمان

كل طلب ضمان يتطلب مصادقة، ويقتصر على سجلات المالك أو البائع أو المصدر للمستخدم المحدد، مع حدود طلبات ورؤوس no-store.

تتضمن الاستجابات X-RateLimit-Limit و X-RateLimit-Remaining و X-RateLimit-Reset و Cache-Control: no-store و Vary: Authorization, x-api-key.

رموز التكامل

أنشئ حتى 20 رمزاً نشطاً من جلسة مسجلة. يظهر السر مرة واحدة، ويتم حفظ الهاش فقط، مع صلاحيات قراءة/كتابة وتاريخ انتهاء وإلغاء.

إنشاء رمز

POST /api/integration-tokens

إلغاء رمز

DELETE /api/integration-tokens/:id
{ "name": "ERP production", "scopes": ["warranties:read", "warranties:write", "claims:read", "documents:read"], "rate_limit_per_minute": 100 }

الصلاحيات: warranties:read لقراءة الضمانات، و warranties:write للإنشاء والتحديث والحذف، و claims:read لقراءة المطالبات، و documents:read لقراءة بيانات المستندات بدون روابط الملفات الخاصة.

ملاحظات التكامل

استخدم Idempotency-Key مع طلبات الإنشاء، وحافظ على رقم مرجعي ثابت متى أمكن، واستخدم رموز تكامل محددة الصلاحيات لمزامنة ERP. لا تطلب من العميل إرسال كلمة مرور Warrantee إلى شريك تكامل.

Idempotency-Key: 8f5d07d0-erp-order-102044

CLI والسكريبتات

استخدم CLI الرسمي لوارنتي في السكريبتات ووظائف ERP ومزامنة المتاجر ومهام CI. داخل هذا المستودع يعمل عبر npm scripts، وبعد تثبيت الحزمة أو npm link يمكن تشغيله كأمر warrantee. الرمز يتبع المستخدم المسجل ولا يتطلب حفظ اسم مستخدم أو كلمة مرور.

متغير البيئة الموصى به

export WARRANTEE_API_KEY="wrt_..."
npm run warrantee:cli -- auth status
./tools/warrantee/cli.mjs auth status
warrantee auth status
npm run warrantee:cli -- warranties list --status active --pretty
npm run warrantee:cli -- claims list --status pending --pretty
npm run warrantee:cli -- documents list --query receipt --pretty
npm run warrantee:cli -- warranties create \
  --product-name "Laptop" \
  --start-date 2026-01-01 \
  --end-date 2027-01-01 \
  --idempotency-key erp-order-102044
npm run warrantee:cli -- verify WR-12345

MCP واستخدام الوكلاء

شغّل خادم MCP لوارنتي عبر stdio أو استخدم نقطة MCP المستضافة على /api/mcp حتى يستطيع الوكلاء عرض الضمانات وإنشاءها وتحديثها وحذفها والتحقق منها، وعرض المطالبات، وقراءة بيانات المستندات عبر نفس مفتاح API المحدد الصلاحيات. داخل هذا المستودع استخدم npm run warrantee:mcp، وبعد تثبيت الحزمة أو npm link استخدم warrantee-mcp. يجب احترام الصلاحيات وحدود الطلبات وحدود الملكية وعدم طلب كلمات المرور.

{
  "mcpServers": {
    "warrantee": {
      "command": "npm",
      "args": [
        "run",
        "warrantee:mcp",
        "--"
      ],
      "env": {
        "WARRANTEE_API_KEY": "wrt_..."
      }
    },
    "warrantee-installed": {
      "command": "warrantee-mcp",
      "env": {
        "WARRANTEE_API_KEY": "wrt_..."
      }
    }
  }
}
curl -X POST "https://warrantee.io/api/mcp" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SERVER_INTEGRATION_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

قواعد الوكلاء

استخدم /llms.txt و /.well-known/agent-card.json و /.well-known/mcp.json و /.well-known/api-catalog و /api/mcp لاكتشاف MCP المستضاف. استخدم صفحة التحقق العامة للفحوص العامة. استخدم x-api-key فقط لبيانات الحساب المصادق عليها.

نقاط الوصول

GET/api/v1/warrantiesقائمة الضمانات
المعلمات: page, limit, status, category
POST/api/v1/warrantiesإنشاء ضمان
المعلمات: product_name*, start_date*, end_date*, description, serial_number, category, supplier, seller_name, seller_email
GET/api/v1/warranties/:idعرض ضمان
المعلمات: id (path)
PUT/api/v1/warranties/:idتحديث ضمان
المعلمات: product_name, start_date, end_date, status, category, supplier
DELETE/api/v1/warranties/:idحذف ضمان
المعلمات: id (path)
GET/api/v1/claimsعرض المطالبات
المعلمات: page, limit, status, warranty_id
GET/api/v1/claims/:idعرض مطالبة
المعلمات: id (path)
GET/api/v1/documentsعرض بيانات المستندات
المعلمات: page, limit, warranty_id, q
GET/api/v1/documents/:idعرض بيانات مستند
المعلمات: id (path)

Example Request

curl -X GET "https://warrantee.io/api/v1/warranties?page=1&limit=10" \
  -H "x-api-key: YOUR_SERVER_INTEGRATION_TOKEN"