SofizPay Logo

SofizPay

SofizPay Logo
SofizPay
التوثيق التقني
واجهة فواتير التاجر

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

إنشاء وإدارة الفواتير باستخدام عناصر جديدة أو عناصر موجودة أو كليهما. تحديث حالة الفاتورة وإدارة العناصر بشكل ديناميكي.

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

POSThttps://sofizpay.com/merchant/invoices/create/

إنشاء فاتورة جديدة باستخدام عناصر جديدة أو عناصر موجودة أو كليهما

POSThttps://sofizpay.com/merchant/invoices/update/

تحديث فاتورة موجودة، إضافة/إزالة عناصر، تغيير الحالة

GEThttps://sofizpay.com/merchant/invoices/

الحصول على الفواتير لتاجر مع دعم الفلترة والتقسيم الصفحات

اختر الطريقة

جميع النِّقاط تتطلب مصادقة Sofizpay باستخدام معامل encrypted_sk

معاملات الطلب (POST)

المعاملالنوعمطلوبالوصف
encrypted_skstringنعمالمفتاح السري المشفر (Base64) للمصادقة
amountnumberنعمإجمالي مبلغ الفاتورة
itemsarrayلامصفوفة العناصر الجديدة لإضافتها إلى الفاتورة
existing_item_idsarrayلامصفوفة معرفات العناصر الموجودة مع الكميات
statusstringلاحالة الفاتورة (PENDING, PAID, CANCELLED)

مثال على الطلب

cURL

bash
1curl -X POST "https://sofizpay.com/merchant/invoices/create/" \
2  -H "Content-Type: application/json" \
3  -d '{
4  "encrypted_sk": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUF4...",
5  "amount": 1970,
6  "items": [
7    {
8      "description": "Custom laptop configuration service",
9      "quantity": 1,
10      "unit_price": 150
11    },
12    {
13      "description": "Extended warranty (2 years)",
14      "quantity": 1,
15      "unit_price": 220
16    }
17  ],
18  "existing_item_ids": [
19    {
20      "item_id": "item_001",
21      "quantity": 1
22    },
23    {
24      "item_id": "item_002",
25      "quantity": 1
26    }
27  ]
28}'

Python

python
1import requests
2import json
3
4url = "https://sofizpay.com/merchant/invoices/create/"
5data = {
6  "encrypted_sk": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUF4...",
7  "amount": 1970,
8  "items": [
9    {
10      "description": "Custom laptop configuration service",
11      "quantity": 1,
12      "unit_price": 150
13    },
14    {
15      "description": "Extended warranty (2 years)",
16      "quantity": 1,
17      "unit_price": 220
18    }
19  ],
20  "existing_item_ids": [
21    {
22      "item_id": "item_001",
23      "quantity": 1
24    },
25    {
26      "item_id": "item_002",
27      "quantity": 1
28    }
29  ]
30}
31
32response = requests.post(url, json=data)
33print(response.json())

JavaScript

javascript
1const response = await fetch('https://sofizpay.com/merchant/invoices/create/', {
2  method: 'POST',
3  headers: {
4    'Content-Type': 'application/json',
5  },
6  body: JSON.stringify({
7  "encrypted_sk": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUF4...",
8  "amount": 1970,
9  "items": [
10    {
11      "description": "Custom laptop configuration service",
12      "quantity": 1,
13      "unit_price": 150
14    },
15    {
16      "description": "Extended warranty (2 years)",
17      "quantity": 1,
18      "unit_price": 220
19    }
20  ],
21  "existing_item_ids": [
22    {
23      "item_id": "item_001",
24      "quantity": 1
25    },
26    {
27      "item_id": "item_002",
28      "quantity": 1
29    }
30  ]
31})
32});
33
34const result = await response.json();
35console.log(result);

استجابة ناجحة (200)

تم إنشاء الفاتورة بنجاح مع جميع العناصر والتفاصيل

json
1{
2  "success": true,
3  "message": "Invoice created successfully",
4  "invoice": {
5    "id": "inv_67890",
6    "amount": 1970.00,
7    "status": "PENDING",
8    "created_at": "2025-08-03T12:00:00Z",
9    "updated_at": "2025-08-03T12:00:00Z",
10    "items": [
11      {
12        "id": "invoice_item_001",
13        "description": "Custom laptop configuration service",
14        "quantity": 1,
15        "unit_price": 150.00,
16        "total_price": 150.00
17      },
18      {
19        "id": "invoice_item_002",
20        "description": "Extended warranty (2 years)",
21        "quantity": 1,
22        "unit_price": 220.00,
23        "total_price": 220.00
24      },
25      {
26        "id": "invoice_item_003",
27        "item_id": "item_001",
28        "name": "Samsung Galaxy S24 Ultra",
29        "quantity": 1,
30        "unit_price": 950.00,
31        "total_price": 950.00
32      },
33      {
34        "id": "invoice_item_004",
35        "item_id": "item_002",
36        "name": "MacBook Pro M3",
37        "quantity": 1,
38        "unit_price": 650.00,
39        "total_price": 650.00
40      }
41    ],
42    "total_items": 4,
43    "subtotal": 1970.00
44  }
45}

استجابة خطأ (400/404)

أمثلة على أخطاء شائعة للمصادقة أو التحقق

json
{
  "error": "Invalid secret key"
}

مثال تحديث فاتورة (POST)

تحديث فاتورة موجودة عن طريق إضافة عناصر أو إزالة عناصر أو تغيير تفاصيل العناصر

json
1{
2  "encrypted_sk": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0K...",
3  "invoice_id": "inv_67890",
4  "amount": 2195.00,
5  "status": "PAID",
6  "items_to_add": [
7    {
8      "description": "Express shipping",
9      "quantity": 1,
10      "unit_price": 25.00
11    }
12  ],
13  "items_to_remove": ["invoice_item_001"],
14  "items_to_update": [
15    {
16      "item_id": "invoice_item_003",
17      "quantity": 2,
18      "unit_price": 900.00
19    }
20  ]
21}

ملاحظة أمنية

احفظ مفتاحك السري المشفر بشكل آمن. استخدم HTTPS لجميع استدعاءات API وتحقق من صحة جميع الاستجابات على الخادم الخاص بك.