Create a cheque directly — POST /api/cheque-log/external

When to use it

When your system prints the cheque itself (or does not print at all) and you want a row in the cheque log with its initial status for follow-up in the app. No preview, no printing — to print from the app’s screen use the Dynamics flow.

Route: POST /api/cheque-log/external — alias POST /api/cheque-logs (audited under the first name).

Fields

Contract notes:

• cheque_status_id is silently ignored — the status derives from cheque_type: OUT ⟹ being issued · IN ⟹ in wallet · unknown ⟹ no status (which you don’t want — always send the direction).
• bank_id is accepted but not read here — the bank resolves from bank_name alone by a case-insensitive match after trimming; send the name as /api/banks returns it.
• The image is not stored unless save_cheque_image: true with image_base64/image — and without a watermark.
• cheque_leaf_id: an available leaf of an issued-cheque book in the key's company; the cheque number, book and account come from it, and it is marked used with the row.

Guards that raise 422

Example

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:

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

data is the full row (100+ columns, including lifecycle columns that are empty now) — rely on id, cheque_number, bank_name, amount, cheque_date, currency, and do not build on the rest.

Errors

Stamped server-side

printed_at = now() · printed_by = null · initial status from the direction · and company_id = the key’s company, always. The payload is checked against it: a different company_id, or a reference (account · book · leaf · partner) from another company ⟹ 422. No fallback and no default company on the key path.

With cheque_leaf_id: the leaf is locked and checked inside the same save transaction, and the cheque number, book and account come from it (send cheque_number equal to its number, or omit it); it becomes used with the row. On the key path the leaf is not restricted to the book's next leaf — the call records a cheque that was already printed. A resend with the same external_source + external_id returns the existing row (200 reused) and leaves the leaf as it is.

The row is confirmed — and idempotency

The row is created printed and confirmed (the paper left outside the app): its number cannot be edited afterwards, like any confirmed cheque, and it enters confirmed reports and reminders — so send the number right the first time.

Three duplicate guards (since 1.8.0):

1. Cheque number in its context: a second call with the same number and bank in the same company and direction (and the same account for issued cheques when sent · the same customer for received ones when partner_id is sent) ⟹ 422 “already used” — treat it as a prior success in your logic.
2. External key (optional): send external_source + external_id (as in Dynamics) — a resend returns the existing row with 200 and "reused": true, no new row (Dynamics uses action: "reused" instead).
3. A row stamped for another company, or a final row (damaged · cancelled · reissued) ⟹ 422 instead of an update.

Recommendation: send both cheque_number and external_id.

Related

• Banks & templates
• Error reference