حاسبتك على موقعك — دليل المطورين

ثلاث طرق لعرض حاسبات PriceKit خارج PriceKit: كود التضمين لأي موقع، وإضافة ووردبريس، والـ API. في كل الطرق يُحسب السعر على خادم PriceKit فقط، ولا تصل المعادلات أو أسعار الخيارات المخفية إلى المتصفح. تحتاج اشتراك PriceKit Pro (التجربة تشملها).

1. كود التضمين

كل حاسبة مفعّلة تظهر على موقعك تلقائياً بآخر نسخة محفوظة. في PriceKit: «موقعك والـ API» ← «حاسباتك على موقعك» ← اكتب نطاق موقعك ← انسخ كود التضمين للحاسبة. لا تظهر الحاسبة إلا داخل هذه النطاقات (حماية المتصفح frame-ancestors)، ويتعدّل ارتفاعها تلقائياً.

<div data-pricekit="https://pricekit-clients.ghosounmedia.com/f/LINK-TOKEN"></div>
<script src="https://pricekit-clients.ghosounmedia.com/assets/embed.js" async></script>

خيارات: data-lang="en" للغة، وdata-title لعنوان الإطار (لقارئات الشاشة). المظهر و CSS المخصص ورسالة الشكر والانتقال بعد الإرسال تُضبط في PriceKit: «موقعك والـ API».

2. إضافة ووردبريس

نزّل الإضافة من PriceKit: «موقعك والـ API» ← المفاتيح ← «تحميل إضافة ووردبريس»، وارفعها في ووردبريس وفعّلها.
أنشئ «مفتاحاً سرياً» في PriceKit وألصقه في ووردبريس: الإعدادات ← PriceKit.
أضف كتلة «حاسبة PriceKit»، أو الـ shortcode:

[pricekit calculator="CALCULATOR-ID" product="123" lang="ar"]

تُعرض الحاسبة جزءاً من الصفحة فتأخذ خطوط القالب وألوانه. product (اختياري) يُظهر «أضف للسلة» في ووكومرس بالسعر المحسوب من PriceKit (موقّع، لا يمكن للمتصفح تغييره). يمكنك إضافة مفاتيح Turnstile أو reCAPTCHA الخاصة بموقعك في إعدادات الإضافة.

3. API v1

العنوان: https://pricekit-clients.ghosounmedia.com/v1 — JSON بترميز UTF-8.

المفتاح	أين	الصلاحية
`Authorization: Bearer sk_…`	خادم موقعك فقط	كل شيء: القائمة، النموذج، الحساب، إرسال الطلبات، السعر الموقّع
`X-PriceKit-Key: pk_…`	المتصفح، من نطاقاتك المسجّلة فقط (https)	القائمة والنموذج والحساب فقط — لا يرسل طلبات

الطلب	ماذا يفعل
`GET /v1/calculators`	حاسبات الحساب على المواقع (كل حاسبة مفعّلة تلقائياً، وروابط «على موقعي»).
`GET /v1/calculators/{id}?lang=ar`	النموذج: الحقول والخيارات وبيانات التواصل والنصوص — بلا أي تسعير.
`POST /v1/calculators/{id}/calculate`	حالة الحقول، وأسعار الخيارات إن سمحت بها، والسعر النهائي عند الطلب.
`POST /v1/calculators/{id}/requests`	إرسال طلب عميل (المفتاح السري فقط) — يصل لـ «طلبات العملاء».
`POST /v1/calculators/{id}/price`	سعر موقّع لووكومرس أو متجرك (المفتاح السري فقط).
`GET /v1/public-key`	المفتاح العام للتحقق من السعر الموقّع.

curl

curl -H "Authorization: Bearer sk_…" https://pricekit-clients.ghosounmedia.com/v1/calculators

curl -H "Authorization: Bearer sk_…" -H "Content-Type: application/json" \
  -d '{"answers":{"bedrooms":"two","extras":["oven"]},"requestPrice":true,"language":"ar"}' \
  https://pricekit-clients.ghosounmedia.com/v1/calculators/CALCULATOR-ID/calculate

curl -H "Authorization: Bearer sk_…" -H "Content-Type: application/json" \
  -d '{"answers":{"bedrooms":"two"},"contact":{"name":"Samer","phone":"0599123456","email":"samer@example.com"},
       "language":"ar","idempotencyKey":"9f1c…","priceShown":true,"elapsedMs":42000,"visitor":{"ip":"203.0.113.5"}}' \
  https://pricekit-clients.ghosounmedia.com/v1/calculators/CALCULATOR-ID/requests

الإجابات: نص أو رقم كنص ("12.5")، وصح/خطأ، ومفتاح الخيار للاختيار الواحد، ومصفوفة مفاتيح للاختيار المتعدد، والتاريخ بالشكل yyyy-MM-dd.

لإرسال الطلبات: أرسل عنوان الزائر (visitor.ip) والزمن منذ عرض النموذج (elapsedMs) واترك حقل website فارغاً — حماية خفية تمنع الإرسال الآلي. idempotencyKey يمنع تكرار الطلب نفسه.

HTTP	error	المعنى
401	invalid_key	مفتاح غير صحيح أو ملغى، أو نوع مفتاح خاطئ.
403	origin_not_allowed · secret_key_required · unavailable	نطاق غير مسجّل لمفتاح الموقع؛ عملية تحتاج المفتاح السري؛ الحاسبات متوقفة (الاشتراك أو إيقاف المدير).
404	not_found	حاسبة غير موجودة لهذا الحساب أو غير نشطة.
400	invalid	أخطاء في الإجابات أو بيانات التواصل (issues: field + message).
409	price_hidden	الحاسبة لا تُظهر السعر النهائي، فلا سعر موقّع.
429	rejected	أوقفته الحماية الخفية (إرسال آلي أو متكرر).

4. التحقق من السعر الموقّع

الرد يحتوي payload (نص JSON فيه الحاسبة والإجابات والإجمالي والعملة وانتهاء الصلاحية) وsignature (ECDSA P-256 / SHA-256، ترميز DER، base64) على النص "PriceKit.Price.v1\n" + payload. تحقق دائماً على خادمك:

// PHP
$pem = json_decode(file_get_contents('https://pricekit-clients.ghosounmedia.com/v1/public-key'), true)['pem'];
$ok  = openssl_verify("PriceKit.Price.v1\n" . $payload, base64_decode($signature), $pem, OPENSSL_ALGO_SHA256) === 1;
$data = json_decode($payload, true);   // check $data['calculator'], $data['expiresAt'] > time(), $data['currency']

// Node.js
const { verify } = require('crypto');
const ok = verify('sha256', Buffer.from('PriceKit.Price.v1\n' + payload), pem, Buffer.from(signature, 'base64'));

5. Webhooks

في PriceKit: «موقعك والـ API» ← Webhooks ← أضف عنوان https. كل طلب عميل جديد يُرسل كـ POST بـ JSON، مع إعادة المحاولة حتى ساعتين تقريباً إن لم يرد نظامك بـ 2xx.

X-PriceKit-Event: request.created        (ping for "send a test")
X-PriceKit-Delivery: 2f6c…
X-PriceKit-Signature: t=1767225600,v1=5d41402abc…   // HMAC-SHA256(secret, t + "." + body), hex

{"id":"…","event":"request.created","createdAt":"…","data":{"request":{
  "id":"…","number":"1C41F42E","status":"New","calculator":"…","link":{"kind":"website",…},
  "contact":{"name":"…","phone":"…","email":"…"},"answers":[{"field":"…","label":"…","value":"…"}],
  "price":{"total":"120.00","currency":"SAR","display":"120.00 SAR"},"receiptUrl":"…"}}}

// Node.js check
const [t, v1] = header.split(',').map(p => p.split('=')[1]);
const ok = crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(
  crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex')));

6. الاستخدام العادل والخصوصية

لا حدود ظاهرة: عدد الحاسبات والزوار ومرات الحساب والطلبات غير محدود ضمن «الاستخدام العادل» في شروط PriceKit. الحماية الخفية تمنع الإرسال الآلي فقط. نحفظ أعداداً يومية لكل موقع، وعناوين الزوار مشفّرة فقط (تُحذف بعد 30 يوماً).

إعدادات الموقع في PriceKit · PriceKit