توثيق الواجهة البرمجية ودليل المطوّر

البدء السريع

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

• لوحة التحكم ← مفاتيح API — سجّلوا الدخول وأنشئوا زوج المفاتيح (KeyId وSecret) من هناك. تُعرض قيمة Secret مرة واحدة فقط عند الإنشاء.
• اللوحة ← الإعدادات أو POST /v1/static-addresses — يسجّل العنوان الثابت لتحصيل الرموز مثل USDT (عنوان واحد لكل شبكة وأصل).
• اللوحة ← الإعدادات أو POST /v1/sweep-addresses — يسجّل المحفظة الرئيسية (عنوان التجميع) التي تُجمَّع فيها تحصيلات العملات الأصلية مثل TRX وBNB وGRAM.
• POST /v1/webhooks — يسجّل عنوان URL الذي نُشعِر عليه نظامك فور اكتمال الدفع.

توقيع الطلبات (HMAC)

تُوقَّع جميع طلبات HTTP بمعيار HMAC-SHA256. ويُحتسب التوقيع على جسم الطلب الخام (raw bytes)، فيبقى صالحاً حتى لو تغيّر ترتيب مفاتيح JSON.

METHOD \n PATH \n TIMESTAMP \n NONCE \n SHA256(raw_body)

X-Api-Key

معرّف مفتاح الواجهة (pk_…)

X-Timestamp

طابعة زمنية Unix بالثواني (مع تسامح لساعة الخادم)

X-Nonce

سلسلة عشوائية فريدة (128 محرفاً كحد أقصى، تُستخدم مرة واحدة)

X-Signature

hex(hmac_sha256(secret, canonical))

يحمي الطلبَ مستويان: يجب أن تقع الطابعة الزمنية ضمن نطاق التسامح، وألا تُستخدم قيمة nonce إلا مرة واحدة. أما إعادة إرسال الطلب نفسه فتُرفض تلقائياً (HTTP 401).

X-Timestamp بالثواني بتوقيت Unix، ولا يتجاوز انحرافه عن وقت الخادم 300 ثانية. وX-Nonce فريد لكل طلب؛ ويُرفض أي nonce مستخدم لمدة 600 ثانية.

1import hashlib, hmac, os, time, json, urllib.request
2 
3KEY_ID  = os.environ["COINZEN_KEY_ID"]
4SECRET  = os.environ["COINZEN_SECRET"]
5BASE    = "https://coinzen.cerceyn.com"
6 
7def request(method: str, path: str, payload: dict | None = None) -> bytes:
8    body = json.dumps(payload).encode() if payload is not None else b""
9    ts = str(int(time.time()))
10    nonce = os.urandom(16).hex()
11    canonical = "\n".join(
12        [method.upper(), path, ts, nonce, hashlib.sha256(body).hexdigest()]
13    )
14    signature = hmac.new(SECRET.encode(), canonical.encode(), hashlib.sha256).hexdigest()
15 
16    req = urllib.request.Request(
17        BASE + path,
18        data=body or None,
19        method=method.upper(),
20        headers={
21            "X-Api-Key": KEY_ID,
22            "X-Timestamp": ts,
23            "X-Nonce": nonce,
24            "X-Signature": signature,
25            "Content-Type": "application/json",
26        },
27    )
28    with urllib.request.urlopen(req) as resp:
29        return resp.read()

نطاقات الصلاحية

لا يستطيع المفتاح استدعاء سوى النقاط التي تغطيها نطاقاته؛ ويعيد النظام 403 عند نقص النطاق. تُختار النطاقات عند إنشاء المفتاح من اللوحة.

حدود المعدل

تُطبَّق الحدود لكل تاجر ضمن نافذة منزلقة مدتها دقيقة. وعند تجاوزها يعود 429 مع ترويسة Retry-After.

• النقاط العامة — 120 طلب / دقيقة
• إنشاء الفاتورة — 30 طلب / دقيقة

منع التكرار (Idempotency)

ترويسة Idempotency-Key إلزامية في POST /v1/invoices. وبدونها يُرفض الطلب برمز 422. أنشئ قيمة جديدة وفريدة لكل طلب.

Idempotency-Key: 7f3c1e9a4b8d42f0a1c6e5b3d9074a2e

إعادة إرسال المحتوى نفسه بالمفتاح نفسه لا تُنشئ فاتورة ثانية: يُعاد الرد الأول كما هو برمز حالته الأصلي. يمكنك إعادة المحاولة بأمان بعد انقطاع الاتصال.

دورة حياة الفاتورة

يبدأ إنشاء الفاتورة آلة حالات. فإن لم تُحدَّد الشبكة والأصل، تبدأ الفاتورة بحالة selecting. وحين يختار العميل الشبكة والعملة في صفحة الدفع، تنتقل إلى pending ويُخصَّص لها عنوان دفع.

• selecting → pending, expired, cancelled
• pending → confirming, partially_paid, expired, cancelled
• confirming → paid, overpaid, failed
• paid ⇄ overpaid — إذا أرسل العميل تحويلاً إضافياً على فاتورة مدفوعة، يُحدَّث المبلغ تلقائياً.

الحالات paid وoverpaid وexpired وcancelled وfailed نهائية. وعند حدوث إعادة تنظيم على السلسلة أو دفعة متأخرة، يحدّث النظام الحالة تلقائياً ويُبلغ نظامك عبر إشعار Webhook.

الدفع برصيد

إن كنت تبيع رصيدًا، فالمبلغ الثابت نموذج غير مناسب: يجبر الدافع 5.188 إلى 5 فتبقى الفاتورة ناقصة. افتح الفاتورة بالخيار balance_payment: true فيُغلقها المبلغ الواصل — المبلغ المعروض اقتراح فقط، وصفحة الدفع تُبلّغ الدافع بذلك صراحةً.

احتسب الإضافة من received_amount في الويب هوك ومن received_fiat_amount المحسوب بالسعر المثبَّت، لا من fiat_amount. فإن طلبت الفاتورة 250 ليرة ووصل 5 USDT، فالمضاف هو قيمة هذه الـ5. وتُحتسب العمولة كذلك على المبلغ الواصل.

في تحصيل التوكن يكون العنوان مشتركًا، والذي يربط الدفعة بالفاتورة هو المبلغ. فإن كانت عدّة فواتير رصيد مفتوحة في الوقت نفسه على الشبكة/الأصل ذاته، تعذّر نسب دفعة مُقرَّبة؛ ولا نخمّن — تنزل الدفعة في الإيداعات غير المطابَقة ويُرسَل الويب هوك deposit.unmatched. تربطها أنت بالفاتورة الصحيحة من اللوحة. لا يُستخدم مع فاتورة تعبئة الرصيد.

إشعارات Webhook

يُرسَل كل تغيّر في حالة الدفع فوراً إلى نقطة Webhook المسجّلة لديك. ويُوقَّع كل إشعار بمعيار HMAC-SHA256، فتتحقّق بثقة من سلامة البيانات ومن أنها صادرة عن Coinzen.

تُمنح قيمة Webhook Secret المستخدمة في التحقق (whsec_…) مرة واحدة عند تسجيل نقطة Webhook: من صفحة Webhook في لوحة التحكم، أو في حقل secret ضمن استجابة POST /v1/webhooks. وهي ليست قيمة Secret الخاصة بمفتاح API؛ فتلك توقّع الطلبات التي ترسلونها أنتم فقط. وإذا سجّلتم العنوان نفسه من جديد مُنحتم Webhook Secret جديدة وعُطّلت النقطة القديمة.

X-Coinzen-Signature

t=<unix>,v1=<hex hmac_sha256(secret, "<t>.<raw_body>")>

X-Coinzen-Delivery

معرّف التسليم الفريد (UUID)

X-Coinzen-Event

اسم الحدث المُطلَق (مثل invoice.paid)

1import hashlib, hmac, time
2 
3def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
4    """X-Coinzen-Signature: t=<unix>,v1=<hex>"""
5    parts = dict(p.split("=", 1) for p in header.split(","))
6    t, v1 = parts["t"], parts["v1"]
7    if abs(time.time() - int(t)) > tolerance:
8        return False
9    expected = hmac.new(
10        secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256
11    ).hexdigest()
12    return hmac.compare_digest(expected, v1)

الأحداث المدعومة

• invoice.pending
• invoice.confirming
• invoice.partially_paid
• invoice.paid
• invoice.overpaid
• invoice.expired
• invoice.cancelled
• payment.reverted
• deposit.unmatched
• credit.low
• credit.exhausted

آلية إعادة المحاولة

تجري المحاولة الأولى فور اكتمال الدفع. فإن لم يستجب خادمك بـ 200 OK، تُعاد المحاولة تلقائياً على سبع مراحل بفواصل 30 · 120 · 600 · 3600 · 21600 · 86400 ثانية. وإن أخفقت المحاولات جميعها، ينتقل السجل إلى حالة dead_letter ويمكن إعادته إلى الطابور بنقرة واحدة من لوحة التحكم.

عقد الأخطاء

تعود جميع الأخطاء بالبنية نفسها. حقل code ثابت ومخصص للمطابقة البرمجية، أما message فموجّه للقراءة البشرية وقد يتغيّر.

1{
2  "error": {
3    "code": "conflict",
4    "subcode": "order_id_exists",
5    "message": "bu order_id zaten kullanılmış",
6    "details": { "order_id": "A-1042" }
7  }
8}

يضيّق حقل subcode رمز الفئة: order_id_exists بدلًا من conflict المجرّد. اقرأ subcode أولًا ثم عد إلى code عند غيابه؛ فالعقد يتوسّع ولا يضيق.

عند فشل الطلب في التحقق من البنية (حقل ناقص، نوع خاطئ، قيمة خارج النطاق) تكون قيمة code هي validation_error، ويربط details مسار كل حقل بنوع الخطأ: {"body.url": "url_scheme"}. النوع مخصّص للمطابقة برمجيًا (مثل missing وgreater_than)، أما الشرح ففي message.

العمولة والرصيد

لا تقتطع Coinzen عمولتها من دفعة العميل إطلاقاً. فمدفوعات USDT وغيرها تصل إلى عنوانك مباشرة، ومفاتيح تلك المحفظة بحوزتك وحدك. أما رسوم الخدمة فتُخصم من رصيد العمولة الذي تشحنه مسبقاً، فيبقى تحصيلك كاملاً.

• السعر المعتاد 1%. وتحصل الحسابات الجديدة على 0.1% خلال أول 45 يوماً. ويمكنك الاطّلاع على سعرك الحالي في حقل fee_bps ضمن استجابة GET /v1/credit (بنقاط الأساس: 10 = 0.1%، 100 = 1%).
• لا تُحتسب العمولة إلا على الفواتير المكتملة بنجاح (paid وoverpaid).
• لا تُؤخذ أي عمولة على الفواتير الملغاة أو المنتهية أو الناقصة.
• عند نفاد رصيدك، تستمر معالجة الفواتير المفتوحة كالمعتاد؛ ولا يتلقّى تنبيه الرصيد (HTTP 402) سوى طلبات إنشاء الفواتير الجديدة.

نموذج الخصم على خطوتين

حين تُدفع الفاتورة، يُفتح قيد العمولة فوراً بحالة pending كي لا تتباطأ متابعة السلسلة، ويُعالَج دون الاعتماد على أي خدمة خارجية. ثم يجري تحويل سعر الصرف في الخلفية ويُخصم المبلغ الصافي من رصيدك.

وإن سُحبت الدفعة بسبب إعادة تنظيم على السلسلة، يُلغى خصم العمولة فوراً؛ وإن كان قد خُصم، يُعاد إلى رصيدك بقيد reversal.

شحن الرصيد

يمنحك استدعاء POST /v1/credit/deposit-addresses عنوان شحن USDT دائماً خاصاً بك. ويُضاف ما ترسله إلى هذا العنوان إلى رصيدك فور تأكيده على السلسلة — دون موافقة يدوية ودون انتظار.

التعبئة التلقائية

عند تفعيل هذه الخاصية، لا تتوقّف مبيعات متجرك حتى لو بلغ رصيدك صفراً. إذ تُحوَّل حصيلة فاتورتك الصغيرة التالية إلى رصيدك، فتستمر الخدمة دون انقطاع.

• لا تُؤخذ عمولة إضافية على الفاتورة المحوَّلة إلى الرصيد.
• يسري حد أعلى حمايةً لك (25 دولاراً افتراضياً). أما الفواتير التي تتجاوز الحد فلا تُحوَّل، فلا تتعرّض طلباتك الكبيرة للمخاطرة.
• يمكنك تفعيلها أو إيقافها وتحديد حدّك الأعلى في أي وقت عبر PUT /v1/credit/auto أو من لوحة التحكم.

تنبيهات الرصيد

حين ينزل رصيدك دون العتبة الحرجة يُطلَق حدث credit.low، وعند نفاده يُطلَق credit.exhausted، فتعلم بالأمر مسبقاً.

الشبكات والأصول المدعومة

يلخّص الجدول التالي سجلّ الشبكات الحيّة. وللحصول على القائمة اللحظية، استخدم نقطة GET /v1/networks.

نقاط الواجهة البرمجية

بنية الطلبات

في ما يلي بنية الطلبات للنقاط التي تستدعيها في اليوم الأول. أما البنية الكاملة لكل النقاط فتُنشر بصيغة يقرأها الحاسوب على GET /openapi.json — استوردها إلى Postman أو ولّد منها عميلًا.

معاملات الاستعلام