الإشعارات الدائنة (المرتجعات)

الفاتورة المُسجَّلة في النظام الضريبي لا تُحذف ولا تُعدَّل. التصحيح أو الإرجاع يتمّ بإصدار إشعار دائن (نوع المستند 381) يشير إلى الفاتورة الأصلية.

هذه الجملة تصف شاشة الإرجاع داخل المنصة: زر الإرجاع المرتبط بفاتورة قائمة، وفيه تحدّد «الكمية المراد إرجاعها» لكل بند. وهي لا تعني أن المرتجعات ممنوعة برمجياً — المرتجع عبر الـAPI مستند مستقل من نوع 381 ترسله بالنقطة أعلاه، وهو الطريق الوحيد المتاح لك بعد ربط الأجهزة، لأن الإصدار اليدوي من المنصة يتوقّف عندها.

الحقول الإضافية

بقيّة الحقول مطابقة تمامًا لـ إنشاء فاتورة: ضع في lines البنود المُرتجعة فقط بقيمها الموجبة.

مثال — إرجاع بند واحد

curl -X POST https://fawtara.codexal.co/api/v1/credit-notes \
  -H "Authorization: Bearer fwt_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ret-S-2026-0042-1" \
  -d '{
    "invoice_number": "CN-2026-0007",
    "original_invoice_id": "inv_5c8d1e9a2b7f3046",
    "return_reason": "إرجاع قطعة واحدة لعيب مصنعي",
    "issue_date": "2026-10-23",
    "payment_method": "receivable",
    "customer": {
      "name": "مؤسسة الفجر التجارية",
      "identity_type": "tax",
      "identity_number": "98765432"
    },
    "lines": [
      {
        "name": "لابتوب Dell Latitude 5440",
        "quantity": 1,
        "unit_price": 450.000,
        "tax_percent": 16
      }
    ]
  }'

ما يُبنى في UBL

<cbc:InvoiceTypeCode name="022">381</cbc:InvoiceTypeCode>
<cac:BillingReference>
  <cac:InvoiceDocumentReference>
    <cbc:ID>S-2026-0042</cbc:ID>
    <cbc:UUID>9c2e4f1b-7a3d-4856-b0c9-1d2e3f4a5b6c</cbc:UUID>
    <cbc:DocumentDescription>1044.000</cbc:DocumentDescription>
  </cac:InvoiceDocumentReference>
</cac:BillingReference>
<cac:PaymentMeans>
  <cbc:PaymentMeansCode listID="UN/ECE 4461">10</cbc:PaymentMeansCode>
  <cbc:InstructionNote>إرجاع قطعة واحدة لعيب مصنعي</cbc:InstructionNote>
</cac:PaymentMeans>

قواعد عملية

• invoice_number للإشعار يجب أن يكون رقمًا جديدًا ومختلفًا عن رقم الفاتورة الأصلية.
• لا تتجاوز قيمة الإشعار قيمة الفاتورة الأصلية — البوابة ترفض ذلك.
• يمكن إصدار أكثر من إشعار دائن جزئي للفاتورة نفسها، على ألّا يتجاوز مجموعها الأصل.
• الإشعار يُحسب كمستند واحد من حصّة خطتك الشهرية.
• الخطة المجانية لا تتضمّن الإشعارات الدائنة؛ متاحة في خطّتي النمو والاحتراف.

الأخطاء الخاصة