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

يستعرض هذا الدليل كيفية بناء نظام لتسليم مفاتيح الترخيص يدويًا من البداية إلى النهاية. بدلًا من أن يتولى Dodo Payments إنشاء مفتاح تلقائيًا عند الدفع، ينشئ كل شراء grant من النوع Pending وينتظر منك تزويده بقيمة المفتاح من نظامك الخاص أو من مورّد تابع لجهة خارجية أو من مجموعة محدودة من الرموز. بنهاية هذا الدليل سيكون لديك:

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

License Keys overview

دورة حياة مفتاح الترخيص الكاملة وإعداد fulfillment_mode.

Fulfill License Key Grant API

مرجع API لنقطة النهاية التي تستدعيها لتسليم مفتاح.

آلية العمل

يغيّر التنفيذ اليدوي خطوة الإصدار فقط. أما التفعيل والتحقق وإلغاء التفعيل وانتهاء الصلاحية والإبطال، فتعمل تمامًا مثل المفتاح المُنشأ تلقائيًا بعد تسليمه.

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

لمتابعة هذا الدليل ستحتاج إلى:

حساب تاجر Dodo Payments.
مفتاح API الخاص بك (DODO_PAYMENTS_API_KEY) ومفتاح سر webhook من لوحة المعلومات. راجع دليل إنشاء مفتاح API.
نقطة نهاية خلفية يمكنها استقبال webhooks.

استخدم https://test.dodopayments.com وبيانات اعتماد وضع الاختبار أثناء الإنشاء. انتقل إلى https://live.dodopayments.com واستخدم المفاتيح الحية عند الانتقال إلى بيئة الإنتاج.

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

الاستحقاق هو تعريف قابل لإعادة الاستخدام لما تقدمه. أنشئ استحقاق License Key واضبط fulfillment_mode الخاص به على manual.

Dashboard
API

Open Entitlements

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

Choose License Key

اختر License Key باعتباره التكامل، وأدخِل له Name. يعرض النموذج الحقول التالية:

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

نموذج استحقاق مفتاح ترخيص جديد يتضمن الاسم ووضع التسليم ومدة الترخيص وحدّ عمليات التفعيل ورسالة التفعيل

Set Fulfillment Mode to Manual

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

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

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_...

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

entitlement = 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",
    },
)

print(entitlement.id)

curl -X POST https://test.dodopayments.com/entitlements \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro License (Manual)",
    "integration_type": "license_key",
    "integration_config": {
      "fulfillment_mode": "manual",
      "activations_limit": 5,
      "duration_count": 1,
      "duration_interval": "Year"
    }
  }'

يكون fulfillment_mode مضبوطًا على auto افتراضيًا. يؤدي حذف هذا الإعداد، أو ترك استحقاق موجود دون تغيير، إلى استمرار السلوك التلقائي. وحدها الاستحقاقات المضبوطة صراحةً على manual تنشئ منحًا معلّقة.

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

افتح المنتج الذي تريد بيعه، ووسّع Advanced Settings → Entitlements & Credits، ثم اختر استحقاق License Key الذي ضبطته على Manual في الخطوة 1. يمكن لمنتج واحد تسليم مفتاح الترخيص هذا إلى جانب استحقاقات أخرى ضمن عملية الشراء نفسها.

لوحة استحقاقات المنتج مع تحديد License Key — Selecting the License Key entitlement in the product entitlements panel.

وضع التسليم خاصية من خصائص entitlement، وليس المنتج. وبما أنك عيّنته على Manual في الخطوة 1، فإن كل منتج مرتبط بهذا الاستحقاق ينشئ grants لمفاتيح الترخيص من النوع Pending عند الشراء — ولا حاجة إلى إعداد أي شيء إضافي هنا.

إذا لم يكن لديك منتج بعد، فأنشئ واحدًا أولًا (لمرة واحدة أو باشتراك). راجع دليل تكامل الدفعات لمرة واحدة لبيع المنتج من خلال صفحة الدفع.

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

عندما يشتري العميل المنتج، ينشئ Dodo Payments grant بالحالة Pending من دون إرفاق مفتاح، ويرسل webhook من النوع entitlement_grant.created. هذه هي الإشارة إلى أن عميلًا ينتظر مفتاحًا.

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

أنشئ نقطة نهاية webhook (Developer → Webhooks في لوحة المعلومات) واتخذ إجراءً بشأن منح مفاتيح الترخيص المعلّقة. يتبع التنفيذ مواصفة Standard Webhooks.

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.DODO_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'
  ) {
    await queueLicenseKeyFulfillment({
      grantId: event.data.id,
      customerId: event.data.customer_id,
    });
  }

  return new Response('ok');
}

تتضمن حمولة المنحة integration_type: "license_key"، لذا يمكنك التعرّف على منحة License Key من دون عملية بحث إضافية. راجع مرجع webhook الخاص بمنحة الاستحقاق للاطلاع على الحمولة الكاملة.

أو الاستطلاع باستخدام List Grants API

إذا كنت تفضّل عدم الاعتماد على webhooks، فاعرض منح استحقاق License Key وفلترها حسب status. كل منحة ضمن استحقاق License Key هي بالفعل منحة لمفتاح ترخيص، لذلك لا حاجة إلى فلتر integration_type:

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 — تسليم المفتاح

احصل على قيمة المفتاح من نظامك الخاص، ثم أرسلها باستخدام نقطة النهاية Fulfill License Key Grant. يتطلب ذلك مفتاح API السري الخاص بك (بصلاحية Editor)؛ وليس هذا المفتاح إحدى نقاط نهاية الترخيص العامة.

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/grant_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"
  }'

حقول الطلب

string

مطلوب

سلسلة مفتاح الترخيص التي سيتم تسليمها إلى العميل. تُزال المسافات البيضاء؛ وتُرفض القيمة الفارغة أو التي تتكون من مسافات بيضاء فقط.

integer

حد التفعيل لكل مفتاح. يعود إلى إعدادات الاستحقاق عند حذفه من الطلب.

string

انتهاء صلاحية كل مفتاح (ISO 8601). يعود إلى مدة إعدادات الاستحقاق عند حذفه من الطلب. وبالنسبة إلى المنح المُصدرة عبر الاشتراك، تظل الصلاحية مرتبطة بالاشتراك في جميع الحالات.

عند النجاح، ينتقل grant إلى Delivered، ويتم إرسال المفتاح إلى العميل تلقائيًا (وهو نفس البريد الإلكتروني الذي كان سيتلقاه في حالة التسليم التلقائي)، ويتم إطلاق أحداث webhook من النوعين license_key.created وentitlement_grant.delivered. يتلقى العميل رسالة بريد إلكتروني تتضمن مفتاح الترخيص والمنتج وحد التفعيل وانتهاء الصلاحية وتعليمات التفعيل الخاصة بك:

رسالة بريد إلكتروني للعميل تتضمن مفتاح الترخيص والمنتج وحد التفعيل وانتهاء الصلاحية وتعليمات التفعيل — The license key email the customer receives once you fulfill the grant.

لا تحتاج إلى إرسال المفتاح عبر البريد الإلكتروني بنفسك — إذ يحدث التسليم تلقائيًا عند تنفيذ المنحة.

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

تتحقق نقطة النهاية من المنحة قبل تسليم أي شيء. عالج الاستجابات التالية:

الحالة	المعنى	الإجراء المطلوب
`200`	تم تسليم المفتاح، وأصبح grant الآن في الحالة `Delivered`.	تم.
`400`	ليس grant لمفتاح ترخيص، أو أن المفتاح فارغ/يتكون من مسافات بيضاء.	أصلح الطلب؛ ولا تعاود المحاولة كما هو.
`404`	لا يوجد grant بهذا المعرّف لنشاطك التجاري.	تحقّق من `grant_id`.
`409`	لا ينتظر grant التسليم (تم تسليمه بالفعل أو يحتوي على مفتاح بالفعل)، أو أن قيمة المفتاح موجودة مسبقًا.	إذا كان قد تم تسليمه بالفعل، فاعتبر العملية ناجحة. وإذا كان المفتاح مكررًا، فأرسل مفتاحًا مختلفًا.
`422`	فشل التحقق من صحة نص الطلب (مثل `activations_limit < 1`).	صحّح الحقل ثم أعد المحاولة.

يمكن إعادة محاولة التنفيذ بأمان عند حدوث أخطاء مؤقتة (مثل انتهاء المهلة و5xx). لا يمكن تنفيذ كل منحة إلا مرة واحدة، لذا فإن إعادة المحاولة بعد استدعاء ناجح لم يتم تأكيده تُرجع 409 بدلًا من إصدار مفتاح ثانٍ أو إرسال رسالة بريد إلكتروني مكررة. استخدم id الخاص بالمنحة باعتباره مفتاح idempotency.

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

اشترِ المنتج في وضع الاختبار (راجع أدلة إتمام الدفع).
تأكد من أن webhook الخاص بك استلم entitlement_grant.created مع status: "Pending" وintegration_type: "license_key"، أو من ظهور grant في استجابة List Grants باستخدام عوامل التصفية نفسها.
استدعِ نقطة نهاية fulfill باستخدام مفتاح اختباري.
تأكد من أن الاستجابة تعرض status: "Delivered" مع license_key مملوءًا، وأن العميل استلم رسالة البريد الإلكتروني التي تتضمن المفتاح، وأن entitlement_grant.delivered قد تم إطلاقه.

بعد التسليم، يمكن للعميل تفعيل المفتاح والتحقق منه باستخدام نقاط نهاية الترخيص العامة، تمامًا مثل المفتاح المُنشأ تلقائيًا.

مرجع API ذي صلة

Create Entitlement

أنشئ entitlement من نوع License Key باستخدام fulfillment_mode: manual.

List Grants

استخدم التصفية حسب status وcustomer_id للعثور على grants المعلّقة.

Fulfill License Key Grant

سلّم قيمة المفتاح وانقل grant إلى الحالة delivered.

Entitlement Grant Webhooks

أحداث entitlement_grant.* التي تشير إلى grants المعلّقة والمسلّمة.

Integration Guides

Billing Deconstructions

Cookbooks

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

License Keys overview

Fulfill License Key Grant API

آلية العمل

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

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

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

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

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

أو الاستطلاع باستخدام List Grants API

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

حقول الطلب

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

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

مرجع API ذي صلة

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

License Keys overview

Fulfill License Key Grant API

​آلية العمل

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

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

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

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

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

​أو الاستطلاع باستخدام List Grants API

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

​حقول الطلب

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

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

​مرجع API ذي صلة

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

آلية العمل

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

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

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

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

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

أو الاستطلاع باستخدام List Grants API

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

حقول الطلب

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

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

مرجع API ذي صلة