API البطاقات الافتراضية: كيف تؤتمت إصدار البطاقات بالكود

ما فائدة API إصدار البطاقات

إصدار بضع بطاقات يدوياً أمر مقبول. لكن إصدار بطاقة لكل عميل أو حملة أو مورّد جديد، والإبقاء على كل منها مشحونة، يصبح عملاً متكرراً بسرعة. وواجهة API لإصدار البطاقات تحوّل هذه الخطوات إلى كود:

• إنشاء بطاقة لكل جهة تلقائياً، مثلاً عند تسجيل عميل جديد في نظام CRM لديك.
• شحن البطاقات وفق جدول زمني أو عند انخفاض رصيدها.
• تجميد البطاقات فوراً عند بلوغ الميزانية أو انتهاء عقد.
• مزامنة المعاملات مع أدوات المحاسبة أو التقارير.
• الاستجابة للأحداث لحظياً عبر webhooks بدلاً من الاستعلام المتكرر.

تؤدي الـ API ما تؤديه لوحة التحكم، لكن من خادمك. كل بطاقة تُصدرها وكل عملية شحن تقوم بها تُدفع من رصيد حسابك، الذي تموّله بإيداعات العملات الرقمية ويُحفظ دائماً بعملة USDT.

الحصول على صلاحية الوصول إلى API البطاقات الافتراضية

يتطلب الوصول ثلاث خطوات:

1. أنشئ مفتاحاً. افتح قسم الوصول إلى الـ API في لوحة التحكم وولّد مفتاحاً. تبدأ المفاتيح بـ sk_live_.
2. اطلب التفعيل. أكّد بريدك الإلكتروني وأجرِ أول إيداع، ثم اطلب من الدعم (عبر تذكرة في لوحة التحكم) تفعيل الـ API لحسابك.
3. نفّذ أول استدعاء. تحقّق من رصيدك، ثم أصدِر بطاقتك الأولى.

إلى أن يصبح حسابك جاهزاً، يحصل المفتاح الصالح على استجابة 403. سترى رمز الخطأ onboarding_incomplete إلى أن تؤكد بريدك وتجري أول إيداع، ثم api_not_enabled إلى أن يُفعَّل الوصول إلى الـ API.

لا توجد بيئة اختبار (sandbox) منفصلة ولا حزم SDK رسمية. تستدعي REST API مباشرة بأي عميل HTTP، وهذا يبقي التكامل بسيطاً لكنه يعني أن كل استدعاء حقيقي. اختبر بمبالغ صغيرة.

الأساسيات: عنوان URL الأساسي والمصادقة والصيغة

• عنوان URL الأساسي: https://usdtcryptocard.com/api/v1
• المصادقة: أرسل مفتاحك كرمز Bearer في ترويسة Authorization في كل طلب.
• الصيغة: JSON عبر HTTPS. المبالغ بالدولار الأمريكي بخانتين عشريتين. والطوابع الزمنية بصيغة ISO 8601 بتوقيت UTC.
• التقسيم إلى صفحات: تقبل نقاط النهاية الخاصة بالقوائم المعاملين page وper_page.

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

أول استدعاء لك

التحقق من رصيدك طلب أول آمن:

curl https://usdtcryptocard.com/api/v1/wallet/balance \
  -H "Authorization: Bearer sk_live_..."

تعرض الاستجابة رصيدك من USDT والإيداعات المعلّقة وما هو موجود على بطاقاتك:

{
  "balance": 1312.5,
  "currency": "USDT",
  "pending_deposits": 500.0,
  "cards_active": 8,
  "cards_total_balance": 2450.0
}

نقاط النهاية

تضم الـ API خمس عشرة نقطة نهاية موزعة على ستة موارد.

المعاملات الكاملة وأمثلة الاستجابات موجودة في مرجع الـ API.

إصدار بطاقة من الكود

إنشاء بطاقة يختار BIN ويشحن البطاقة من رصيدك في الطلب نفسه. والحقول هي:

• bin_id (إلزامي): الـ BIN الذي تُصدر عليه البطاقة. اعرض الخيارات عبر GET /bins.
• amount (إلزامي): الشحن الأولي بالدولار الأمريكي، يُقتطع من رصيدك. الحد الأدنى 50$، وتُضاف رسوم الإصدار البالغة 1$ فوقه.
• label: الاسم الذي تختاره للبطاقة.
• spending_limit: حد إنفاق بالدولار الأمريكي.
• allowed_categories: فئات التجار المسموح باستخدام البطاقة لديها، مثل الإعلانات أو البرمجيات. وأي فئة أخرى تُرفض.
• auto_freeze_at: تجميد البطاقة تلقائياً عندما ينخفض رصيدها تحت هذا المبلغ.
• metadata: أزواج مفتاح-قيمة لأغراض التتبع الخاصة بك.

وهذا الطلب نفسه بلغة Node.js:

const res = await fetch('https://usdtcryptocard.com/api/v1/cards', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.USDTCC_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    bin_id: '491653',
    amount: 500,
    label: 'Meta Ads - Campaign 12',
    spending_limit: 2000,
    allowed_categories: ['advertising'],
    metadata: { campaign: 'fall_2026' },
  }),
});
const card = await res.json();

يعيد الاستدعاء الناجح الرمز 201 مع كائن البطاقة: معرّفها id، والـ BIN، والشبكة، وآخر أربعة أرقام، والحالة، والرصيد، إضافة إلى الاسم والبيانات الوصفية التي وضعتها. ويستبعد الملخص عمداً الرقم الكامل ورمز CVV.

الحصول على رقم البطاقة بأمان

يعيد GET /cards/{card_id}/details رقم البطاقة الكامل ورمز CVV وتاريخ الانتهاء. تعامل معه كبيانات حساسة: لا تسجّل الاستجابة في السجلات أبداً ولا تخزنها دون تشفير، واجلبها فقط عندما تحتاج فعلاً إلى تسليم البيانات لشخص أو لصفحة دفع. ولنقطة النهاية هذه حد استدعاءات أشد من البقية.

الشحن والتجميد والإغلاق

• الشحن: POST /cards/{card_id}/fund مع amount ينقل المال من رصيدك إلى البطاقة، ويصبح قابلاً للإنفاق فوراً.
• استرجاع الأموال: POST /cards/{card_id}/withdraw يعيد رصيد البطاقة إلى محفظتك.
• الإيقاف المؤقت: POST /cards/{card_id}/freeze يوقف كل المعاملات مع الإبقاء على الرصيد. وunfreeze يعيد تفعيل البطاقة.
• الإغلاق: DELETE /cards/{card_id} ينهي البطاقة نهائياً ويعيد رصيدها المتبقي إلى محفظتك. ولا يمكن التراجع عن ذلك.

تنطبق الرسوم المعتادة على نشاط الـ API تماماً كما في لوحة التحكم: 1$ لكل بطاقة تُصدر، و0.30$ لكل معاملة مقبولة (العمليات المرفوضة مجانية)، وشحن البطاقات من رصيدك مجاني. الإيداعات الأقل من 300$ عليها رسوم 2%، ومن 300$ فأكثر بلا رسوم. راجع قسم الأسعار.

Webhooks

بدلاً من الاستعلام المتكرر، سجّل نقطة نهاية HTTPS عبر POST /webhooks، مع قائمة الأحداث التي تريدها (أو ["*"] لكل الأحداث). ومن الأحداث المتاحة:

• card.created، card.frozen، card.unfrozen، card.terminated، card.funded
• transaction.authorized، transaction.settled، transaction.declined، transaction.refunded
• 3ds.challenge
• deposit.pending، deposit.confirmed

كل عملية تسليم موقّعة بخوارزمية HMAC-SHA256 باستخدام السر الخاص بنقطة النهاية، والذي يُولَّد لك إن لم تقدّمه. أعد حساب التوقيع على جسم الطلب الخام وقارنه بمقارنة ثابتة الزمن قبل الوثوق بالمحتوى:

import crypto from 'node:crypto';

export function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

لا تحلّل JSON إلا بعد نجاح التحقق، واجعل المعالج لديك متساوي الأثر (idempotent) تحسباً لوصول الحدث أكثر من مرة.

الأخطاء وحدود الاستدعاءات

أي استجابة غير 2xx تأتي مع جسم JSON يحتوي على رمز error ثابت يمكنك البناء عليه في منطقك، ورسالة message مقروءة. رموز الحالة التي ستصادفها هي 400 (معاملات غير صالحة)، و401 (مفتاح مفقود أو غير صالح)، و403 (الحساب غير جاهز أو الـ API غير مفعّلة)، و404 (غير موجود)، و429 (تجاوز حد الاستدعاءات).

تُحتسب الحدود لكل مفتاح API:

إذا حصلت على 429، فانتظر وأعد المحاولة مع تراجع أُسّي (exponential backoff).

نصائح تصميم لتكامل موثوق

• خزّن معرّف البطاقة id لا رقمها. اجلب البيانات عند الحاجة.
• استخدم metadata وlabel لربط البطاقات بسجلاتك، مثل معرّف العميل أو الحملة.
• فضّل webhooks على الاستعلام المتكرر للمعاملات وتحديات 3D Secure.
• اترك هامشاً على البطاقات التي تدفع رسوماً متكررة، أو استخدم auto_freeze_at وfund لإدارة الأرصدة تلقائياً.
• خطّط للحدود. حدود خطة الحساب تبقى سارية: تسمح خطة Virtual بـ 5,000$ للمعاملة و20,000$ شهرياً، بينما Platinum، التي تُفتح بإيداع واحد قيمته 300$ أو أكثر، بلا حدود للإنفاق.

إذا كنت تدير البطاقات لفريق بدلاً من كتابة الكود، فراجع البطاقات الافتراضية للفرق. ولحالات استخدام الحسابات الإعلانية، اقرأ البطاقات الافتراضية للإعلانات. جاهز للبدء؟ أنشئ حساباً.

الأسئلة الشائعة

ما هي واجهة API للبطاقات الافتراضية؟

واجهة تتيح للبرمجيات إنشاء بطاقات الدفع وإدارتها تلقائياً. في USDT Crypto Card، هي REST API تستخدم JSON عبر HTTPS، وتتم المصادقة فيها بمفتاح سري sk_live_.

هل توجد بيئة اختبار أو SDK؟

لا. لا توجد بيئة اختبار (sandbox) ولا حزم SDK رسمية. تستدعي REST API مباشرة بأي عميل HTTP، وكل استدعاء حقيقي، لذا اختبر بمبالغ صغيرة.

لماذا يعيد مفتاح الـ API الجديد الرمز 403؟

الحساب ليس جاهزاً بعد. يعني onboarding_incomplete أنك ما زلت بحاجة إلى تأكيد بريدك وإجراء أول إيداع. ويعني api_not_enabled أن الدعم لم يفعّل الوصول إلى الـ API بعد.

كيف تُؤمَّن الـ webhooks؟

كل عملية تسليم موقّعة بخوارزمية HMAC-SHA256 باستخدام السر الخاص بنقطة النهاية. أعد حساب التوقيع على الجسم الخام وقارنه بمقارنة ثابتة الزمن قبل الوثوق بالمحتوى.

هل تكلّف بطاقات الـ API ما تكلّفه بطاقات لوحة التحكم؟

نعم. تنطبق الرسوم نفسها: 1$ لكل بطاقة، و0.30$ لكل معاملة مقبولة، وشحن مجاني من رصيدك، ورسوم إيداع 2% لأقل من 300$.