إنشاء دفعة

ينشئ نية تحصيل ويرجع checkoutUrl، وهو رابط الدفع المستضاف، الصالح لمدة 48 ساعة. وجه المشتري إليه.

الحقل	النوع	مطلوب	التفاصيل
amount	int	نعم	عدد صحيح موجب تماما (DZD).
description	string	لا	نص يظهر للمشتري على صفحة الدفع (280 حرفا كحد أقصى). بدونه لا يرى المشتري سوى مبلغ مجرد.
customerRef	string	لا	مرجعك الخاص (مثلا معرف المستخدم). لا يظهر للمشتري أبدا.
method	string	لا	ccp أو baridimob: يحدد وسيلة الدفع مسبقا على الصفحة (ويمكن للمشتري تغييرها). 400 PAYMENT_METHOD_NOT_AVAILABLE إذا لم تكن هذه الوسيلة متاحة في إعداداتك.
locale	string	لا	fr أو ar: لغة صفحة الدفع. انظر لغة صفحة الدفع. القيمة الافتراضية: لغتك الافتراضية.
returnUrl	string	لا	إلى أين يعاد المشتري انطلاقا من الصفحة. يجب أن يكون النطاق ضمن قائمتك البيضاء. انظر العودة إلى موقعك.
metadata	object	لا	كائن JSON حر. لا يظهر للمشتري أبدا.

يجب أن تكون وسيلة تحصيل واحدة على الأقل مفعلة ومكتملة في إعداداتك (بريدي موب: صاحب الحساب مع RIP؛ CCP: صاحب الحساب مع الرقم والمفتاح والعنوان)، وإلا 409 MERCHANT_PAYMENT_DETAILS_MISSING. ينطبق هذا على البيئتين معا، بما فيها Sandbox: بدون هذه المعلومات لن يجد المشتري أين يحول المال، واختبار يتجاوز هذه الخطوة لا يختبر المسار الحقيقي.

الأخطاء: 400 VALIDATION_ERROR، 400 PAYMENT_METHOD_NOT_AVAILABLE، 400 MERCHANT_LOCALE_NOT_AVAILABLE، 400 MERCHANT_RETURN_URL_NOT_ALLOWED، 401 AUTH_UNAUTHORIZED، 409 MERCHANT_PAYMENT_DETAILS_MISSING.

curl -X POST https://api.lahsab.com/payments/intents \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -d '{
    "amount": 2500,
    "customerRef": "user_abc123",
    "metadata": { "orderId": "CMD-1042" }
  }'

const res = await fetch("https://api.lahsab.com/payments/intents", {
  method: "POST",
  headers: {
    "x-api-key": process.env.LAHSAB_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    amount: 2500,
    customerRef: "user_abc123",
    metadata: { orderId: "CMD-1042" },
  }),
});
const intent = await res.json();

window.location.href = intent.checkoutUrl;

{
  "id": "a7f3c2e1-9b4d-4e6a-8c1f-2d3e4f5a6b7c",
  "environment": "live",
  "customerRef": "user_abc123",
  "amount": 2500,
  "locale": "fr",
  "returnUrl": "https://votre-site.dz/merci",
  "status": "pending",
  "checkoutUrl": "https://dashboard.lahsab.com/pay/a7f3c2e1-9b4d-4e6a-8c1f-2d3e4f5a6b7c",
  "metadata": { "orderId": "CMD-1042" },
  "expiresAt": "2026-07-13T10:00:00.000Z",
  "proofs": [],
  "version": 1,
  "createdAt": "2026-07-11T10:00:00.000Z",
  "updatedAt": "2026-07-11T10:00:00.000Z"
}

الاطلاع على دفعة

يرجع الحالة الراهنة، بشرط أن تنتمي الدفعة إلى المفتاح وإلى بيئته. وإلا 404: الدفعة التابعة لبيئة أخرى غير مرئية.

الأخطاء: 401 AUTH_UNAUTHORIZED، 404 PAYMENT_INTENT_NOT_FOUND.

curl https://api.lahsab.com/payments/intents/INTENT_ID \
  -H "x-api-key: lsk_live_CLE"

{
  "id": "a7f3c2e1-9b4d-4e6a-8c1f-2d3e4f5a6b7c",
  "environment": "live",
  "amount": 2500,
  "method": "baridimob",
  "status": "proof_submitted",
  "checkoutUrl": "https://dashboard.lahsab.com/pay/a7f3c2e1-9b4d-4e6a-8c1f-2d3e4f5a6b7c",
  "expiresAt": "2026-07-13T10:00:00.000Z",
  "proofs": [
    {
      "id": "9c8b7a6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
      "originalName": "recu-baridimob.jpg",
      "mimeType": "image/jpeg",
      "size": 184230,
      "method": "baridimob",
      "submittedAt": "2026-07-11T10:12:00.000Z"
    }
  ],
  "version": 2,
  "createdAt": "2026-07-11T10:00:00.000Z",
  "updatedAt": "2026-07-11T10:12:00.000Z"
}

صفحة الدفع

بدون أي مصادقة: هذا ما تقدمه الصفحة المستضافة لمتصفح المشتري. يرجع عرضا عموميا للدفعة: المبلغ والحالة ووسائل التحصيل الخاصة بالتاجر داخل methods، لكل وسيلة معلوماتها الخاصة (RIP لوسيلة بريدي موب، والرقم والمفتاح والعنوان للدفع عبر CCP). لا تظهر إلا الوسائل المفعلة والمكتملة. يعكس الحقل method الاختيار المسبق إن وجد، والمشتري يختار وسيلته على الصفحة. الحقل locale هو اللغة التي تعرض بها الصفحة، والحقل locales قائمة لغاتك المفعلة. لا مفتاح API ولا سر webhook ولا metadata أبدا.

الدفعة المنتهية الصلاحية (بعد 48 ساعة) ترجع بالحالة status: "expired".

ولا يميز هذا العرض بين دفعة اعتبر وصلها متوافقا ودفعة وصلها للتو: كلتاهما تخرجان بالحالة proof_submitted. وهذا مقصود. فلا ينبغي أن يعلم المشتري أن ملفا ما اجتاز التحليل، وإلا صار الإيداع منصة تجريب لصناعة وصل مزور ينجح. أما الحالة الحقيقية proof_validated فلا تدور إلا على واجهات التاجر: GET /payments/intents/:id وحدث webhook ولوحة التحكم.

الأخطاء: 404 PAYMENT_INTENT_NOT_FOUND.

curl https://api.lahsab.com/payments/checkout/INTENT_ID

{
  "id": "a7f3c2e1-9b4d-4e6a-8c1f-2d3e4f5a6b7c",
  "environment": "live",
  "amount": 2500,
  "method": "baridimob",
  "locale": "ar",
  "locales": ["fr", "ar"],
  "status": "pending",
  "expiresAt": "2026-07-13T10:00:00.000Z",
  "hasProof": false,
  "merchantConfigured": true,
  "methods": [
    {
      "method": "ccp",
      "holder": "SARL ACME",
      "ccpNumber": "0123456789",
      "ccpKey": "12",
      "address": "10 rue Didouche Mourad, Alger"
    },
    {
      "method": "baridimob",
      "holder": "SARL ACME",
      "rip": "00799999012345678912"
    }
  ],
  "merchant": {
    "displayName": "ACME Store",
    "paymentInstructions": "Le versement doit venir de votre propre compte.",
    "supportEmail": "support@acme.dz",
    "supportPhone": "0770000000"
  }
}

إيداع وصل الدفع

بدون أي مصادقة: نقطة نهاية عمومية تستعملها صفحة الدفع (أو صفحتك الخاصة إن بنيت واحدة). الإرسال بصيغة multipart/form-data: حقل file مع حقل method (ccp أو baridimob)، أي الوسيلة التي استعملها المشتري فعلا. يمكن إغفال method عندما تكون وسيلة واحدة فقط متاحة أو عندما تحمل الدفعة اختيارا مسبقا صالحا. تنتقل الدفعة إلى proof_submitted وتحمل من الآن هذا method، وحدث webhook باسم payment.proof_submitted ينقله.

الملف محدود: صور (JPEG، PNG، WebP، HEIC) أو PDF، بحجم أقصاه 10 ميغابايت.

الأخطاء: 400 PAYMENT_PROOF_FILE_MISSING، 400 PAYMENT_METHOD_REQUIRED، 400 PAYMENT_METHOD_NOT_AVAILABLE، 404 PAYMENT_INTENT_NOT_FOUND، 409 PAYMENT_INVALID_TRANSITION، 409 PAYMENT_INTENT_EXPIRED، 413 FILE_TOO_LARGE، 415 FILE_TYPE_NOT_ALLOWED، 429 PAYMENT_PROOF_LIMIT_REACHED.

curl -X POST https://api.lahsab.com/payments/intents/INTENT_ID/proof \
  -F "method=baridimob" \
  -F "file=@recu-baridimob.jpg"

محاكاة وصل الدفع

يرفق وصلا اصطناعيا (ملف PDF بعنوان «PREUVE SIMULEE - SANDBOX»، يظهر في لوحة التحكم مثل أي وصل آخر) وينقل الدفعة إلى proof_submitted. يصدر الحدث payment.proof_submitted، ثم payment.proof_analyzed بتحليل محاكى حكمه match، ثم payment.proof_validated لأن هذا الحكم متوافق. أما الدفعة نفسها فتبقى في انتظار التأكيد: لا يؤكدها أي نظام آلي، تماما كما في الإنتاج.

نفس الضوابط المطبقة على الإيداع العمومي: دفعة منتهية الصلاحية ترد بالخطأ 409 PAYMENT_INTENT_EXPIRED، وحالة نهائية بالخطأ 409 PAYMENT_INVALID_TRANSITION.

الأخطاء: 400 ENVIRONMENT_NOT_ALLOWED، 401 AUTH_UNAUTHORIZED، 404 PAYMENT_INTENT_NOT_FOUND، 409 PAYMENT_INVALID_TRANSITION، 409 PAYMENT_INTENT_EXPIRED.

curl -X POST https://api.lahsab.com/payments/intents/INTENT_ID/simulate/proof \
  -H "x-api-key: lsk_sandbox_CLE"

محاكاة التأكيد

تأكيد «وصول المال» عبر مسار الإشارة المعتاد: تنتقل الدفعة إلى confirmed، وحمولة حدث webhook باسم payment.confirmed تحمل confirmationSource: "manual" تماما كما في الإنتاج. إذا كانت الدفعة مرتبطة بفاتورة، تتم تسوية الفاتورة: يصدر invoice.paid وتتقدم فترة الاشتراك.

صالح انطلاقا من pending أو proof_submitted أو proof_validated. النداء آمن عند التكرار: إذا نودي مجددا على دفعة مؤكدة من قبل، يرجع الدفعة المؤكدة دون خطأ.

الأخطاء: 400 ENVIRONMENT_NOT_ALLOWED، 401 AUTH_UNAUTHORIZED، 404 PAYMENT_INTENT_NOT_FOUND، 409 PAYMENT_INVALID_TRANSITION.

curl -X POST https://api.lahsab.com/payments/intents/INTENT_ID/simulate/confirm \
  -H "x-api-key: lsk_sandbox_CLE"

محاكاة الرفض أو انتهاء الصلاحية

يرفض reject الدفعة: تنتقل إلى rejected ويصدر payment.rejected. سيناريو «وصل مودع لكن المال لم يصل» تحصل عليه بتسلسل simulate/proof ثم simulate/reject.

الحقل	النوع	مطلوب	التفاصيل
reason	string	لا	سبب الرفض.

يفرض expire انتهاء الصلاحية دون انتظار expiresAt. صالح فقط انطلاقا من pending، وإلا 409 PAYMENT_INVALID_TRANSITION. يصدر payment.expired.

الأخطاء: 400 ENVIRONMENT_NOT_ALLOWED، 401 AUTH_UNAUTHORIZED، 404 PAYMENT_INTENT_NOT_FOUND، 409 PAYMENT_INVALID_TRANSITION.

# Rejeter : le motif est optionnel.
curl -X POST https://api.lahsab.com/payments/intents/INTENT_ID/simulate/reject \
  -H "x-api-key: lsk_sandbox_CLE" \
  -H "content-type: application/json" \
  -d '{ "reason": "Fonds jamais reçus" }'

# Expirer (uniquement depuis pending).
curl -X POST https://api.lahsab.com/payments/intents/INTENT_ID/simulate/expire \
  -H "x-api-key: lsk_sandbox_CLE"

تشغيل ساعة الفوترة

ينفذ ساعة الفوترة الآن، مقصورة على بياناتك في Sandbox (التجديدات، التأخيرات، انتهاء الصلاحية)، ويرجع تقريرها. بهذا يمكنك ملاحظة عدة دورات لاشتراك interval: "day" في دقائق معدودة.

قيمة purgedIdempotencyKeys تساوي دائما 0 في الوضع المقصور. الحد الأقصى 6 نداءات في الدقيقة.

الأخطاء: 400 ENVIRONMENT_NOT_ALLOWED، 401 AUTH_UNAUTHORIZED، 429 RATE_LIMITED.

curl -X POST https://api.lahsab.com/billing/simulate/tick \
  -H "x-api-key: lsk_sandbox_CLE"

{
  "expiredIntents": 0,
  "issuedInvoices": 1,
  "markedOverdue": 0,
  "markedUncollectible": 0,
  "closedSubscriptions": 0,
  "purgedIdempotencyKeys": 0
}

البدء من جديد

يمسح بيانات الاختبار الخاصة بك (الدفعات، الوصولات، الأحداث). في Sandbox فقط: مع مفتاح lsk_live_… يرجع 400 ENVIRONMENT_NOT_ALLOWED. مفيد بين جولتي اختبار للانطلاق من قاعدة نظيفة.

الأخطاء: 400 ENVIRONMENT_NOT_ALLOWED، 401 AUTH_UNAUTHORIZED.

curl -X DELETE https://api.lahsab.com/payments/sandbox-data \
  -H "x-api-key: lsk_sandbox_CLE"

إنشاء زبون

الزبون هو الطرف الذي يدفع. وكل ما عداه (الاشتراكات، الفواتير) يرتبط به.

الحقل	النوع	مطلوب	التفاصيل
externalId	string	لا	معرف الزبون عندك. فريد لكل تاجر وبيئة.
name	string	لا	الاسم الظاهر على الفاتورة.
email	string	لا
phone	string	لا
defaultMethod	string	لا	ccp أو baridimob. يحدد مسبقا وسيلة الدفع على فواتير هذا الزبون، فقط إذا كانت متاحة في إعداداتك.
locale	string	لا	fr أو ar: لغة الصفحات المرسلة إلى هذا الزبون، بما فيها تجديدات الاشتراك. انظر لغة صفحة الدفع.
metadata	object	لا	كائن JSON حر.

املأ externalId: هو ما يعود إليك في كل حدث webhook، ويغنيك عن تخزين معرف id الذي يولده lahsab من جهتك.

الأخطاء: 400 VALIDATION_ERROR، 400 MERCHANT_LOCALE_NOT_AVAILABLE، 401 AUTH_UNAUTHORIZED، 409 CUSTOMER_ALREADY_EXISTS، 409 IDEMPOTENCY_KEY_REUSED.

curl -X POST https://api.lahsab.com/customers \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: cust-user_abc123" \
  -d '{
    "externalId": "user_abc123",
    "name": "Yacine B.",
    "email": "yacine@example.dz",
    "phone": "0770000000",
    "defaultMethod": "baridimob"
  }'

{
  "id": "c0ffee00-1111-4222-8333-444455556666",
  "environment": "live",
  "externalId": "user_abc123",
  "name": "Yacine B.",
  "email": "yacine@example.dz",
  "phone": "0770000000",
  "defaultMethod": "baridimob",
  "locale": "ar",
  "version": 1,
  "createdAt": "2026-07-13T10:00:00.000Z",
  "updatedAt": "2026-07-13T10:00:00.000Z"
}

قراءة زبون وتحديثه

GET /customers?externalId= هو نمط البحث ثم الإنشاء (lookup / upsert): ابحث بمعرفك الخاص، وأنشئ الزبون إذا رجعت القائمة فارغة. هكذا يحل الزبون دون تخزين أي معرف id من lahsab.

بدون مرشح، يعرض GET /customers زبائن البيئة الحالية.

يقبل PATCH الحقول name و email و phone و defaultMethod و locale و metadata. أما externalId فهو غير قابل للتعديل. مرر "locale": null للعودة إلى لغتك الافتراضية.

الأخطاء: 401 AUTH_UNAUTHORIZED، 404 CUSTOMER_NOT_FOUND.

# Lookup par votre propre identifiant : le motif upsert.
curl "https://api.lahsab.com/customers?externalId=user_abc123" \
  -H "x-api-key: lsk_live_CLE"

curl https://api.lahsab.com/customers/CUSTOMER_ID \
  -H "x-api-key: lsk_live_CLE"

curl -X PATCH https://api.lahsab.com/customers/CUSTOMER_ID \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -d '{ "phone": "0771111111" }'

المنتجات

المنتج هو ما تبيعه، لا تسعيرته. التسعيرة هي السعر (أدناه)، والمنتج الواحد يمكن أن يحمل عدة أسعار.

الحقل	النوع	مطلوب	التفاصيل
name	string	نعم	مثلا «Abonnement Pro».
description	string	لا
metadata	object	لا	كائن JSON حر.

يقبل PATCH الحقول name و description و active و metadata. مرر active: false لسحب المنتج من الكتالوج دون المساس بالسجل التاريخي.

الأخطاء: 400 VALIDATION_ERROR، 401 AUTH_UNAUTHORIZED، 404 PRODUCT_NOT_FOUND.

curl -X POST https://api.lahsab.com/products \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: prod-pro" \
  -d '{ "name": "Abonnement Pro", "description": "Accès complet" }'

curl https://api.lahsab.com/products \
  -H "x-api-key: lsk_live_CLE"

curl -X PATCH https://api.lahsab.com/products/PRODUCT_ID \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -d '{ "name": "Abonnement Pro (mensuel)" }'

{
  "id": "3b2a1c09-8d7e-4f65-a432-1098765fedcb",
  "environment": "live",
  "name": "Abonnement Pro",
  "description": "Accès complet",
  "active": true,
  "version": 1,
  "createdAt": "2026-07-13T10:00:00.000Z",
  "updatedAt": "2026-07-13T10:00:00.000Z"
}

إنشاء سعر

السعر يربط مبلغا ووتيرة بمنتج. وهو ما يشترك فيه الزبون.

الحقل	النوع	مطلوب	التفاصيل
productId	uuid	نعم	المنتج المسعر.
amount	int	نعم	عدد صحيح موجب تماما (DZD).
type	string	نعم	one_time أو recurring.
interval	string	إذا كان recurring	day، week، month، year.
intervalCount	int	لا	مضاعف الفترة (من 1 إلى 52). القيمة الافتراضية 1.
trialPeriodDays	int	لا	تجربة مجانية (من 0 إلى 365).
nickname	string	لا	تسمية داخلية.
metadata	object	لا	كائن JSON حر.

الاشتراك الفصلي يعبر عنه بالمزج بين interval: "month" و intervalCount: 3.

الأخطاء: 400 VALIDATION_ERROR، 401 AUTH_UNAUTHORIZED، 404 PRODUCT_NOT_FOUND، 409 IDEMPOTENCY_KEY_REUSED.

curl -X POST https://api.lahsab.com/prices \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: price-pro-mensuel-2500" \
  -d '{
    "productId": "3b2a1c09-8d7e-4f65-a432-1098765fedcb",
    "amount": 2500,
    "type": "recurring",
    "interval": "month",
    "intervalCount": 1,
    "nickname": "Pro mensuel"
  }'

{
  "id": "9f8e7d6c-5b4a-4321-9876-543210fedcba",
  "environment": "live",
  "productId": "3b2a1c09-8d7e-4f65-a432-1098765fedcb",
  "productName": "Abonnement Pro",
  "nickname": "Pro mensuel",
  "amount": 2500,
  "type": "recurring",
  "interval": "month",
  "intervalCount": 1,
  "active": true,
  "version": 1,
  "createdAt": "2026-07-13T10:00:00.000Z",
  "updatedAt": "2026-07-13T10:00:00.000Z"
}

عرض الأسعار وأرشفتها

يعرض GET /prices?productId=&active=true الكتالوج القابل للبيع لمنتج معين.

لذلك لا يقبل PATCH سوى nickname و active و metadata. أرشفة سعر لا تمس الاشتراكات القائمة عليه: تستمر فوترتها بالمبلغ المتفق عليه.

الأخطاء: 400 VALIDATION_ERROR، 401 AUTH_UNAUTHORIZED، 404 PRICE_NOT_FOUND.

curl "https://api.lahsab.com/prices?productId=PRODUCT_ID&active=true" \
  -H "x-api-key: lsk_live_CLE"

# Archiver un tarif : on ne le modifie pas, on le retire du catalogue.
curl -X PATCH https://api.lahsab.com/prices/PRICE_ID \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -d '{ "active": false }'

الكوبونات

الكوبون يعرف تخفيضا قابلا لإعادة الاستعمال، بنسبة مئوية أو بمبلغ ثابت. يطبق عند إنشاء الاشتراك (الحقل couponId في POST /subscriptions) ويعدل مبلغ كل فاتورة حسب قيمة duration.

الحقل	النوع	مطلوب	التفاصيل
name	string	نعم	يعرض للمشتري على الفاتورة وصفحة الدفع.
percentOff	int	أحد الحقلين	من 1 إلى 100. لا يجتمع مع amountOff.
amountOff	int	أحد الحقلين	عدد صحيح موجب (د.ج). لا يجتمع مع percentOff.
duration	string	نعم	forever (كل الفواتير) أو once (الفاتورة الأولى فقط).
metadata	object	لا	كائن JSON حر.

أرشفة كوبون (active: false) تمنع تطبيقه على الاشتراكات الجديدة. أما الاشتراكات التي تحمله فتحتفظ بتخفيضها: الالتزام الممنوح يبقى ساريا.

الكوبون بالنسبة المئوية يواكب تغيرات الأسعار: -50 % تبقى -50 % مهما كانت التسعيرة المعتمدة لاحقا.

كل فاتورة مخفضة تحمل لقطة تدقيق: amountSubtotal (المبلغ الكامل) و discountAmount (التخفيض المطبق) و couponId و couponName. تبقى الفاتورة مفهومة بذاتها حتى لو أرشف الكوبون أو أعيدت تسميته لاحقا.

الأخطاء: 400 VALIDATION_ERROR، 401 AUTH_UNAUTHORIZED، 404 COUPON_NOT_FOUND، 409 IDEMPOTENCY_KEY_REUSED.

curl -X POST https://api.lahsab.com/coupons \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: coupon-founder" \
  -d '{
    "name": "founder",
    "percentOff": 50,
    "duration": "forever"
  }'

curl "https://api.lahsab.com/coupons?active=true" \
  -H "x-api-key: lsk_live_CLE"

# Archiver un coupon : il ne s'applique plus aux nouveaux abonnements.
curl -X PATCH https://api.lahsab.com/coupons/COUPON_ID \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -d '{ "active": false }'

{
  "id": "7d6c5b4a-3210-4fed-9cba-876543210fed",
  "environment": "live",
  "name": "founder",
  "percentOff": 50,
  "duration": "forever",
  "active": true,
  "version": 1,
  "createdAt": "2026-07-23T10:00:00.000Z",
  "updatedAt": "2026-07-23T10:00:00.000Z"
}

إنشاء اشتراك

نقطة الدخول إلى مسار الشراء. نداء واحد: ينشأ الاشتراك، وتصدر الفاتورة الأولى، وتحمل الاستجابة رابط الدفع. وهو المقابل لما يقدمه Stripe Checkout.

الحقل	النوع	مطلوب	التفاصيل
customerId	uuid	نعم	الزبون صاحب الاشتراك.
priceId	uuid	نعم	يجب أن يكون سعرا recurring و active.
daysUntilDue	int	لا	مهلة الدفع الممنوحة (من 0 إلى 365). القيمة الافتراضية 7.
invoiceLeadDays	int	لا	عدد الأيام قبل نهاية الفترة التي تصدر فيها فاتورة التجديد. القيمة الافتراضية 7.
trialPeriodDays	int	لا	تجربة مجانية. لها الأولوية على تجربة السعر.
cancelAt	datetime	لا	أجل محدد: ينتهي الاشتراك في هذا التاريخ مهما كانت فترة السعر. يجب أن يكون في المستقبل (وبعد نهاية التجربة إن وجدت).
couponId	uuid	لا	يطبق كوبونا نشطا: تخفض كل فاتورة حسب قيمة duration. كوبون واحد لكل اشتراك.
locale	string	لا	fr أو ar: يثبت لغة كل فواتير هذا الاشتراك، بما فيها التجديدات. بدونه تقرأ كل فاتورة لغة الزبون من جديد.
returnUrl	string	لا	إلى أين يعاد المشتري انطلاقا من الصفحة. يجب أن يكون النطاق ضمن قائمتك البيضاء. انظر العودة إلى موقعك.
metadata	object	لا	كائن JSON حر.

يولد الاشتراك بالحالة incomplete: وجه المشتري إلى latestInvoice.hostedInvoiceUrl. وسينتقل إلى active عند استقبال invoice.paid، وليس قبل ذلك أبدا.

مع تجربة مجانية: لا فاتورة فورية. يولد الاشتراك بالحالة trialing، وتساوي currentPeriodEnd قيمة trialEnd، ويكون latestInvoice غائبا.

مع cancelAt: تتقدم الفترات كالمعتاد، لكن كل فترة جديدة تتوقف عند cancelAt على أقصى تقدير. الفترة الأخيرة تكون إذن مبتورة، وتعرض فاتورتها الفترة الحقيقية، ولا يصدر أي تجديد بعدها. المثال النموذجي: اشتراك سنوي يباع في سبتمبر وينتهي في 30 جوان، بفاتورة واحدة.

الأخطاء: 400 VALIDATION_ERROR، 400 SUBSCRIPTION_CANCEL_AT_INVALID، 400 MERCHANT_LOCALE_NOT_AVAILABLE، 400 MERCHANT_RETURN_URL_NOT_ALLOWED، 400 COUPON_ARCHIVED، 401 AUTH_UNAUTHORIZED، 404 CUSTOMER_NOT_FOUND، 404 PRICE_NOT_FOUND، 404 COUPON_NOT_FOUND، 400 PRICE_INACTIVE، 400 PRICE_NOT_RECURRING، 409 MERCHANT_PAYMENT_DETAILS_MISSING، 409 IDEMPOTENCY_KEY_REUSED.

curl -X POST https://api.lahsab.com/subscriptions \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: sub-user_abc123-pro-mensuel" \
  -d '{
    "customerId": "c0ffee00-1111-4222-8333-444455556666",
    "priceId": "9f8e7d6c-5b4a-4321-9876-543210fedcba",
    "daysUntilDue": 7,
    "invoiceLeadDays": 7
  }'

# Terme fixe + réduction : un pass saison à -50 %, qui se termine le 30 juin.
curl -X POST https://api.lahsab.com/subscriptions \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: sub-user_abc123-pass-saison" \
  -d '{
    "customerId": "c0ffee00-1111-4222-8333-444455556666",
    "priceId": "PASS_SAISON_PRICE_ID",
    "cancelAt": "2027-06-30T00:00:00.000Z",
    "couponId": "COUPON_ID"
  }'

const res = await fetch("https://api.lahsab.com/subscriptions", {
  method: "POST",
  headers: {
    "x-api-key": process.env.LAHSAB_API_KEY,
    "content-type": "application/json",
    "Idempotency-Key": `sub-${user.id}-pro-mensuel`,
  },
  body: JSON.stringify({
    customerId: customer.id,
    priceId: PRO_MENSUEL,
    daysUntilDue: 7,
  }),
});
const subscription = await res.json();

window.location.href = subscription.latestInvoice.hostedInvoiceUrl;

{
  "id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "environment": "live",
  "status": "incomplete",
  "collectionMethod": "send_invoice",
  "daysUntilDue": 7,
  "invoiceLeadDays": 7,
  "currentPeriodStart": "2026-07-13T00:00:00.000Z",
  "currentPeriodEnd": "2026-08-13T00:00:00.000Z",
  "cancelAtPeriodEnd": false,
  "latestInvoice": {
    "id": "f1e2d3c4-b5a6-4978-8b1c-2d3e4f5a6b7c",
    "number": "LSB-2026-0042",
    "status": "open",
    "amountDue": 2500,
    "dueDate": "2026-07-20T00:00:00.000Z",
    "hostedInvoiceUrl": "https://dashboard.lahsab.com/invoice/f1e2d3c4-b5a6-4978-8b1c-2d3e4f5a6b7c",
    "version": 2,
    "createdAt": "2026-07-13T10:00:00.000Z",
    "updatedAt": "2026-07-13T10:00:00.000Z"
  },
  "version": 2,
  "createdAt": "2026-07-13T10:00:00.000Z",
  "updatedAt": "2026-07-13T10:00:00.000Z"
}

الاطلاع على اشتراك

المرشحات: customerId، status.

currentPeriodEnd هو التاريخ الوحيد المهم: معناه «مدفوع حتى هذا التاريخ». ولا يتقدم إلا عند دفع فاتورة الفترة الموالية، ولا يتقدم أبدا لمجرد صدور فاتورة. راجع القاعدة الذهبية.

يعرض الاشتراك أيضا cancelAt (الأجل المحدد إن وجد) و discount.coupon (الكوبون المطبق)، في API كما في حمولات webhooks.

الأخطاء: 401 AUTH_UNAUTHORIZED، 404 SUBSCRIPTION_NOT_FOUND.

curl "https://api.lahsab.com/subscriptions?customerId=CUSTOMER_ID&status=active" \
  -H "x-api-key: lsk_live_CLE"

curl https://api.lahsab.com/subscriptions/SUBSCRIPTION_ID \
  -H "x-api-key: lsk_live_CLE"

الإلغاء والاستئناف

الحقل	النوع	مطلوب	التفاصيل
atPeriodEnd	bool	لا	القيمة الافتراضية true.

atPeriodEnd: true (الوضع الافتراضي) يبرمج الإلغاء: تصبح قيمة cancelAtPeriodEnd هي true، ويبقى الاشتراك active حتى نهاية الفترة المدفوعة، ولن تصدر أي فاتورة تجديد. وهذا هو السلوك المطلوب: الزبون دفع حتى currentPeriodEnd ومن حقه الاستفادة إلى ذلك التاريخ.

atPeriodEnd: false ينهي الاشتراك فورا: الحالة canceled مع ضبط endedAt. والفترة المدفوعة تضيع.

يتراجع resume عن إلغاء مبرمج ما دامت الفترة جارية. أما اشتراك صار canceled فلا يستأنف: 409 SUBSCRIPTION_INVALID_TRANSITION.

الأخطاء: 401 AUTH_UNAUTHORIZED، 404 SUBSCRIPTION_NOT_FOUND، 409 SUBSCRIPTION_ALREADY_CANCELED، 409 SUBSCRIPTION_INVALID_TRANSITION.

# Par défaut : à la fin de la période déjà payée.
curl -X POST https://api.lahsab.com/subscriptions/SUBSCRIPTION_ID/cancel \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -d '{ "atPeriodEnd": true }'

# Revenir sur une annulation programmée.
curl -X POST https://api.lahsab.com/subscriptions/SUBSCRIPTION_ID/resume \
  -H "x-api-key: lsk_live_CLE"

{
  "id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "status": "active",
  "cancelAtPeriodEnd": true,
  "canceledAt": "2026-07-13T10:00:00.000Z",
  "currentPeriodEnd": "2026-08-13T00:00:00.000Z"
}

إنشاء فاتورة لمرة واحدة

فاتورة خارج أي اشتراك: خدمة، تسبيق، طلبية. تصدر نهائية (أي مرقمة) فور إنشائها، و hostedInvoiceUrl هو رابط الصفحة التي ترسلها إلى الزبون.

الحقل	النوع	مطلوب	التفاصيل
customerId	uuid	نعم
amount	int	نعم	عدد صحيح موجب تماما (DZD).
description	string	لا	موضوع الفوترة (280 حرفا كحد أقصى).
dueDate	date	لا	تاريخ الاستحقاق (YYYY-MM-DD). القيمة الافتراضية: يومان.
locale	string	لا	fr أو ar: لغة الفاتورة المستضافة. القيمة الافتراضية: لغة الزبون، وإلا لغتك.
returnUrl	string	لا	إلى أين يعاد المشتري انطلاقا من الصفحة. يجب أن يكون النطاق ضمن قائمتك البيضاء. انظر العودة إلى موقعك.

أما فواتير الاشتراكات فتصدر تلقائيا، ولا حاجة لإنشائها بنفسك.

الأخطاء: 400 VALIDATION_ERROR، 400 MERCHANT_LOCALE_NOT_AVAILABLE، 400 MERCHANT_RETURN_URL_NOT_ALLOWED، 401 AUTH_UNAUTHORIZED، 404 CUSTOMER_NOT_FOUND، 409 MERCHANT_PAYMENT_DETAILS_MISSING، 409 IDEMPOTENCY_KEY_REUSED.

curl -X POST https://api.lahsab.com/invoices \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: inv-CMD-1042" \
  -d '{
    "customerId": "c0ffee00-1111-4222-8333-444455556666",
    "amount": 12000,
    "description": "Installation sur site",
    "dueDate": "2026-07-31"
  }'

{
  "id": "a1b2c3d4-e5f6-4789-8abc-def012345678",
  "environment": "live",
  "customerId": "c0ffee00-1111-4222-8333-444455556666",
  "number": "LSB-2026-0043",
  "status": "open",
  "amountDue": 12000,
  "amountPaid": 0,
  "description": "Installation sur site",
  "locale": "fr",
  "dueDate": "2026-07-31T00:00:00.000Z",
  "finalizedAt": "2026-07-13T10:00:00.000Z",
  "hostedInvoiceUrl": "https://dashboard.lahsab.com/invoice/a1b2c3d4-e5f6-4789-8abc-def012345678",
  "version": 2,
  "createdAt": "2026-07-13T10:00:00.000Z",
  "updatedAt": "2026-07-13T10:00:00.000Z"
}

الاطلاع على فاتورة

المرشحات: customerId، subscriptionId، status.

GET /invoices?status=open هو قائمة المستحقات غير المدفوعة عندك. و status=uncollectible هو قائمة الخسائر.

فاتورة الاشتراك تحمل periodStart / periodEnd، وتحمل checkoutUrl ما دامت لها دفعة قابلة للدفع جارية.

الأخطاء: 401 AUTH_UNAUTHORIZED، 404 INVOICE_NOT_FOUND.

curl "https://api.lahsab.com/invoices?customerId=CUSTOMER_ID&status=open" \
  -H "x-api-key: lsk_live_CLE"

curl https://api.lahsab.com/invoices/INVOICE_ID \
  -H "x-api-key: lsk_live_CLE"

الإلغاء

يلغي void فاتورة بالحالة open: لم تعد قابلة للدفع، لكنها تحتفظ برقمها (التسلسل القانوني لا يعاد استعماله). والفاتورة المدفوعة لا تلغى (409 INVOICE_ALREADY_PAID).

الأخطاء: 401 AUTH_UNAUTHORIZED، 404 INVOICE_NOT_FOUND، 409 INVOICE_ALREADY_PAID، 409 INVOICE_INVALID_TRANSITION.

# Annuler une facture ouverte.
curl -X POST https://api.lahsab.com/invoices/INVOICE_ID/void \
  -H "x-api-key: lsk_live_CLE"

صفحة الفاتورة

بدون أي مصادقة: هذا ما تقدمه صفحة الفاتورة المستضافة (/invoice/:id) لمتصفح زبونك. وهو الرابط الذي تلصقه في محادثة WhatsApp.

يرجع عرضا عموميا: المبلغ وتاريخ الاستحقاق والحالة ووسائل التحصيل الخاصة بك داخل methods (بنفس شكل صفحة الدفع، الوسائل المفعلة والمكتملة فقط). لا مفتاح ولا سر ولا metadata ولا externalId أبدا.

الأخطاء: 404 INVOICE_NOT_FOUND.

curl https://api.lahsab.com/invoices/INVOICE_ID/public

{
  "id": "f1e2d3c4-b5a6-4978-8b1c-2d3e4f5a6b7c",
  "number": "LSB-2026-0042",
  "status": "open",
  "environment": "live",
  "amountDue": 2500,
  "amountPaid": 0,
  "locale": "ar",
  "locales": ["fr", "ar"],
  "dueDate": "2026-07-20T00:00:00.000Z",
  "customerName": "Yacine B.",
  "hasProof": false,
  "merchantConfigured": true,
  "methods": [
    {
      "method": "baridimob",
      "holder": "SARL ACME",
      "rip": "00799999012345678912"
    }
  ],
  "merchant": {
    "displayName": "ACME Store",
    "supportEmail": "support@acme.dz"
  }
}

فتح جلسة بوابة

يرجع عنوان URL يجد فيه زبونك اشتراكه وفواتيره وزرا للدفع. إنها صفحة «تسيير اشتراكي» التي لا تحتاج إلى بنائها بنفسك.

الحقل	النوع	مطلوب	التفاصيل
customerId	uuid	نعم
returnUrl	string	لا	إلى أين يعاد المشتري انطلاقا من الصفحة. يجب أن يكون النطاق ضمن قائمتك البيضاء. انظر العودة إلى موقعك.

الرابط صالح لمدة ساعة واحدة. والصفحة نفسها (/portal/:token) عمومية، يفتحها حامل الرابط.

الأخطاء: 400 VALIDATION_ERROR، 400 MERCHANT_RETURN_URL_NOT_ALLOWED، 401 AUTH_UNAUTHORIZED، 404 CUSTOMER_NOT_FOUND.

curl -X POST https://api.lahsab.com/portal-sessions \
  -H "x-api-key: lsk_live_CLE" \
  -H "content-type: application/json" \
  -d '{ "customerId": "c0ffee00-1111-4222-8333-444455556666" }'

{
  "url": "https://dashboard.lahsab.com/portal/ps_7f3c2e1a9b4d4e6a8c1f2d3e",
  "expiresAt": "2026-07-13T11:00:00.000Z"
}