حزم SDK ومكتبات العملاء

تغطي مكتبات SOAMTAR الرسمية لغات الخوادم وتطبيقات الهاتف والمتصفح وUnity وأبرز منصات التجارة الإلكترونية. وكلها موجّهة إلى سيراليون: المبالغ بالليون (SLE، مع قبول USD وEUR أيضًا)، وOrange Money Sierra Leone (orange_money_sl) هو المزوّد الوحيد، وأرقام هواتف الدافعين بصيغة +232 متبوعة بـ 8 أرقام.

التوفّر

الإصدارات أدناه نهائية، لكن الحزم لم تُنشر بعد في المستودعات العامة (npm وPackagist وPyPI وRubyGems وMaven Central وNuGet وpub.dev…). إلى أن يتم ذلك، ثبّتها من مستودع الشيفرة المصدرية الذي يوفّره دعم SOAMTAR. أما حزمة المتصفح فهي متاحة بالفعل على https://app.so-amtar.com/sdk/soamtar.js (غير منشورة على npm بعد).

---

كيف تختار؟

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

صفحات لغات الخادم وصفحة المتصفح متاحة باللغة الإنجليزية.

نوعان من المكتبات

	حزم SDK للخادم	حزم SDK للعميل (المتصفح، الهاتف، Unity)
المفتاح	مفتاح سرّي sk_test_… / sk_live_…	مفتاح عام pk_test_… / pk_live_… (أو بلا مفتاح)
مكان التشغيل	الواجهة الخلفية لديك فقط	متصفح الدافع أو هاتفه أو لعبته
الوظيفة	تنشئ الدفعات (POST /v1/payments) وتستعلم عنها وتتحقق من webhooks	تفتح payment_url التي حصلت عليها واجهتك الخلفية عبر POST /v1/payments

لا تنشئ حزمة العميل أي دفعة ولا تحتفظ أبدًا بمفتاح سرّي. لا يوجد مضيف sandbox منفصل: مع مفتاح sk_test_ تُحاكى الدفعات على https://app.so-amtar.com/v1.

---

الخادم (الخلفي)

اللغة	الحزمة	الإصدار	نقطة الدخول
PHP / Laravel	soamtar/soamtar-php (Composer، PHP 8.2+)	1.1.0	Soamtar\SoamtarClient، Soamtar\Soamtar
Node.js / TypeScript	@soamtar/sdk (npm)	1.1.0	SoamtarClient
Python	soamtar (pip)	1.1.0	soamtar.SoamtarClient
Ruby	soamtar (gem)	1.1.0	Soamtar::Client
Java	com.soamtar:soamtar-java (Maven)	1.1.0	com.soamtar.sdk.SoamtarClient
Go	github.com/soamtar/soamtar-go-sdk	1.1.0	soamtar.NewClient
.NET / C#	Soamtar (NuGet)	1.1.0	Soamtar.SoamtarClient

الهاتف المحمول والواجهة الأمامية

المنصة	الحزمة	الإصدار	نقطة الدخول
المتصفح (JavaScript)	@soamtar/browser، أو السكربت المتاح على https://app.so-amtar.com/sdk/soamtar.js	1.0.0	SoamtarSDK
iOS (Swift)	SoamtarSDK (Swift Package Manager، iOS 14+)	1.0.1	Soamtar، SoamtarCheckoutView
Android (Kotlin)	com.soamtar:soamtar-android (Gradle)	1.1.0	com.soamtar.sdk.Soamtar
Flutter	soamtar_sdk (pub)	1.0.1	package:soamtar_sdk/soamtar_sdk.dart
React Native	@soamtar/react-native (npm، مع react-native-webview)	1.1.0	SoamtarClient، SoamtarCheckout
Unity (الألعاب)	المجلد Assets/Soamtar	1.0.1	Soamtar.SoamtarClient

إضافات أنظمة إدارة المحتوى والتجارة الإلكترونية

المنصة	الإضافة	الإصدار
WordPress / WooCommerce	SOAMTAR for WooCommerce (soamtar-gateway)	1.1.0
Magento 2	soamtar/magento2-payment (الوحدة Soamtar_Payment)	1.1.0
PrestaShop 1.7.7+	وحدة الدفع soamtar	1.1.0
Drupal Commerce	soamtar/drupal-commerce (الوحدة soamtar_commerce)	1.1.0
Odoo	payment_soamtar (SOAMTAR Payment Provider)	17.0.1.1.0

أجهزة الدفع (TPE / Smart POS)

حزمة SDK من SOAMTAR لأجهزة الدفع العاملة بنظام Android قيد الإعداد. وهي تعتمد على نقاط النهاية /v1/pos/* التي لم تتوفّر بعد في الواجهة البرمجية: لا تستخدمها في بيئة الإنتاج.

---

الاصطلاحات المشتركة

تعرض حزم SDK للخادم الواجهة نفسها، مع تكييفها مع أسلوب التسمية في كل لغة (CreateAsync في .NET، وCreate(ctx, …) في Go):

client.payments.create(params, idempotencyKey?)   POST /v1/payments
client.payments.retrieve(id)                      GET  /v1/payments/{id}
client.payments.list(filters)                     GET  /v1/payments
client.payments.status(idOrReference)             GET  /v1/status/{idOrReference}
client.payments.verify(id)                        POST /v1/payments/{id}/verify

client.payouts.create / retrieve / list           /v1/payouts
client.refunds.create / retrieve / list           /v1/refunds
client.balance.retrieve()                         GET  /v1/balance
client.webhooks.list / create / secret / sendTest /v1/webhooks

Webhook.constructEvent(rawBody, signatureHeader, secret)

• تقبل retrieve معرّف SOAMTAR أو مرجعها (TXN-…)، وليس merchant_ref الخاص بك.
• ترفض عملاء الخادم أي مفتاح لا يبدأ بـ sk_. عند عدم تمرير مفتاح تقرأ SOAMTAR_SECRET_KEY؛ ويُؤخذ العنوان الأساسي من SOAMTAR_API_URL (مع قبول SOAMTAR_BASE_URL كبديل احتياطي)، والقيمة الافتراضية https://app.so-amtar.com/v1.
• يحمل كل طلب POST الترويسة Idempotency-Key: تُولَّد تلقائيًا، أو تُستخدم القيمة التي تمرّرها.
• webhooks.create: الحقل subscribed_events اختياري، وقيمته الافتراضية payment.success وpayment.failed وpayout.success وpayout.failed.
• تطلب webhooks.sendTest() (أو send_test / SendTest حسب اللغة) من SOAMTAR إرسال حدث webhook.test إلى نقاط النهاية الخاصة بك.
• تبقى أسماء الدوال القديمة (webhooks.test وwebhooks.all وbalance.show وstatus.retrieve…) متاحة كأسماء بديلة مُهمَلة.
• تُطلق الأخطاء استثناء SOAMTAR يتضمّن حالة HTTP ورمز خطأ الواجهة البرمجية.

توقيع الطلبات الاختياري (راجع Authentication) هو خيار في العميل:

اللغة	الخيار
Node.js	soamtar(key, { signRequests: true })
PHP	'sign_requests' => true
Python	SoamtarClient(..., sign_requests=True)
Ruby	Soamtar::Client.new(key, sign_requests: true)
Go	soamtar.WithSignRequests(true)
Java	new SoamtarClient(null, null, Duration.ofSeconds(30), true) (signRequests)
.NET	new SoamtarClient(signRequests: true)

دالة التحقق من webhooks حسب اللغة:

اللغة	الدالة
PHP	Soamtar\Webhook::constructEvent($rawBody, $signatureHeader, $secret)
Node.js	Webhook.constructEvent(rawBody, signatureHeader, secret)
Python	Webhook.construct_event(raw_body, signature_header, secret)
Ruby	Soamtar::Webhook.construct_event(raw_body, signature_header, secret)
Java	Webhook.constructEvent(payload, signatureHeader, secret)
Go	soamtar.ConstructEvent(payload, sigHeader, secret)
.NET	Webhook.ConstructEvent(payload, signatureHeader, secret)

تتحقق كل دالة من الترويسة X-Soamtar-Signature (t=<unix>,v1=<hmac>، بالإضافة إلى v2= أثناء تدوير السرّ)، وتعيد حساب HMAC-SHA256(secret, "t.payload") على الجسم الخام، وترفض الطوابع الزمنية الأقدم من 300 ثانية، وتعيد الحدث بعد فكّه (event، created، data). راجع Webhooks.

الاسترداد

تعيد client.refunds.create({ transaction_id, amount? }) المال إلى رقم Orange Money الخاص بالدافع، مع خصمه من رصيدك. عند حذف amount يُسترد كامل المبلغ المتبقي؛ والاسترداد الجزئي مسموح. الاسترداد غير متزامن: تصل النتيجة عبر refund.success / refund.failed. يحتاج المفتاح إلى الصلاحية can_refund. راجع Refunds.

الأنماط الموصى بها

إعادة استخدام العميل

أنشئ عميلًا واحدًا لكل عملية وأعد استخدامه بدلًا من إنشاء عميل جديد لكل طلب:

import { SoamtarClient } from '@soamtar/sdk'

const soamtar = new SoamtarClient(process.env.SOAMTAR_SECRET_KEY)

export function pay(order: { id: string; amount: string; phone: string }) {
  return soamtar.payments.create({
    merchant_ref: order.id,
    amount: order.amount,          // "1250.00" → Le 1,250.00
    currency: 'SLE',
    provider: 'orange_money_sl',
    phone: order.phone,            // +232XXXXXXXX
  })
}

إعادة المحاولة مع تأخير تصاعدي

لا تعيد حزم SDK المحاولة من تلقاء نفسها. إذا أضفت إعادة المحاولة، فأعد استخدام نفس Idempotency-Key حتى لا يُنشئ طلب POST المعاد دفعةً ثانية أبدًا:

import { randomUUID } from 'node:crypto'

async function withRetry<T>(fn: (key: string) => Promise<T>, max = 3): Promise<T> {
  const idempotencyKey = randomUUID()   // one key for every attempt
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn(idempotencyKey)
    } catch (e: any) {
      const retryable = !e.status || e.status === 429 || e.status >= 500
      if (!retryable || attempt >= max) throw e
      await new Promise(r => setTimeout(r, 2 ** attempt * 1000))   // 1s, 2s, 4s
    }
  }
}

await withRetry(key => soamtar.payments.create(params, { idempotencyKey: key }))

مهم

أعد محاولة أخطاء الشبكة و429 و5xx بنفس Idempotency-Key. لا تُعد أبدًا محاولة أخطاء 4xx الأخرى: صحّح الطلب أولًا. راجع Idempotency (بالإنجليزية).

التوليد من مواصفة OpenAPI

للغة لا تتوفّر لها حزمة SDK، ولّد عميلًا مُنمَّطًا من مواصفة OpenAPI (openapi.yaml):

# TypeScript types
npx openapi-typescript ./openapi.yaml -o src/soamtar.types.ts

# Python (openapi-generator)
openapi-generator-cli generate -i ./openapi.yaml -g python -o ./soamtar-py

# Go
oapi-codegen -package soamtar ./openapi.yaml > soamtar.gen.go

طلب حزمة SDK

لغتك غير موجودة؟ راسل support@so-amtar.com مع ذكر:

• اللغة / إطار العمل المستهدف؛
• حجم المعاملات المتوقع؛
• حالة الاستخدام الرئيسية.