واجهة فواتير التاجر
إدارة الفواتير
إنشاء وإدارة الفواتير باستخدام عناصر جديدة أو عناصر موجودة أو كليهما. تحديث حالة الفاتورة وإدارة العناصر بشكل ديناميكي.
نقاط النهاية للواجهة البرمجية
POST
https://sofizpay.com/merchant/invoices/create/إنشاء فاتورة جديدة باستخدام عناصر جديدة أو عناصر موجودة أو كليهما
POST
https://sofizpay.com/merchant/invoices/update/تحديث فاتورة موجودة، إضافة/إزالة عناصر، تغيير الحالة
GET
https://sofizpay.com/merchant/invoices/الحصول على الفواتير لتاجر مع دعم الفلترة والتقسيم الصفحات
اختر الطريقة
جميع النِّقاط تتطلب مصادقة Sofizpay باستخدام معامل encrypted_sk
معاملات الطلب (POST)
| المعامل | النوع | مطلوب | الوصف |
|---|---|---|---|
encrypted_sk | string | نعم | المفتاح السري المشفر (Base64) للمصادقة |
amount | number | نعم | إجمالي مبلغ الفاتورة |
items | array | لا | مصفوفة العناصر الجديدة لإضافتها إلى الفاتورة |
existing_item_ids | array | لا | مصفوفة معرفات العناصر الموجودة مع الكميات |
status | string | لا | حالة الفاتورة (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 وتحقق من صحة جميع الاستجابات على الخادم الخاص بك.