انتقل إلى المحتوى

المطوّرون

واجهة REST البرمجية وWebhooks

اقرأ كل سجل في مساحة عملك واكتبه من نصوصك البرمجية وأدواتك، وتلقَّ إشعارًا عند حدوث تغييرات. الواجهة البرمجية وWebhooks متاحتان في Starter وPro وBusiness.
في هذه الصفحة

المصادقة

أنشئ مفتاحًا من الإعدادات ← الواجهة البرمجية و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-signatureHMAC-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 مرات بفواصل متزايدة، وتُعرض التسليمات الأخيرة في الإعدادات مع حالتها.