المطورون

ابنِ على Granetra

واجهة برمجة تطبيقات REST نظيفة وwebhooks موقعة لوكلاء الدعم الذكيين لديك. أنشئ مفتاحًا في صفحة المطورين في لوحة التحكم الخاصة بك وابدأ البناء في دقائق.

احصل على مفتاح APIاقرأ المرجع
https://granetra.com/api/v1

واجهة برمجة تطبيقات REST

قم بإدراج البوتات، قراءة المحادثات والنصوص، إرسال رسائل الدردشة، وإدارة الإجراءات الوكيلة — كل ذلك باستخدام مفتاح حامل محدد.

webhooks موقعة

احصل على POST بتوقيت-HMAC في اللحظة التي تبدأ فيها المحادثة، أو عندما يطلب زائر إنسانًا، أو يتم التقاط عميل محتمل — مع محاولات وإدارة تسليم.

مصممة للأتمتة

قم بتدوير المفاتيح، وقفلها على عناوين IP الخاصة بالخادم لديك، وقم بتوجيه تكوين البوت من CI/CD. كل ما تفعله لوحة التحكم، عبر API.

مرجع API

عنوان URL الأساسي: https://granetra.com/api/v1

المصادقة

مرر مفتاح API الخاص بك كرمز حامل في كل طلب:

Authorization: Bearer gk_your_key_here

المفاتيح محددة النطاق. الطلب إلى نقطة نهاية ليس مفتاحك محدد النطاق لها يعيد 403 insufficient_scope. النطاقات المتاحة: bots:read, conversations:read, chat:write, actions:read, actions:write.

نقاط النهاية

GET/botsإدراج البوتات الخاصة بك
GET/bots/:idبوت واحد
GET/bots/:id/conversationsإدراج المحادثات
GET/conversations/:idنص المحادثة
POST/chatإرسال رسالة، الحصول على رد
GET/bots/:id/actionsإدراج الإجراءات الوكيلة للبوت
POST/bots/:id/actionsإنشاء إجراء
PATCH/bots/:id/actions/:actionIdتحديث إجراء
DEL/bots/:id/actions/:actionIdحذف إجراء

إرسال رسالة دردشة

curl -X POST https://granetra.com/api/v1/chat \
  -H "Authorization: Bearer gk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "00000000-0000-0000-0000-000000000000",
    "message": "What are your opening hours?"
  }'

# → { "conversation_id": "…", "message_id": "…", "fallback": false, "reply": "We're open 9–5 Mon–Fri." }
# Pass the returned conversation_id back to continue the same thread.

إدارة الإجراءات الوكيلة

قم بتسجيل نقاط النهاية HTTPS الخاصة بك كأدوات يمكن للبوت استدعاؤها أثناء المحادثة — قم بإدارتها من CI/CD بدلاً من لوحة التحكم. يتطلب نطاق actions:write وبوت على خطة Scale.

curl -X POST https://granetra.com/api/v1/bots/BOT_ID/actions \
  -H "Authorization: Bearer gk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lookup_order",
    "description": "Look up an order status by number",
    "url": "https://api.yourstore.com/orders",
    "method": "GET",
    "parameters": [
      { "name": "order_number", "type": "string", "description": "The order #", "required": true }
    ]
  }'

# → { "ok": true, "id": "…" }

أحداث Webhook

كل تسليم هو JSON POST مع هذا الظرف:

{
  "id": "delivery-uuid",
  "type": "handoff.requested",
  "created": "2026-07-20T12:00:00.000Z",
  "data": { "bot_id": "…", "conversation_id": "…" }
}

أنواع الأحداث: conversation.created, handoff.requested, lead.captured.

التحقق من التوقيعات

يحمل كل Webhook رأس X-Granetra-Signature بالشكل t=<unix>,v1=<hmac>. أعد حساب HMAC-SHA256 لـ `${t}.${rawBody}` باستخدام سر توقيع نقطة النهاية الخاصة بك وقارن:

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

استجب بأي 2xx للاعتراف. يتم إعادة المحاولة في حالة عدم وجود 2xx أو حدوث مهلة مع زيادة زمنية؛ يتم تعطيل نقطة النهاية تلقائيًا بعد فترة طويلة من الفشل.

تأمين مفتاحك إلى عناوين IP الخاصة بك

يمكن أن يحمل المفتاح قائمة عناوين IP مسموح بها اختيارية (عناوين IPv4 فردية أو نطاقات CIDR). عند تعيينها، يتم رفض الطلبات من أي عنوان آخر مع 403 ip_not_allowed. قم بإدارتها لكل مفتاح في لوحة التحكم.