SofizPay Logo

SofizPay

SofizPay Logo
SofizPay
التوثيق التقني
واجهة برمجة تطبيقات دفع الفواتير

دفع فواتير الخدمات العمومية في الجزائر

سدد فواتير الخدمات العمومية الجزائرية (سونلغاز، اتصالات الجزائر، الجزائرية للمياه ADE، سيال SEAAL) بسرعة وأمان وفق معايير الربط الرسمية الموحدة

المسار القياسي المتكامل لدفع الفواتير (3 مراحل)

المرحلة 1: استعلام وجلب الفاتورة الحية

التحقق من الفواتير المعلقة، المبلغ المستحق، والمفتاح المشفر من مزود الخدمة قبل الشروع في الدفع.

POST /api/operations/fetch/{service}/
المرحلة 2: حفظ ميتاداتا الفاتورة في السيرفر

حفظ البيانات التفصيلية للفاتورة لضمان تتبعها (مفتاح EBB لسونلغاز، كود الدفع لـ ADE، رقم الهاتف لـ AT، كود الزبون لـ SEAAL).

POST /api/operations/facture-data/
المرحلة 3: تسديد الفاتورة مالياً

إرسال أمر الخصم والتسوية المالية النهائي عبر المفتاح السري المشفر (encrypted_sk).

POST /services/operation_post

المفتاح العام للتشفير ومصادقة الطلبات (RSA-OAEP)

تشفير المفتاح السري لـ SofizPay (encrypted_sk)

خوارزمية RSA-OAEP SHA-256ترميز Base64 (344 محرف)الموضع: جسم الطلب (JSON Body)

لحماية المفتاح السري (SofizPay Secret Key) ومنع تداوله بنص صريح عبر الشبكة، تتطلب جميع عمليات جلب ودفع الفواتير تشفير المفتاح السري بواسطة المفتاح العام الرسمي لـ SofizPay عبر خوارزمية RSA-OAEP SHA-256، وتمرير الناتج بصيغة Base64 داخل الـ JSON Body تحت الحقل encrypted_sk.

المفتاح العام الرسمي (RSA 2048-bit Public Key)

bash
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAv9toBr7vZ4XIkVzlzdGR
vNVaKw7A9Z3/Vnq3bK8fLaaUTmoweL3CEKSbz1lxYUjzuRzY/nmDuCpPS/7t0i5c
kWRifPaPgIoiUFr1fGLzjN+cttxtvbPQof2Zuxllbq5ox+XyZpc1eo8PjwhRobCB
djDZ1iSV1VkhOWanrnNXeXFzUnRYHQUZmQ8FWOFQ8D9vUZanmq/ZJ6nJ4SZoj2lV
dKrLBbh/MWtn9MmyrPrywoJYCnc7c+ylJIWnAhNv4jTafB5bqDTd6oSElV9lQqPf
diO93j+Q/uBoAZQZ2EqWY0E4Ooz4Dd9dHl7EiNiAh19G9VTcBFN/QfXOdyCGajwC
WwIDAQAB
-----END PUBLIC KEY-----
يمكنك تضمين هذا المفتاح في تطبيقك، أو جلبه لحظياً عبر طلب GET https://epay.sofizpay.com/api/operations/public-key/

أمثلة برمجية لتشفير المفتاح السري

python
1import base64
2from cryptography.hazmat.primitives.asymmetric import padding
3from cryptography.hazmat.primitives import serialization, hashes
4from cryptography.hazmat.backends import default_backend
5
6SOFIZ_PUBLIC_KEY_PEM = """-----BEGIN PUBLIC KEY-----
7MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAv9toBr7vZ4XIkVzlzdGR
8vNVaKw7A9Z3/Vnq3bK8fLaaUTmoweL3CEKSbz1lxYUjzuRzY/nmDuCpPS/7t0i5c
9kWRifPaPgIoiUFr1fGLzjN+cttxtvbPQof2Zuxllbq5ox+XyZpc1eo8PjwhRobCB
10djDZ1iSV1VkhOWanrnNXeXFzUnRYHQUZmQ8FWOFQ8D9vUZanmq/ZJ6nJ4SZoj2lV
11dKrLBbh/MWtn9MmyrPrywoJYCnc7c+ylJIWnAhNv4jTafB5bqDTd6oSElV9lQqPf
12diO93j+Q/uBoAZQZ2EqWY0E4Ooz4Dd9dHl7EiNiAh19G9VTcBFN/QfXOdyCGajwC
13WwIDAQAB
14-----END PUBLIC KEY-----"""
15
16def encrypt_sofizpay_sk(secret_key: str, public_key_pem: str = SOFIZ_PUBLIC_KEY_PEM) -> str:
17    """Encrypts SofizPay Secret Key (S...) using RSA-OAEP SHA-256 for encrypted_sk"""
18    pub_key = serialization.load_pem_public_key(
19        public_key_pem.strip().encode('utf-8'),
20        backend=default_backend()
21    )
22    ciphertext = pub_key.encrypt(
23        secret_key.strip().encode('utf-8'),
24        padding.OAEP(
25            mgf=padding.MGF1(algorithm=hashes.SHA256()),
26            algorithm=hashes.SHA256(),
27            label=None
28        )
29    )
30    return base64.b64encode(ciphertext).decode('utf-8')
31
32# Example usage in API request body:
33# payload = {"encrypted_sk": encrypt_sofizpay_sk("S..."), "customer_num": "00000000000"}

المرحلة 1: استعلام وجلب الفواتير الحية (Fetch Bills API)

POST https://epay.sofizpay.com/api/operations/fetch/{service}/

تتيح نقطة النهاية هذه فحص واسترجاع الفواتير غير المسددة مباشرة من أنظمة المؤسسات الجزائرية بالربط اللحظي، مما يسمح بالتحقق من قيمة الفاتورة الدقيقة ورقمها المرجعي ومفتاح التتبع قبل الخصم والتسوية.

POSThttps://epay.sofizpay.com/api/operations/fetch/sonelgaz/
Content-Type: application/jsonالمصادقة: encrypted_sk (داخل جسم الطلب)

طلب الاستعلام (Fetch Request)

cURL
bash
curl --location 'https://epay.sofizpay.com/api/operations/fetch/sonelgaz/' --header 'Content-Type: application/json' --data '{
    "encrypted_sk": "YOUR_ENCRYPTED_SECRET_KEY",
    "customer_num": "00000000000"
}'

نموذج استجابة الفاتورة المسترجعة (Fetch Response)

200 OK
json
{
  "bills": [
    {
      "value": "000000000000",
      "label": "[1500.00 DZD] [000000000000]",
      "amount": 1500.00,
      "bill_number": "000000000000",
      "customer_num": "00000000000",
      "ebb": "000",
      "isIdoom": false
    }
  ],
  "customer_num": "00000000000"
}
ملاحظة: تُرجع الاستجابة مصفوفة bills تحتوي على تفاصيل الفاتورة والمبلغ المستحق بالدينار الجزائري، والتي تُستخدم في المرحلة التالية لحفظ الميتاداتا ثم تنفيذ أمر الدفع.

معاملات طلب الاستعلام (Fetch Parameters)

المعاملالموضعالنوعالوصفمطلوب لـ
encrypted_skجسم الطلب (Body)نص (string)المفتاح السري المشفر للمصادقة وتنفيذ العمليةالكل (جميع الخدمات)
customer_numجسم الطلب (Body)نص (string)رقم الزبون الخاص بسونلغاز (11 خانة مثل 00000000000) مستخرج من الفاتورة أو شفرة Data Matrixسونلغاز
bill_numberجسم الطلب (Body)نص (string)رقم الفاتورة الخاص بسونلغاز (اختياري للتحقق والتدقيق المباشر)سونلغاز (اختياري)
ebbجسم الطلب (Body)نص (string)مفتاح التحقق EBB المستخرج من باركود فاتورة سونلغاز (اختياري)سونلغاز (اختياري)
ndجسم الطلب (Body)نص (string)رقم هاتف الخط الثابت أو كود خدمة أيدوم Idoom (مثل 021000000)اتصالات الجزائر
c_paiementجسم الطلب (Body)نص (string)كود الدفع الإلكتروني (Code de Paiement) المطبوع على فاتورة الجزائرية للمياه ADEالجزائرية للمياه
customer_numجسم الطلب (Body)نص (string)رقم الزبون أو العميل المرجعي الخاص بمياه سيال الجزائر وتيبازةسيال SEAAL

المرحلة 2: حفظ ميتاداتا الفاتورة في السيرفر — POST /api/operations/facture-data/

حفظ البيانات التفصيلية للفاتورة لضمان تتبعها (مفتاح EBB لسونلغاز، كود الدفع لـ ADE، رقم الهاتف لـ AT، كود الزبون لـ SEAAL).

bash
curl --location 'https://epay.sofizpay.com/api/operations/facture-data/' --header 'Content-Type: application/json' --data '{
    "encrypted_sk": "YOUR_ENCRYPTED_SECRET_KEY",
    "facture_number": "000000000000",
    "bill_number": "000000000000",
    "ebb": "000",
    "customer_number": "00000000000"
}'

المرحلة 3: تسديد الفاتورة مالياً — POST /services/operation_post

سونلغاز

سونلغاز

الشركة الوطنية للكهرباء والغاز (Sonelgaz)

مثال على طلب التسديد

bash
curl --location 'https://sofizpay.com/services/operation_post' --header 'Content-Type: application/json' --data '{      
    "encrypted_sk": "YOUR_ENCRYPTED_SECRET_KEY",
    "amount": 1500.00,
    "operator": "sonelgaz",
    "offer": "sonelgaz",
    "bill": "000000000000",
    "customerId": "",
    "customernumber": " ",
    "ebb": " "
}'
رمز المشغل (Operator)
"sonelgaz"
الحقول المطلوبة
encrypted_skamountoperator: "sonelgaz"offer: "sonelgaz"billebbcustomerId
اتصالات الجزائر

اتصالات الجزائر

اتصالات الجزائر أيدوم (Algérie Télécom)

مثال على طلب التسديد

bash
curl --location 'https://sofizpay.com/services/operation_post' --header 'Content-Type: application/json' --data '{      
    "encrypted_sk": "YOUR_ENCRYPTED_SECRET_KEY",
    "amount": 645.00,
    "montant": 645.00,
    "operator": "AT",
    "offer": "AT",
    "phone": "021000000",
    "bill": "021000000",
    "bill_number": "021000000",
    "memo": "00:021000000"
}'
رمز المشغل (Operator)
"AT"
الحقول المطلوبة
encrypted_skamountmontantoperator: "AT"offer: "AT"phonebillmemo: "00:nd"
الجزائرية للمياه

الجزائرية للمياه

الجزائرية للمياه (Algérienne Des Eaux)

مثال على طلب التسديد

bash
curl --location 'https://sofizpay.com/services/operation_post' --header 'Content-Type: application/json' --data '{      
    "encrypted_sk": "YOUR_ENCRYPTED_SECRET_KEY",
    "amount": 2500,
    "operator": "ade",
    "offer": "ade",
    "bill": "0000000000",
    "c_paiement": "0000000000",
    "customerId": "0000000000"
}'
رمز المشغل (Operator)
"ade"
الحقول المطلوبة
encrypted_skamountoperator: "ade"offer: "ade"billc_paiementcustomerId
سيال SEAAL

سيال SEAAL

شركة المياه والتطهير للجزائر وتيبازة (SEAAL)

مثال على طلب التسديد

bash
curl --location 'https://sofizpay.com/services/operation_post' --header 'Content-Type: application/json' --data '{      
    "encrypted_sk": "YOUR_ENCRYPTED_SECRET_KEY",
    "amount": 1800,
    "operator": "seaal",
    "offer": "SEAAL",
    "phone": "00000000",
    "bill": "00000000",
    "memo": "00:00000000"
}'
رمز المشغل (Operator)
"seaal"
الحقول المطلوبة
encrypted_skamountoperator: "seaal"offer: "SEAAL"phonebillmemo: "00:num"

معاملات طلب التسديد

المعاملالنوعالوصفمطلوب لـ
encrypted_skنص (string)المفتاح السري المشفر للمصادقة وتنفيذ العمليةالكل (جميع الخدمات)
amountرقم (number)مبلغ الفاتورة بالدينار الجزائري (DZD)الكل (جميع الخدمات)
operatorنص (string)مقدم الخدمة: sonelgaz أو AT أو ade أو seaalالكل (جميع الخدمات)
offerنص (string)نوع العرض: sonelgaz أو AT أو ade أو SEAALالكل (جميع الخدمات)
billنص (string)رقم الفاتورة أو المرجع أو كود الدفعالكل (جميع الخدمات)
ebbنص (string)مفتاح التحقق EBB المستخرج من باركود فاتورة سونلغازسونلغاز
c_paiementنص (string)كود الدفع الإلكتروني لفاتورة الجزائرية للمياه ADEالجزائرية للمياه
phoneنص (string)رقم الهاتف الثابت أو كود الزبون (اتصالات الجزائر، سيال)اتصالات الجزائر / سيال
memoنص (string)بيان العملية بصيغة 00:{رقم} (اتصالات الجزائر، سيال)اتصالات الجزائر / سيال
montantرقم (number)قيمة الفاتورة بالدينار الممررة لاتصالات الجزائر / أيدوماتصالات الجزائر

استجابة تأكيد التسديد الناجحة (200)

json
{
    "status": "success",
    "message": "Bill payment completed successfully",
    "operation_id": "OP_DZ_000000000000",
    "transaction_id": "TXN_000000000",
    "transaction_status": "confirmed"
}

ملاحظة: تتم معالجة الفاتورة عبر بوابة SofizPay ويتم إصدار إشعار وتأكيد التسديد فوراً.