المطوّرون
واجهة REST البرمجية وWebhooks
المصادقة
أنشئ مفتاحًا من الإعدادات ← الواجهة البرمجية وWebhooks. تبدأ المفاتيح بـ grw_ وتُعرض مرة واحدة فقط، فاحفظ مفتاحك في مكان آمن. يعمل المفتاح بصفة المستخدم الذي أنشأه، وبدوره، في مساحة العمل تلك. ألغِه من الصفحة نفسها.
أرسل المفتاح كرمز حامل. عنوان الأساس هو https://growlyne.com:
curl https://growlyne.com/api/v1/me \
-H "Authorization: Bearer grw_your_key"المستخدمون للقراءة فقط
403.نقاط الوصول
:object هو مفتاح كائن: contacts أو companies أو deals أو tickets، أو مفتاح كائن مخصص. يعرض GET /api/v1/objects جميعها مع مفاتيح خصائصها.
| الطريقة | المسار | الوظيفة |
|---|---|---|
| GET | /api/v1/me | مستخدم المفتاح ودوره ومساحة عمله |
| GET | /api/v1/objects | الكائنات وخصائصها ومساراتها، ومستخدمو مساحة العمل |
| GET | /api/v1/records/:object | عرض السجلات. المعاملات: limit وoffset وsearch وfilters (JSON) وsort=prop:asc|desc وlistId |
| GET | /api/v1/records/:object/:id | سجل واحد مع ارتباطاته ومهامه ورسائله |
| POST | /api/v1/records/:object | إنشاء سجل: { values, associate? } |
| PATCH | /api/v1/records/:object/:id | تحديث سجل: { values } |
| DELETE | /api/v1/records/:object/:id | أرشفة سجل |
| POST | /api/v1/records/:object/:id/notes | إضافة ملاحظة إلى السجل الزمني: { body, subject? } |
| GET | /api/v1/tasks | مهامك المفتوحة |
| POST | /api/v1/ops | تشغيل أي عملية يستخدمها التطبيق: { op, args } |
أمثلة
إنشاء جهة اتصال
curl -X POST https://growlyne.com/api/v1/records/contacts \
-H "Authorization: Bearer grw_your_key" \
-H "content-type: application/json" \
-d '{ "values": { "email": "sam@example.com", "firstname": "Sam" } }'البحث في الصفقات، الأحدث أولًا
curl "https://growlyne.com/api/v1/records/deals?search=renewal&sort=createdAt:desc&limit=50" \
-H "Authorization: Bearer grw_your_key"إضافة ملاحظة إلى سجل
curl -X POST https://growlyne.com/api/v1/records/contacts/REC_ID/notes \
-H "Authorization: Bearer grw_your_key" \
-H "content-type: application/json" \
-d '{ "subject": "Call", "body": "Discussed the Q1 rollout." }'تشغيل عملية
يتيح POST /api/v1/ops العمليات التي يستخدمها التطبيق نفسه، مثل record.merge وrecord.associate وrecord.bulkUpdate وtask.upsert. يُرجع الاسم المجهول 400 مع قائمة العمليات المتاحة.
curl -X POST https://growlyne.com/api/v1/ops \
-H "Authorization: Bearer grw_your_key" \
-H "content-type: application/json" \
-d '{ "op": "record.merge", "args": { … } }'تعتمد مفاتيح الخصائص على مساحة عملك: اقرأها من GET /api/v1/objects قبل الكتابة.
الاستجابات والأخطاء والحدود
الاستجابات الناجحة بصيغة JSON على الشكل { "data": … }. والأخطاء على الشكل { "error": "message" } مع الحالة المناسبة:
| الحالة | المعنى |
|---|---|
400 | مدخلات غير صالحة، أو عملية مجهولة |
401 | مفتاح مفقود أو غير صالح |
402 | باقة مساحة العمل لا تشمل الواجهة البرمجية |
403 | دورك لا يسمح بذلك |
404 | لا يوجد مسار أو سجل بهذا الاسم |
429 | تم بلوغ حد الاستخدام |
حد الاستخدام هو 600 طلب في الدقيقة لكل مستخدم.
Webhooks
يضيف مشرفو مساحة العمل Webhooks من الإعدادات ← الواجهة البرمجية وWebhooks: عنوان HTTPS والأحداث المراد استقبالها. ويمكن لسير العمل أيضًا استدعاء Webhook كأحد إجراءاته.
الأحداث:
| الحدث | متى |
|---|---|
record.created | إنشاء جهة اتصال أو شركة أو صفقة أو تذكرة أو سجل مخصص (من التطبيق أو الواجهة البرمجية أو نموذج أو استيراد أو صندوق الوارد) |
record.updated | تغيّر خاصية. يحتوي المتن على السجل وقائمة التغييرات |
record.deleted | حذف سجل نهائيًا |
deal.stage_changed | انتقال صفقة إلى مرحلة أخرى، مع معرّفي المرحلة السابقة والجديدة |
form.submitted | إرسال أحدهم أحد نماذجك |
كل تسليم هو طلب POST بمتن JSON على الشكل { "event", "data", "sentAt" } ومع هذه الترويسات:
| الترويسة | القيمة |
|---|---|
growlyne-event | اسم الحدث |
growlyne-delivery | معرّف فريد لهذا التسليم، مفيد لتجاهل المكرر منها |
growlyne-signature | HMAC-SHA256 بالصيغة السداسية العشرية للمتن الخام، بمفتاح هو سرّ Webhook |
تحقق من التوقيع قبل الوثوق بالحمولة:
import { createHmac, timingSafeEqual } from "node:crypto";
const expected = createHmac("sha256", process.env.GROWLYNE_WEBHOOK_SECRET)
.update(rawBody)
.digest("hex");
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["growlyne-signature"]));أجب بأي رمز 2xx خلال 10 ثوانٍ. يُعاد التسليم الفاشل (خطأ شبكة أو انتهاء مهلة أو حالة أخرى) حتى 5 مرات بفواصل متزايدة، وتُعرض التسليمات الأخيرة في الإعدادات مع حالتها.