التوثيق
الدمج

الفواتير

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

الـ Invoice هي مطالبة لعميل واحد، ليها صفحة مستضافة بيدفع منها. السيرفر بتاعك بيعمل مسودة، ويعمل لها finalize، ويبعتها. وXPay بيستضيف صفحة الدفع، ويبعت التذكيرات، ويبعتلك webhook لما الفلوس توصل.

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

الـ API بتاع الفواتير ماشي على شكل API الفواتير بتاع Stripe: نفس الكائنات والحالات والإجراءات وأسماء الأحداث. أسماء الحقول camelCase، والمبالغ أرقام صحيحة بأصغر وحدة (150000 يعني 1,500.00 جنيه). لو اشتغلت قبل كده على فواتير Stripe، فالنموذج ده إنت عارفه.

إزاي بيشتغل

  1. السيرفر بتاعك بيعمل مسودة بـ POST /invoices: عميل وبنود.
  2. السيرفر بتاعك بيعمل لها finalize بـ POST /invoices/:id/finalize. الفاتورة بتاخد رقمها والـ hostedInvoiceUrl بتاعها، ومبالغها بتثبت.
  3. السيرفر بتاعك بيبعتها بـ POST /invoices/:id/send، أو بيشارك الـ hostedInvoiceUrl بنفسه.
  4. العميل بيدفع من الصفحة المستضافة، كامل أو على أجزاء أو بالأقساط.
  5. 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 معناها الإعداد الافتراضي لحسابك.
deliverychannels (email، أو sms، أو فاضية لو هتشارك الرابط بنفسك)، وadditionalRecipients (لحد 5)، وmessage.
locale، pdfLanguagelocale قيمته 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.

تعديل الفاتورة أو إلغاؤها

علشاننادي
تصحّح فاتورة اتعملها finalizePOST /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.

رايح فين بعد كده

في الصفحة دي