الفواتير
اعمل فاتورة من السيرفر بتاعك وأصدرها وابعتها، واستمع للأحداث اللي بتقولك إنها اتدفعت، وسجّل دفعات، وأصدر إشعارات دائنة، وأدِر أسعار الضريبة.
الـ Invoice هي مطالبة لعميل واحد، ليها صفحة مستضافة بيدفع منها. السيرفر بتاعك بيعمل مسودة، ويعمل لها finalize، ويبعتها. وXPay بيستضيف صفحة الدفع، ويبعت التذكيرات، ويبعتلك webhook لما الفلوس توصل.
الصفحة دي بتغطّي مسار المطوّر. علشان المسار اللي فريقك بيستخدمه يوم بيوم من لوحة التحكم، شوف الفواتير تحت المميزات.
الـ API بتاع الفواتير ماشي على شكل API الفواتير بتاع Stripe: نفس الكائنات والحالات والإجراءات
وأسماء الأحداث. أسماء الحقول camelCase، والمبالغ أرقام صحيحة بأصغر وحدة (150000 يعني 1,500.00
جنيه). لو اشتغلت قبل كده على فواتير Stripe، فالنموذج ده إنت عارفه.
إزاي بيشتغل
- السيرفر بتاعك بيعمل مسودة بـ
POST /invoices: عميل وبنود. - السيرفر بتاعك بيعمل لها finalize بـ
POST /invoices/:id/finalize. الفاتورة بتاخد رقمها والـhostedInvoiceUrlبتاعها، ومبالغها بتثبت. - السيرفر بتاعك بيبعتها بـ
POST /invoices/:id/send، أو بيشارك الـhostedInvoiceUrlبنفسه. - العميل بيدفع من الصفحة المستضافة، كامل أو على أجزاء أو بالأقساط.
- XPay بيبعت
invoice.paidلما مايفضلش حاجة تتدفع. ده الإشارة إنك تنفّذ الطلب.
إرسال مسودة بيعمل لها finalize الأول، فالخطوتين 2 و3 ممكن يبقوا طلب واحد.
لوحة التحكم بتسمّي الـ finalize إصدار. الفاتورة الصادرة في لوحة التحكم هي فاتورة اتعملها finalize في الـ API.
الحالات
status فيه قيمة من خمس قيم متخزنة. كل تغيير ليه إجراء لوحده، ومابتغيّرش status بتحديث أبدًا.
status | معناها |
|---|---|
draft | بتتعدّل. ملهاش رقم ولا رابط دفع. |
open | اتعملها finalize ومستنية الدفع. |
paid | مايفضلش حاجة تتدفع. |
uncollectible | اتشطبت. لسه ممكن تتدفع، وساعتها بتبقى paid. |
void | اتلغت. وبتحتفظ برقمها. |
displayStatus هي اللي تعرضها للناس. بتضيف تلات قيم محسوبة: scheduled (مسودة فيها automaticallyFinalizesAt)، وpartially_paid، وpast_due.
ابنيها
1. اعمل مسودة
POST /invoices محتاج customerId. وكل حاجة تانية اختيارية، وتقدر تضيفها بعدين بـ PATCH /invoices/:id طول ما الفاتورة مسودة.
curl -X POST https://api.xpay.app/invoices \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: 8b1f6c0e-2a4d-4c7b-9f3a-5e2d1c0b7a66" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cus_3Nf8a2kLmPq9",
"daysUntilDue": 7,
"defaultTaxRateIds": ["txr_3Nf8a2kLmPq9"],
"lines": [
{ "description": "Website design", "quantity": 2, "unitAmount": 150000, "unitLabel": "day" }
],
"delivery": { "channels": ["email"] },
"metadata": { "order_id": "ord_42" }
}'أهم حقول الطلب:
| الحقل | ملاحظات |
|---|---|
customerId | مطلوب. العميل لازم يكون ليه اسم، وإيميل أو رقم موبايل، قبل ما الفاتورة يتعملها finalize. |
lines | لحد 250. البند بياخد priceId من الكتالوج، أو description مع unitAmount. وquantity أقلها 0.001، بلحد 3 أرقام عشرية. |
dueDate أو daysUntilDue | تاريخ (YYYY-MM-DD)، أو عدد أيام بعد الـ finalize (من 0 لـ 365). ابعت واحد بس، مش الاتنين. ولو مابعتش ولا واحد، الفاتورة مستحقة عند الاستلام. |
defaultTaxRateIds | أسعار الضريبة للبنود اللي مالهاش أسعار خاصة بيها. والبند ممكن يكون ليه taxRateIds خاصة بيه، لحد 5. |
discounts | لحد 5 على الفاتورة و5 على كل بند. { "type": "percent", "percent": 10 }، أو { "type": "amount", "amount": 5000 }، أو { "type": "coupon", "couponId": "..." }. |
shipping | { "amount": 5000, "taxRateIds": [] }. |
allowPartialPayments | تسمح للعميل يدفع جزء من المبلغ. وminimumPartialAmount بيحدد أقل دفعة جزئية. |
paymentMethodTypes | طرق الدفع اللي الفاتورة بتقبلها. null معناها الإعداد الافتراضي لحسابك. |
delivery | channels (email، أو sms، أو فاضية لو هتشارك الرابط بنفسك)، وadditionalRecipients (لحد 5)، وmessage. |
locale، pdfLanguage | locale قيمته auto أو ar أو en للإيميل ورسالة SMS وصفحة الدفع. وpdfLanguage قيمته ar أو en أو bilingual. |
description، footer | الملاحظة والتذييل. وcustomFields بياخد لحد 4 أزواج { name, value }. |
automaticallyFinalizesAt | يعمل finalize للمسودة ويبعتها في الوقت ده (ISO 8601 مع فرق التوقيت). وnull بيلغي الجدولة. |
autoAdvance | هل XPay يبعت تذكيرات ويتعامل مع التأخير للفاتورة دي. |
metadata | مفاتيح وقيم خاصة بيك. |
علشان تغيّر بنود مسودة من غير ما تبعتها كلها تاني، استخدم POST /invoices/:id/add-lines وupdate-lines وremove-lines، لحد 50 بند في الطلب الواحد. وPOST /invoices/preview بيرجّع إجماليات الفاتورة من غير ما يحفظها.
لخطة دفع، نادي PUT /invoices/:id/installments بالخطة كلها: من 2 لـ 24 قسط، كل قسط ليه amount وdueDate. على المسودة مجموعهم يساوي الـ total، لأن الفاتورة اللي عليها خطة مابتستخدمش رصيد العميل. وعلى فاتورة اتعملها finalize مجموعهم يساوي amountDue ناقص الإشعارات الدائنة بتاعتها. والقائمة الفاضية بتشيل الخطة.
2. اعملها finalize
curl -X POST https://api.xpay.app/invoices/in_3Nf8a2kLmPq9/finalize \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: 0d7c2f4a-91b3-4e58-a6c1-3f8e2b9d4c10"الـ finalize بيدّي الفاتورة الرقم اللي عليه الدور في تسلسلك، وبينسخ بيانات العميل وبيانات نشاطك على الفاتورة، وبيطبّق أي رصيد للعميل، وبيعمل رابط الدفع. والـ body الاختياري { "issueDate": "2026-05-01" } بيحدد التاريخ اللي بيظهر على الفاتورة، والافتراضي النهارده.
الفاتورة اللي مايفضلش عليها حاجة تتدفع بعد رصيد العميل بتروح على طول لـ paid.
من هنا الفاتورة مابتتعدّلش. علشان تصحّحها، أصدر إشعار دائن، أو اعمل لها نسخة معدّلة.
3. ابعتها
curl -X POST https://api.xpay.app/invoices/in_3Nf8a2kLmPq9/send \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: 6a3e9d1c-5b72-4f0e-8c4d-1e7a2b3c9f55" \
-H "Content-Type: application/json" \
-d '{ "channels": ["email", "sms"], "message": "Thank you for your order." }'الـ body اختياري. من غيره بتتستخدم إعدادات delivery المتخزنة على الفاتورة، ومعاه الإعدادات بتتحفظ للإرسال الجاي كمان. نداء send على مسودة بيعمل لها finalize الأول. ونداؤه على فاتورة مفتوحة بيبعتها تاني.
الرد بيرجع قبل ما الرسالة توصل. invoice.sent بيتطلق أول مرة الفاتورة توصل فيها للعميل، ومش بيتطلق لما تبعتها تاني. علشان تتابع كل مرة اتبعتت فيها، اقرا GET /invoices/:id/activity. ولو عايز توصّل الفاتورة بنفسك، اتخطّى النداء ده وشارك الـ hostedInvoiceUrl.
في وضع الاختبار، مفيش حاجة بتوصل للعميل. الفاتورة بتكمّل زي ما كانت هتكمّل في الوضع الفعلي، وinvoice.sent بيتطلق برضه.
4. اقرا الرد
كل النداءات اللي فوق بترجّع الفاتورة. ده الكائن بعد الخطوة 2، ومختصر على أهم الحقول:
{
"id": "in_3Nf8a2kLmPq9",
"object": "invoice",
"livemode": false,
"status": "open",
"displayStatus": "open",
"number": "INV-000127",
"collectionMethod": "send_invoice",
"currency": "EGP",
"customerId": "cus_3Nf8a2kLmPq9",
"customerName": "Mona Adel",
"customerEmail": "mona@example.com",
"issueDate": "2026-05-01",
"dueDate": "2026-05-08",
"isOverdue": false,
"subtotal": 300000,
"totalTaxes": [
{
"amount": 42000,
"taxableAmount": 300000,
"taxBehavior": "exclusive",
"taxRateDetails": {
"taxRateId": "txr_3Nf8a2kLmPq9",
"displayName": "VAT",
"displayNameAr": null,
"percentage": 14
}
}
],
"total": 342000,
"amountDue": 342000,
"amountPaid": 0,
"amountRemaining": 342000,
"lines": [
{
"id": "il_3Nf8a2kLmPq9",
"object": "line_item",
"description": "Website design",
"quantity": 2,
"unitLabel": "day",
"pricing": { "unitAmount": 150000, "priceDetails": null },
"amount": 300000,
"amountTotal": 342000
}
],
"installments": [],
"payments": [],
"allowPartialPayments": false,
"delivery": {
"channels": ["email"],
"additionalRecipients": [],
"message": null
},
"statusTransitions": {
"finalizedAt": "2026-05-01T09:12:00.000Z",
"paidAt": null,
"markedUncollectibleAt": null,
"voidedAt": null
},
"sentAt": null,
"hostedInvoiceUrl": "https://checkout.xpay.app/i/ilink_test_...",
"hostedInvoiceUrlExpiresAt": null,
"metadata": { "order_id": "ord_42" }
}الحقول اللي هتستخدمها أكتر:
| الحقل | معناه |
|---|---|
status، displayStatus | الحالة المتخزنة، والحالة اللي تعرضها للناس. |
number | بيتحدد عند الـ finalize. وnull على المسودة. |
total | قيمة الفاتورة. |
amountDue | اللي العميل لازم يدفعه في المجمل، بعد رصيد العميل. الإشعارات الدائنة مابتغيّرهوش. |
amountPaid، amountRemaining | اللي اتستلم لحد دلوقتي، واللي لسه هيتدفع. |
dueDate، isOverdue، daysOverdue | تاريخ الاستحقاق (null معناها مستحقة عند الاستلام)، وهل عدّى وفيه مبلغ متبقي. |
lines، totalTaxes، totalDiscountAmounts | اللي بتحاسب عليه، والضريبة والخصومات محسوبة. |
payments | كل دفعة على الفاتورة، أونلاين أو مسجّلة. |
installments | خطة الدفع. فاضية لو مفيش خطة. |
hostedInvoiceUrl | الصفحة اللي العميل بيشوف منها الفاتورة ويدفعها. |
startingBalance، endingBalance | رصيد العميل قبل ما الفاتورة تستخدمه وبعدها. السالب رصيد للعميل. |
fromInvoice، latestRevisionId | الأول على الفاتورة اللي بتعدّل فاتورة تانية، والتاني على الفاتورة اللي اتبدّلت. |
GET /invoices/:id بيرجّع نفس الكائن. وGET /invoices بيعرض الفواتير بالشكل { "data": [...], "totalCount": 0 }، مع page وlimit (لحد 100)، وفلاتر زي status وcustomerId وoverdue وdueDate وcreated وsearch. وGET /invoices/:id/pdf بيرجّع ملف PDF؛ ضيف ?language=ar أو en أو bilingual علشان تختار لغته.
استمع لأحداث الفواتير
اشترك في الأحداث اللي محتاجها على نقطة الـ webhook بتاعتك. الـ data.object بتاع كل حدث invoice.* هو الـ Invoice كاملة، زي GET /invoices/:id بالظبط.
| الحدث | بيتطلق لما | data.object |
|---|---|---|
invoice.created | مسودة تتعمل، ومنها النسخة المكررة أو النسخة المعدّلة. | Invoice |
invoice.updated | فاتورة تتغير بره أحداثها التانية: مسودة تتعدّل، أو تاريخ الاستحقاق أو خطة الدفع أو الرابط يتغير، أو دفعة مسجّلة تتشال. | Invoice |
invoice.deleted | مسودة تتحذف. | Invoice |
invoice.finalized | مسودة يتعملها finalize وتاخد رقمها. | Invoice |
invoice.finalization_failed | مسودة مجدولة ماقدرتش يتعملها finalize في ميعادها. بتفضل مسودة وجدولتها بتتلغي. | Invoice |
invoice.sent | الفاتورة توصل للعميل أول مرة. | Invoice |
invoice.will_be_due | قبل تاريخ الاستحقاق بـ 3 أيام، طول ما فيه مبلغ متبقي. | Invoice |
invoice.overdue | تاريخ الاستحقاق يعدّي وفيه مبلغ متبقي. وفي خطة الدفع، مرة لكل قسط. | Invoice |
invoice.payment_succeeded | دفعة تتستلم على الفاتورة، أونلاين أو مسجّلة. بيتطلق مع كل دفعة. | Invoice |
invoice.payment_failed | محاولة دفع أونلاين تترفض، أو مرجع دفع ينتهي من غير ما يتدفع. | Invoice |
invoice.paid | مايفضلش حاجة تتدفع، من دفعات أو رصيد العميل أو إشعار دائن. بيتطلق تاني لو شلت دفعة والفاتورة اتفتحت واتدفعت تاني. | Invoice |
invoice.overpaid | دفعة جابت أكتر من المستحق. والزيادة بقت رصيد للعميل. | Invoice |
invoice.marked_uncollectible | الفاتورة تتشطب، منك أو بالشطب التلقائي. | Invoice |
invoice.voided | الفاتورة تتلغي، ومنها لما نسخة معدّلة تحل محلها. | Invoice |
invoice_payment.paid | دفعة واحدة على فاتورة تتستلم. | Invoice Payment |
credit_note.created | إشعار دائن يصدر، ومنه الإشعار اللي بيتكتب لاسترداد مباشر. | Credit Note |
credit_note.updated | ملاحظة الإشعار الدائن أو الـ metadata بتاعته تتغير. | Credit Note |
credit_note.voided | إشعار دائن يتلغي. | Credit Note |
customer.updated | الـ balance بتاع العميل يتغير: رصيد اتدّى أو اتستخدم أو رجع. | Customer |
تنفّذ الطلب على أنهي حدث
نفّذ الطلب على invoice.paid. بيتطلق لما مايفضلش حاجة تتدفع: الفلوس جت أونلاين، أو من دفعة مسجّلة، أو من رصيد العميل. وبيتطلق كمان لما إشعار دائن يقفل اللي كان فاضل، من غير ما توصل فلوس جديدة. لو شلت دفعة مسجّلة، الفاتورة بتتفتح تاني وبيتطلق invoice.paid تاني لما تتدفع. نفّذ كل فاتورة مرة واحدة بس، حسب الـ id بتاعها.
علشان تفرّق بينهم، قارن amountPaid بـ amountDue. لو إشعار دائن قفل الباقي، amountPaid بيبقى أقل من amountDue، وprePaymentCreditNotesAmount فيه الجزء اللي اتعمله إشعار دائن. لو بتنفّذ الطلب بس لما الفلوس توصل، اتأكد من ده قبل ما تنفّذ.
لو بتسلّم على مراحل، زي الدفع الجزئي أو الأقساط، استخدم invoice.payment_succeeded أو invoice_payment.paid. الاتنين بيتطلقوا مع كل دفعة. اقرا amountPaid وamountRemaining على الفاتورة، أو amountPaid وinstallmentId على الـ Invoice Payment.
مع دفعة ناجحة واحدة، الأحداث بتوصل بالترتيب ده: invoice_payment.paid، وبعده invoice.payment_succeeded، وبعده invoice.paid لو مافضلش حاجة، وبعده invoice.overpaid وcustomer.updated لو الدفعة كانت أكتر من المستحق. ماتعتمدش على ترتيب التسليم مع الإعادات؛ اتعامل مع كل حدث من غير تكرار حسب الـ id بتاعه.
علشان طريقة التحقق من التوقيع، شوف الـ Webhooks ← التحقق من التوقيعات.
سجّل دفعة
لما العميل يدفعلك بره XPay، اربط سجل دفعة بالفاتورة:
curl -X POST https://api.xpay.app/invoices/in_3Nf8a2kLmPq9/attach-payment \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: 2c9a7e4b-6d18-4b3f-b5a0-9e1f3d7c8a21" \
-H "Content-Type: application/json" \
-d '{
"paymentRecord": {
"amount": 100000,
"method": "bank_transfer",
"paidAt": "2026-05-03",
"reference": "TRX-88231"
}
}'method قيمته cash أو bank_transfer أو cheque أو other. وpaidAt الافتراضي النهارده، ومينفعش يكون في المستقبل. وreference بيتطبع على الإيصال؛ وnote لفريقك بس.
الرد هو الفاتورة بعد الدفعة. الفاتورة لازم تكون open أو uncollectible. والمبلغ اللي فوق المتبقي بيبقى رصيد للعميل، وinvoice.overpaid بيتطلق.
الدفعات الأونلاين بتتربط لوحدها لما العميل يدفع، فالـ endpoint ده بياخد سجل دفعة بس.
كل دفعة هي Invoice Payment (inpay_*):
{
"id": "inpay_3Nf8a2kLmPq9",
"object": "invoice_payment",
"invoiceId": "in_3Nf8a2kLmPq9",
"status": "paid",
"amountRequested": 100000,
"amountPaid": 100000,
"amountRefunded": 0,
"currency": "EGP",
"payment": {
"type": "payment_record",
"paymentIntentId": null,
"checkoutSessionId": null,
"paymentRecord": { "method": "bank_transfer", "reference": "TRX-88231", "note": null }
},
"statusTransitions": { "paidAt": "2026-05-02T21:00:00.000Z", "canceledAt": null },
"installmentId": null,
"receiptNumber": "2830-5289",
"receiptUrl": "https://checkout.xpay.app/r/rlink_live_..."
}الدفعة الأونلاين الـ payment.type بتاعها payment_intent ومعاها الـ paymentIntentId والـ checkoutSessionId.
GET /invoice-payments?invoiceId=in_...بيعرض دفعات الفاتورة، وGET /invoice-payments/:idبيقرا دفعة واحدة.DELETE /invoice-payments/:idبيشيل دفعة سجّلتها بالغلط. الدفعات الأونلاين بتتسترد بدل كده.receiptUrlهو صفحة الإيصال، ومنها ملف PDF. وPOST /invoice-payments/:id/send-receiptبيبعت الإيصال بالإيميل تاني (في الوضع الحقيقي بس).
الإشعارات الدائنة
الـ Credit Note بيقلّل فاتورة اتعملها finalize من غير ما يغيّرها. الأول بيقلّل اللي لسه مستحق على العميل (prePaymentAmount). وأي حاجة زيادة عن كده كانت اتدفعت بالفعل (postPaymentAmount) ولازم ترجع للعميل.
curl -X POST https://api.xpay.app/credit-notes \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: 4f2b8d6a-3c91-4e7f-a2d5-7b0c1e9f6a34" \
-H "Content-Type: application/json" \
-d '{
"invoiceId": "in_3Nf8a2kLmPq9",
"lines": [
{ "type": "invoice_line_item", "invoiceLineItemId": "il_3Nf8a2kLmPq9", "quantity": 1 }
],
"reason": "order_change",
"memo": "One day cancelled"
}'ده بيخصم يوم واحد، 171000 بالضريبة. والفاتورة اللي فوق لسه عليها 242000، فالإشعار كله بيقلّل المستحق ومفيش حاجة اتدفعت ترجع: فالحقول التلاتة اللي تحت مش بتتبعت.
قول تخصم إيه بـ lines أو بـ amount، مش الاتنين:
linesبيخصم من بنود الفاتورة (invoice_line_item، بـquantityأو بـamountقبل الضريبة) أو بيضيف بنود خاصة بيه (custom_line_item، بـdescriptionوunitAmount). وضريبة بند الفاتورة بتتخصم بنفس النسبة.amountبيخصم إجمالي واحد من غير ضريبة، كبند واحد.
وبعدين قول الجزء اللي اتدفع بالفعل هيرجع إزاي. التلاتة دول لازم مجموعهم يساوي postPaymentAmount:
| الحقل | بيعمل إيه |
|---|---|
refundAmount | بيسترد الدفعات الأونلاين على الفاتورة، الأحدث الأول. محتاج صلاحية كتابة المبالغ المستردة على المفتاح بتاعك. |
creditAmount | العميل بيحتفظ بيه كرصيد، بيتستخدم في فاتورته الجاية. |
outOfBandAmount | إنت رجّعته بره XPay. |
نادي POST /credit-notes/preview بنفس الـ body الأول علشان تقرا prePaymentAmount وpostPaymentAmount قبل ما تقرر التقسيم. مفيش حاجة بتتحفظ.
قواعد مهم تعرفها:
- الفاتورة لازم تكون
openأوpaidأوuncollectible، ومفيش عليها دفعة أونلاين شغالة. - كل الإشعارات الدائنة على الفاتورة مع بعض مينفعش تبقى أكبر من الـ
totalبتاعها (credit_note_amount_too_large). - الجزء اللي العميل دفعه من رصيده مينفعش يرجع غير كـ
creditAmount. refundAmountبيشتغل على الفواتير بالجنيه المصري. في فاتورة بعملة تانية، استرد الدفعة بـPOST /refunds.POST /credit-notes/:id/voidبيشتغل بس طول ما الفاتورةopenوالإشعار الدائن مارجّعش حاجة.PATCH /credit-notes/:idبيغيّر الـmemoوالـmetadataبس.
استرداد دفعة فاتورة مباشرة
تقدر برضه تسترد دفعة أونلاين على فاتورة بـ POST /refunds والـ paymentIntentId بتاعها.
- لو الفاتورة
paid، الاسترداد الأول بيرجّع أي مبلغ العميل دفعه زيادة عن الفاتورة. وXPay بيكتب إشعار دائن للباقي ويبعتcredit_note.created. والفاتورة بتفضلpaid. - لو الفاتورة لسه
open، الدفعة بتترجع:amountPaidبينزل وamountRemainingبيطلع بنفس المبلغ اللي اتسترد، ومفيش إشعار دائن بيتكتب.
في الحالتين، الـ Invoice Payment بيفضل status: "paid" وبيوري الفلوس اللي رجعت في amountRefunded.
رصيد العميل
الـ balance بتاع العميل هو رصيده عندك. والرصيد السالب معناه إن ليه رصيد. وبيتستخدم لوحده لما فاتورته الجاية يتعملها finalize.
GET /customers/:id/balance-transactionsبيعرض كل تغيير في الرصيد.POST /customers/:id/balance-transactionsبيعدّله بإيدك:{ "amount": -5000, "description": "Goodwill credit" }. الـamountالسالب بيدّي رصيد؛ والموجب بياخده تاني.
كل تغيير بيبعت customer.updated.
أسعار الضريبة
الـ Tax Rate هو ضريبة بتستخدمها تاني وتالت على البنود، زي ضريبة القيمة المضافة 14%.
curl -X POST https://api.xpay.app/tax-rates \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"displayName": "VAT",
"displayNameAr": "ضريبة القيمة المضافة",
"percentage": 14,
"inclusive": false
}'{
"id": "txr_3Nf8a2kLmPq9",
"object": "tax_rate",
"displayName": "VAT",
"displayNameAr": "ضريبة القيمة المضافة",
"percentage": 14,
"inclusive": false,
"active": true
}inclusive: falseبيضيف الضريبة فوق السعر. وinclusive: trueمعناها إن السعر فيه الضريبة أصلًا.percentageأكبر من 0 ولحد 100، بلحد 4 أرقام عشرية.percentageوinclusiveمابيتغيّروش بعد الإنشاء، علشان الفواتير اللي اتعملها finalize ماتتغيرش أبدًا. وPATCH /tax-rates/:idبيغيّر الأسماء والـdescriptionوالـactive.- خلّي
active: falseعلشان تأرشف سعر. بيفضل على الفواتير الموجودة، وإضافته لفاتورة جديدة بترجّعtax_rate_archived.
GET /tax-rates بيعرض أسعارك وبيقبل فلاتر active وinclusive.
تعديل الفاتورة أو إلغاؤها
| علشان | نادي |
|---|---|
| تصحّح فاتورة اتعملها finalize | POST /invoices بـ { "fromInvoice": { "action": "revision", "invoiceId": "in_..." } }. الفاتورة لازم تكون open أو uncollectible. بتاخد نسخة مسودة. والـ finalize بتاعها بيلغي الأصلية. |
| تغيّر تاريخ الاستحقاق | POST /invoices/:id/due-date بـ { "dueDate": "2026-06-01" }، أو null لمستحقة عند الاستلام. |
| تفكّر العميل | POST /invoices/:id/send-reminder. |
| تلغيها | POST /invoices/:id/void. بس طول ما مفيش دفعة اتستلمت. |
| تشطبها | POST /invoices/:id/mark-uncollectible. |
| تبدّل رابط الدفع | POST /invoices/:id/rotate-link. الرابط القديم بيبطّل يشتغل على طول. |
| تنسخها | POST /invoices/:id/duplicate. |
| تحذف مسودة | DELETE /invoices/:id. |
الفاتورة اللي عليها دفعة مينفعش تتلغي ولا يتعملها نسخة معدّلة (invoice_has_payments). أصدر إشعار دائن بدل كده.
عدم التكرار
ابعت Idempotency-Key مع كل عملية كتابة على الفواتير ممكن تعيدها: إنشاء الفاتورة وتحديثها، وتغيير بنودها، وfinalize، وsend، وsend-reminder، وvoid، وmark-uncollectible، وdue-date، وduplicate، وrotate-link، وattach-payment، وPOST /credit-notes، وPOST /credit-notes/:id/void، وPOST /customers/:id/balance-transactions.
أهم حاجة على finalize وattach-payment وPOST /credit-notes. الإعادة العمياء بعد مهلة منتهية ممكن تستخدم رقم فاتورة تاني، أو تسجّل نفس الدفعة مرتين، أو ترجّع الفلوس للعميل مرتين. ومع المفتاح، الإعادة بترجّع النتيجة الأصلية. شوف عدم التكرار.
قائمة الإنتاج
- نفّذ الطلب من الـ webhook، مش من الرجوع للصفحة.
invoice.paidهو المرجع. العميل ممكن يقفل الصفحة قبل ما تتحمّل تاني. - اتعامل مع الأحداث من غير تكرار. خزّن الـ
idبتاع الحدث واتخطّى أي حدث اتعاملت معاه قبل كده. - حدّد صلاحيات مفتاح الـ API. المفتاح محتاج صلاحية Invoices، وTax rates لو بيدير أسعار الضريبة، وكتابة Refunds بس لو بيبعت
refundAmount. - راجع العميل الأول. الـ finalize بيفشل بـ
invoice_customer_incompleteلما العميل مالوش اسم، أو مالوش لا إيميل ولا رقم موبايل. - توقّع حدود على الإرسال. رسايل SMS ليها حد لكل فاتورة، ولكل رقم موبايل، ولكل شهر، والإيميلات اليدوية ليها حد في اليوم. والرسالة اللي اتخطّت بتظهر في نشاط الفاتورة في لوحة التحكم.
- اقرا كود الخطأ. أخطاء الفواتير معاها أكواد زي
invoice_not_editableوinvoice_payment_in_progress. شوف أكواد أخطاء الـ API.
رايح فين بعد كده
الفواتير في لوحة التحكم
المسار اللي فريقك بيستخدمه من غير كتابة كود.
إعداد نقطة نهاية webhook
استقبل invoice.paid وتحقق من توقيعه.
عدم التكرار
أعد عمليات الكتابة على الفواتير بأمان.
أكواد أخطاء الـ API
كل أكواد أخطاء الفواتير والإشعارات الدائنة وأسعار الضريبة.
نموذج الكائنات
إزاي Payment Intents وCharges وRefunds بيقفوا ورا دفعة الفاتورة.