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

البدء السريع

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

• POST /v1/merchants/{merchant_id}/api-keys — يُصدر زوج مفاتيح الواجهة الذي توقّع به طلباتك.
• POST /v1/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).

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()

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

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

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

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

إشعارات Webhook

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

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 ويمكن إعادته إلى الطابور بنقرة واحدة من لوحة التحكم.

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

لا تقتطع 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.

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