# الفواتير (/ar/integrate/invoices)

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

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

الصفحة دي بتغطّي مسار المطوّر. علشان المسار اللي فريقك بيستخدمه يوم بيوم من لوحة التحكم، شوف [الفواتير](/features/invoices/overview) تحت المميزات.

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

## إزاي بيشتغل [#إزاي-بيشتغل]

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. اعمل مسودة [#1-اعمل-مسودة]

`POST /invoices` محتاج `customerId`. وكل حاجة تانية اختيارية، وتقدر تضيفها بعدين بـ `PATCH /invoices/:id` طول ما الفاتورة مسودة.

<Tabs items="[&#x22;cURL&#x22;, &#x22;Node.js&#x22;, &#x22;Python&#x22;]">
  <Tab value="cURL">
    ```bash
    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" }
      }'
    ```
  </Tab>

  <Tab value="Node.js">
    ```typescript
    const res = await fetch("https://api.xpay.app/invoices", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.XPAY_SECRET_KEY}`,
        "Idempotency-Key": crypto.randomUUID(),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        customerId: "cus_3Nf8a2kLmPq9",
        daysUntilDue: 7,
        defaultTaxRateIds: ["txr_3Nf8a2kLmPq9"],
        lines: [
          // 2 days at 1,500.00 EGP, in minor units
          { description: "Website design", quantity: 2, unitAmount: 150000, unitLabel: "day" },
        ],
        delivery: { channels: ["email"] },
        metadata: { order_id: "ord_42" },
      }),
    });

    const invoice = await res.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import os, uuid, requests

    res = requests.post(
        "https://api.xpay.app/invoices",
        headers={
            "Authorization": f"Bearer {os.environ['XPAY_SECRET_KEY']}",
            "Idempotency-Key": str(uuid.uuid4()),
            "Content-Type": "application/json",
        },
        json={
            "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"},
        },
        timeout=10,
    )

    invoice = res.json()
    ```
  </Tab>
</Tabs>

أهم حقول الطلب:

| الحقل                       | ملاحظات                                                                                                                                                            |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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 [#2-اعملها-finalize]

```bash
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. ابعتها [#3-ابعتها]

```bash
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. اقرا الرد [#4-اقرا-الرد]

كل النداءات اللي فوق بترجّع الفاتورة. ده الكائن بعد الخطوة 2، ومختصر على أهم الحقول:

```json
{
  "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 ← التحقق من التوقيعات](/integrate/webhooks/verifying-signatures).

## سجّل دفعة [#سجّل-دفعة]

لما العميل يدفعلك بره XPay، اربط سجل دفعة بالفاتورة:

```bash
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_*`):

```json
{
  "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`) ولازم ترجع للعميل.

```bash
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`](/integrate/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%.

```bash
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
  }'
```

```json
{
  "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`. الإعادة العمياء بعد مهلة منتهية ممكن تستخدم رقم فاتورة تاني، أو تسجّل نفس الدفعة مرتين، أو ترجّع الفلوس للعميل مرتين. ومع المفتاح، الإعادة بترجّع النتيجة الأصلية. شوف [عدم التكرار](/integrate/idempotency).

## قائمة الإنتاج [#قائمة-الإنتاج]

* **نفّذ الطلب من الـ webhook، مش من الرجوع للصفحة.** `invoice.paid` هو المرجع. العميل ممكن يقفل الصفحة قبل ما تتحمّل تاني.
* **اتعامل مع الأحداث من غير تكرار.** خزّن الـ `id` بتاع الحدث واتخطّى أي حدث اتعاملت معاه قبل كده.
* **حدّد صلاحيات مفتاح الـ API.** المفتاح محتاج صلاحية **Invoices**، و**Tax rates** لو بيدير أسعار الضريبة، وكتابة **Refunds** بس لو بيبعت `refundAmount`.
* **راجع العميل الأول.** الـ finalize بيفشل بـ `invoice_customer_incomplete` لما العميل مالوش اسم، أو مالوش لا إيميل ولا رقم موبايل.
* **توقّع حدود على الإرسال.** رسايل SMS ليها حد لكل فاتورة، ولكل رقم موبايل، ولكل شهر، والإيميلات اليدوية ليها حد في اليوم. والرسالة اللي اتخطّت بتظهر في نشاط الفاتورة في لوحة التحكم.
* **اقرا كود الخطأ.** أخطاء الفواتير معاها أكواد زي `invoice_not_editable` و`invoice_payment_in_progress`. شوف [أكواد أخطاء الـ API](/integrate/errors/api-error-codes#الفواتير).

## رايح فين بعد كده [#رايح-فين-بعد-كده]

<Cards>
  <Card icon="<FileText />" title="الفواتير في لوحة التحكم" href="/features/invoices/overview">
    المسار اللي فريقك بيستخدمه من غير كتابة كود.
  </Card>

  <Card icon="<Webhook />" title="إعداد نقطة نهاية webhook" href="/integrate/webhooks/setting-up-an-endpoint">
    استقبل `invoice.paid` وتحقق من توقيعه.
  </Card>

  <Card icon="<ShieldCheck />" title="عدم التكرار" href="/integrate/idempotency">
    أعد عمليات الكتابة على الفواتير بأمان.
  </Card>

  <Card icon="<TriangleAlert />" title="أكواد أخطاء الـ API" href="/integrate/errors/api-error-codes">
    كل أكواد أخطاء الفواتير والإشعارات الدائنة وأسعار الضريبة.
  </Card>

  <Card icon="<Network />" title="نموذج الكائنات" href="/integrate/object-model">
    إزاي Payment Intents وCharges وRefunds بيقفوا ورا دفعة الفاتورة.
  </Card>
</Cards>