العربية

Dynamics — field map and template selection

Prepare accepts the usual Dynamics names (payee_name · net_amount · issue_date · document_no · memo) through ordered fallback chains and picks the template by a decision tree. The full map, what the server stamps, and what is not in the contract.

Last updated: 2026-09-21

On this page

The chain rule

Each field has a list of accepted names: the first non-empty value (after trim) wins, and an empty one falls through to the next.

Cheque field	Accepted names, in precedence	Note
recipient_name ✅	`recipient_name` → `payee_name` → `beneficiary_name` → `vendor_name` → `customer_name`	required
amount ✅	`amount` → `net_amount`	required
cheque_date	`cheque_date` → `issue_date` → `due_date`	normalised to `Y-m-d`
reason	`reason` → `memo` → `description`
reference_number	`reference_number` → `external_reference` → `document_no` → `voucher_no`
note	`note` and `notes` together	merged with a newline, de-duplicated
currency	`currency` → `currency_code` → `EGP`	upper-cased
cheque_type	`cheque_type` only	default `OUT`
external identifier	`external_id` → `external_reference` → `document_no` → `voucher_no`	the matching key — send `external_id`
`bank_name` · `template_name`	⛔ not taken from input	stamped from the resolved bank and template
`external_source`	⛔ from `DYNAMICS_SOURCE`

Stub fields stub_date · stub_name · stub_amount · stub_reason — no aliases, and they fall back to their main counterpart on a threefold condition: not sent and a template resolved and that template has a stub (with_stub = 1). In the “template selection required” case there is no fallback.

bank_code · bank_account_code · bank_account_number are not in the contract (removed in 1.8.0) — never read.

Template selection — decision tree

Base in every branch: the template is active and its bank is active. “Featured” (most used) only breaks ties: chosen if exactly one is featured, else the only member if the set has one, else no decision.

#	Sent	Result
1	`template_id`	wins outright; missing/disabled ⟹ 422
2	`bank_id`	resolved; missing/disabled ⟹ 422 on `bank_id`
2b	`bank_name`	fuzzy match (case, spaces, alef/yaa/hamza folding): single exact ← single partial; failure with `template_name` present continues without a bank
3	`template_name`	exact ← partial; ambiguity ⟹ 422 (several featured / ambiguous name)
4	bank only	single featured ⟹ chosen · no templates ⟹ 422 · otherwise ⟹ 200 with `template_selection_required`
5	nothing valid	422 on `template` explaining the three options

Recommendation: send template_id — precise, fast, independent of Arabic names.

What `data` returns — 30 keys in order

شفرة

bank_name · template_name · cheque_type · cheque_date · stub_date · place · recipient_name ·
stub_name · amount · stub_amount · amount_text · reason · reference_number · note · stub_reason ·
signed_by · currency · cheque_number · liner_enabled · liner_text · two_lines · company_id ·
bank_account_id · cheque_book_id · cheque_leaf_id · partner_id · resolved_bank_id ·
resolved_template_id · template_selection_required · available_templates

(+ external_source · external_id · request_hash.)

Stamped by the server at creation

Always stamped	Caller may set
`bank_name` · `template_name` (resolved)	`printed_status` (default true)
`external_source` · `external_id` · `request_hash` (from the draft)	`cheque_type`
`printed_at` · `printed_by` (the employee) · `company_id` (the key’s company, from the draft)	—
initial status (from the direction) · `paper_status` · image path	every other field in the completion body — overrides the draft

Common 422 messages

bank_id: bank missing or disabled.
template: “specify the template by template_id, bank_id or template_name”.
template_name: ambiguous name / more than one featured template.
Amount and fraction: as in Create a cheque directly.