دليل تكامل التنفيذ اليدوي لمفاتيح الترخيص

• منتج يتضمن استحقاق License Key مضبوطًا على تنفيذ manual.
• مستمع webhook يكتشف متى ينتظر أحد العملاء مفتاحًا.
• استدعاء تنفيذ يسلّم المفتاح ويُخطر العميل تلقائيًا.

​

آلية العمل

​

المتطلبات الأساسية

• حساب تاجر على Dodo Payments.
• مفتاح API، يتم إنشاؤه ضمن Developer → API Keys وتخزينه في DODO_PAYMENTS_API_KEY، وسر توقيع webhook من Developer → Webhooks، يتم تخزينه في DODO_PAYMENTS_WEBHOOK_KEY. راجع دليل إنشاء مفتاح API.
• نقطة نهاية في الواجهة الخلفية يمكنها استقبال webhooks.

​

الخطوة 1 — إنشاء استحقاق License Key في الوضع اليدوي

• Dashboard
• API

1

Open Entitlements

انتقل إلى Entitlements في لوحة التحكم وانقر على + لإنشاء استحقاق.

2

Choose License Key

حدد License Keys وأدخل Name. يحتوي النموذج على الحقول التالية:

• Fulfillment Mode: Automatic افتراضيًا. هذا هو الإعداد الذي يفعّل التسليم اليدوي، ويمكنك تغييره في الخطوة التالية.
• License Length: المدة التي يظل خلالها كل مفتاح مُصدر صالحًا، أو No expiration.
• Activations Limit: الحد الأقصى لعدد عمليات التفعيل لكل مفتاح، أو Unlimited.
• Activation Message: رسالة اختيارية موجّهة إلى العميل تظهر عند تفعيل العميل للمفتاح، ويتم تضمينها في رسالة البريد الإلكتروني الخاصة بمفتاح الترخيص.

3

Set Fulfillment Mode to Manual

افتح القائمة المنسدلة Fulfillment Mode وغيّرها من Automatic إلى Manual. يعتمد باقي هذا الدليل على هذا الإعداد: بدونه، ينشئ Dodo Payments المفاتيح ويرسلها بالبريد الإلكتروني تلقائيًا، ولا ينشئ أي منحة معلّقة. عند تحديد Manual، تنشئ كل عملية شراء منحة Pending لتسليمها. انقر على Create Entitlement للحفظ.

أنشئ الاستحقاق مع ضبط integration_config.fulfillment_mode على manual.

Node.js

Python

cURL

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

const entitlement = await client.entitlements.create({
  name: 'Pro License (Manual)',
  integration_type: 'license_key',
  integration_config: {
    fulfillment_mode: 'manual',
    activations_limit: 5,
    duration_count: 1,
    duration_interval: 'Year',
  },
});

console.log(entitlement.id); // ent_...

See all 19 lines

​

الخطوة 2 — إرفاق الاستحقاق بمنتج

​

الخطوة 3 — اكتشاف المنح المعلّقة

​

الاستماع إلى webhook

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.DODO_PAYMENTS_WEBHOOK_KEY!);

export async function POST(request: Request) {
  const rawBody = await request.text();
  const headers = {
    'webhook-id': request.headers.get('webhook-id') || '',
    'webhook-signature': request.headers.get('webhook-signature') || '',
    'webhook-timestamp': request.headers.get('webhook-timestamp') || '',
  };

  await webhook.verify(rawBody, headers);
  const event = JSON.parse(rawBody);

  // A customer bought a manual-mode license key and is waiting for it.
  if (
    event.type === 'entitlement_grant.created' &&
    event.data.integration_type === 'license_key' &&
    event.data.status === 'Pending'
  ) {
    // queueLicenseKeyFulfillment is your own job queue, not part of the SDK.
    await queueLicenseKeyFulfillment({
      grantId: event.data.id,
      customerId: event.data.customer_id,
    });
  }

  return new Response('ok');
}

​

أو الاستعلام عن List Grants API

// Uses the client from Step 1.
const pending = await client.entitlements.grants.list('ent_license_key_id', {
  status: 'Pending',
});

for (const grant of pending.items) {
  console.log(`Grant ${grant.id} for customer ${grant.customer_id} needs a key`);
}

curl -G https://test.dodopayments.com/entitlements/ent_license_key_id/grants \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  --data-urlencode "status=Pending"

​

الخطوة 4 — تسليم المفتاح

async function fulfill(grantId: string, key: string) {
  const res = await fetch(
    `https://test.dodopayments.com/grants/${grantId}/license-key`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
      },
      body: JSON.stringify({
        key,
        // Optional — fall back to the entitlement config when omitted
        activations_limit: 5,
        expires_at: '2027-05-01T00:00:00Z',
      }),
    },
  );

  if (!res.ok) {
    // See the status code table below for handling
    throw new Error(`Fulfillment failed: ${res.status}`);
  }

  return res.json(); // updated grant, now status: "Delivered"
}

curl -X POST https://test.dodopayments.com/grants/entg_8VbC6JDZ/license-key \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "PRO-AAAA-BBBB-CCCC-DDDD",
    "activations_limit": 5,
    "expires_at": "2027-05-01T00:00:00Z"
  }'

​

حقول الطلب

​

الخطوة 5 — معالجة الأخطاء وإعادة المحاولات

​

التحقق من التدفق

1. اشترِ المنتج في وضع الاختبار. راجع أدلة الدفع.
2. تأكد من أن webhook الخاص بك تلقى entitlement_grant.created مع status: "Pending" وintegration_type: "license_key"، أو من ظهور المنحة في استجابة List Grants التي تمت تصفيتها حسب status=Pending.
3. استدعِ نقطة نهاية التسليم باستخدام مفتاح اختبار.
4. تأكد من أن الاستجابة تعرض status: "Delivered" مع license_key مملوءة، وأن العميل تلقى رسالة المفتاح، وأن entitlement_grant.delivered قد تم تشغيله.

​

مرجع API ذي الصلة