English

إنشاء شيك مباشرة — POST /api/cheque-log/external

نقطة واحدة تُنشئ صف شيك مطبوع من نظامك بلا شاشة ولا معاينة — للأنظمة التي تطبع بنفسها وتريد السجل في برنامج الشيكات. حقولها وقواعدها الحرفية، الحرّاس التي ترمي 422، شكل الردّ 201، وما يجب أن تعرفه عن التكرار والصورة.

آخر تحديث: 2026-10-24

في الصفحة دي

متى تستعملها؟

حين يطبع نظامك الشيك بنفسه (أو لا يطبعه أصلًا) وتريد صفًّا في حركات الشيكات بحالته الابتدائية لمتابعته من البرنامج. لا معاينة ولا طباعة هنا — للطباعة من شاشة البرنامج استعمل تدفّق Dynamics.

المسار: POST /api/cheque-log/external — واسمه البديل POST /api/cheque-logs (يُسجَّل في التدقيق بالاسم الأول).

الحقول

الحقل	القاعدة الحرفية	إلزامي	الافتراضي
`bank_name`	`required\|string\|max:255`	✅	—
`template_name`	`nullable\|string\|max:255`		null
`cheque_type`	`IN` أو `OUT`		null ⟹ بلا حالة
`cheque_date`	`nullable\|date` + السنة بين 2000 و2100		null
`stub_date`	`nullable\|date`		null
`recipient_name` · `place` · `signed_by` · `reason` · `reference_number` · `stub_name` · `stub_reason`	`nullable\|string\|max:255`		null
`amount_text` · `note` · `liner_text`	`nullable\|string`		null
`amount`	`nullable\|numeric` — ≤ 13 خانة صحيحة، والكسر بخانات العملة		null
`stub_amount`	`nullable\|numeric` — ≤ 8 خانات، والكسر بخانات العملة		null
`currency`	`nullable\|string\|max:10`		`EGP`
`cheque_number`	`nullable\|string\|max:50` + فريد على البنك بين المطبوع		null
`company_id`	`nullable\|integer\|exists:companies,id`		شركة المفتاح — إن أُرسل وخالفها ⟹ 422
`bank_account_id` · `cheque_book_id` · `partner_id`	`nullable\|integer\|exists`		null
`cheque_leaf_id`	`nullable\|integer\|exists` + حارس الورقة (أدناه)		—
`liner_enabled` · `two_lines`	`boolean`		false
`image`	`nullable\|image\|max:200048` (KB)		—
`image_base64`	`nullable\|string`		—
`save_cheque_image`	`nullable\|boolean`		false
`external_source` · `external_id`	`nullable\|string`		null — مفتاح التكرار الاختياري

ملاحظات على العقد:

cheque_status_id يُهمل بصمت — الحالة تُشتق من cheque_type: OUT ⟹ قيد الإصدار · IN ⟹ بالمحفظة · مجهول ⟹ بلا حالة (وهو ما لا تريده — أرسل الاتجاه دائمًا).
bank_id يُقبل ولا يُقرأ هنا — البنك يُحلّ من bank_name وحده بمطابقة لا تفرّق حالة الأحرف بعد إزالة المسافات الطرفية؛ اكتب الاسم كما يعيده /api/banks.
الصورة لا تُحفظ إلا بـsave_cheque_image: true مع image_base64/image — وبلا علامة مائية.
cheque_leaf_id: ورقة متاحة من دفتر صادر في شركة المفتاح؛ رقم الشيك والدفتر والحساب منها، وتُسجَّل مستخدمة مع الصف.

حرّاس ترمي 422

الحالة	الرسالة
الرقم يخصّ ورقة دفتر ولم يُرسَل `cheque_leaf_id` (للصادر وحده: ورقة في دفتر الحساب المرسَل، أو في دفاتر البنك في الشركة حين لا يُرسَل حساب)	`هذا الرقم يخص دفتر شيكات — اطبعه من وضع الدفتر`
`cheque_leaf_id` لورقة محذوفة أو غير موجودة	`الورقة المختارة غير موجودة.`
`cheque_leaf_id` على شيك وارد (`IN`)	`أوراق الدفاتر للشيكات الصادرة وحدها.`
الورقة لا تتبع `cheque_book_id` أو `bank_account_id` أو `bank_name` المرسَلة	`الورقة المختارة لا تتبع الدفتر/الحساب/البنك المرسَل.`
الورقة ليست متاحة (محجوزة · مستخدمة · تالفة)	`الورقة المختارة غير متاحة — حالتها: {الحالة}.`
`cheque_number` مرسَل ويخالف رقم الورقة	`رقم الشيك لا يطابق رقم الورقة المختارة ({n}).`
دفتر الورقة غير نشط	`الدفتر غير نشط.`
رقم الورقة مطبوع على شيك آخر لنفس البنك	`رقم الشيك {n} موجود بالفعل (مطبوع) على نفس البنك.`
الرقم محجوز في دفعة مفتوحة	`الرقم :number محجوز في دفعة مفتوحة (الدفعة #:batch) — اطبعها أو ألغِها أولًا.`
الرقم مكرَّر في سياقه — نفس الشركة والاتجاه والبنك (وحساب الصادر · عميل المستلم حين يُرسَلان)	`رقم الشيك {N} مستعمَل بالفعل على بنك {البنك} — اختر رقمًا آخر`
المبلغ كبير	`القيمة كبيرة جدًا — لا يزيد الجزء الصحيح عن 13 خانة.`
كسر المبلغ	`كسر المبلغ يتجاوز خانات {العملة} (خانتان عشريتان).`
سنة تاريخ الشيك قبل 2000 أو بعد 2100	`تاريخ الشيك يجب أن يقع بين سنة 2000 وسنة 2100.`
مرجع من شركة أخرى	`المستفيد لا يتبع شركة الشيك.` · `الحساب البنكي المختار لا يتبع شركة الشيك.` · `دفتر الشيكات المختار …` · `الورقة المختارة لا تتبع شركة الشيك.`
المفتاح بلا شركة	`مفتاح الـAPI غير منسوب لشركة — عيّن شركته من شاشة «التكامل ← مفاتيح API».`
`company_id` يخالف المفتاح	`الحمولة تطلب شركة «…» بينما مفتاح الـAPI منسوب لشركة «…» — احذف الحقل أو استعمل مفتاح الشركة الصحيحة.`

المثال

bash

curl -s -X POST "APP_URL/api/cheque-log/external" \
  -H "X-API-KEY: KEY" -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
        "bank_name": "بنك مصر",
        "template_name": "بنك مصر - نموذج 1",
        "cheque_type": "OUT",
        "recipient_name": "شركة النيل للتوريدات",
        "amount": 1250.50,
        "currency": "EGP",
        "cheque_date": "2026-10-15",
        "cheque_number": "100200",
        "reference_number": "PV-1001",
        "reason": "دفعة مورّد",
        "signed_by": "خالد عبد الرحمن"
      }'

201:

json

{
  "success": true,
  "message": "تم الحفظ بنجاح",
  "data": { "id": 4321, "bank_name": "بنك مصر", "cheque_number": "100200", "amount": "1250.500", "…": "صف cheque_logs كاملًا" },
  "image_saved": false
}

data هو الصف الكامل (أكثر من مئة عمود، ومنها أعمدة دورة الحياة الفارغة الآن) — اعتمد على id وcheque_number وbank_name وamount وcheque_date وcurrency، ولا تبنِ على الباقي.

الأخطاء

الكود	الجسم
422	`{"message":"Validation failed","errors":{"cheque_number":["…"]}}` — الحقل `cheque_number` أو `cheque_leaf_id` أو `cheque_book_id` بحسب الحارس، والرسائل بالعربية
500	`{"message":"Error saving cheque log","error":"…"}`
503 · 401 · 403 · 429	من سلّم المفتاح

ما يُختم سيرفريًا

printed_at = now() · printed_by = null · الحالة الابتدائية من الاتجاه · و**company_id = شركة المفتاح دائمًا**. الحمولة تُفحص ضدها: company_id مخالف أو مرجع (حساب · دفتر · ورقة · شريك) من شركة أخرى ⟹ 422. لا سلّم ولا شركة افتراضية على مسار المفتاح.

مع cheque_leaf_id: الورقة تُقفَل وتُفحص داخل ترانزاكشن الحفظ نفسها، ورقم الشيك والدفتر والحساب منها (أرسل cheque_number = رقمها أو لا ترسله)، وتصير مستخدمة مع الصف. والورقة غير مقيّدة بالتالية في الدفتر على مسار المفتاح — النداء يسجّل شيكًا طُبع فعلًا. وإعادة الإرسال بنفس external_source + external_id تعيد الصف القائم (200 reused) والورقة كما هي.

الصف مؤكَّد — والتكرار (idempotency)

الصف يُنشأ مطبوعًا مؤكَّدًا (الورق خرج خارج البرنامج): رقمه لا يُعدَّل بعد الإنشاء كأي مؤكَّد، ويدخل تقارير المؤكَّد والتذكيرات — فأرسل الرقم صحيحًا من أول مرة.

ثلاث حمايات من التكرار (منذ 1.8.0):

رقم الشيك في سياقه: النداء الثاني بنفس الرقم والبنك في الشركة نفسها وبالاتجاه نفسه (والحساب نفسه للصادر حين يُرسَل · والعميل نفسه للمستلم حين يُرسَل partner_id) ⟹ 422 «مستعمَل بالفعل» — عامله كنجاح سابق في منطقك.
المفتاح الخارجي (اختياري): أرسل external_source + external_id (كما في Dynamics) — إعادة الإرسال تعيد الصف القائم بـ200 و"reused": true بلا صف جديد (في Dynamics الصيغة action: "reused").
صف مختوم لشركة أخرى أو نهائي (تالف · ملغى · مُعاد إصداره) ⟹ 422 بدل التحديث.

التوصية: أرسل cheque_number وexternal_id معًا.