Goods returns
Create a mapped return line
/a/GoodsReturnedEntry_createData
Insert one return-line record without deducting stock or updating its header.
When to use this endpoint
Use alongside a separately created header when using the mapped API. This is not the legacy creation endpoint’s rows parser and does not perform a catalog stock deduction.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Session CSRF and account/IP restrictions still apply. These handlers add no goods-return, finance, department, owner or page-role permission check.
Records belong to the authenticated tenant. CRM1 shows this workflow when the employer features bit 262144 is enabled; CRM2 uses features2.goodsReturnedNotes. These are UI gates, not checks performed by these handlers.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
grtID | Integer | No | Positive whole parent return-note ID when supplied; parent existence is checked. Optional for metadata-only line creation. |
grnID | Integer | No | Whole positive goods-received note ID or legacy -1. Required on header creation; optional on updates/line creation. No received-note existence or supplier ownership check. |
stock | Native object | No | Native {id,type,text} expands to scalar stockID/type/text; present members, including zero/empty, override scalar aliases. Not a stock movement. |
stockID / stockType | Integer | No | stockID must be a non-negative whole integer; stockType must be 1 (catalog) or 2 (free text). No catalog availability validation by mapped writes. |
stockText | String | No | Free-text description, persisted separately from catalog stock. |
qty | Integer | No | Whole non-negative 32-bit integer; negatives and fractions are rejected. Mapped edits do not reconcile stock or impose a received-quantity maximum. |
grne_id | Integer | No | Whole integer goods-received entry link with this exact name. No received-entry relationship validation. |
cDate | Date/time string | No | Exact YYYY-MM-DD HH:MM:SS without timezone conversion. Defaults to server now on creation. Blank/null becomes SQL NULL; writable despite UI readonly metadata. |
lastEdited | Date/time string | No | Server-owned edit time; supplied values are ignored. Creation and changed updates set last_edited to server date/time. |
noRecord | Native array | No | Native field-alias list whose history is marked hidden on create/update; does not skip persistence/history or grant authorization. |
Example request
FM_api('GoodsReturnedEntry_createData', ['grtID'=>642, 'grnID'=>531, 'stock'=>['id'=>1042,'type'=>1,'text'=>''], 'qty'=>2, 'grne_id'=>733]);Example response
{"ok":1,"id":"744"}id is a checked database insert ID, normally a numeric string; failed inserts return an error, not ok with an invalid ID.
Errors and unusual responses
| Response | Condition |
|---|---|
{"error":"not logged in"} | No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs. |
{"error":"goods return write failed"} | A primary write or history insert failed; the transaction is rolled back. |
{"error":"goods return read failed"} | A required locking read failed; no changes commit. |
{"error":"goods return transaction failed"} | Starting/committing the tenant transaction failed. |
{"error":"goods return operation failed"} | Unexpected database/JSON processing failure; no changes commit. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Primary writes and history commit in one checked tenant transaction. A failed read, write or history insert rolls back the operation; individual bulk failures are not concealed.
- Primary IDs are immutable. Numeric amounts must be finite; integer fields must be whole 32-bit values. Quantities and stock/supplier IDs cannot be negative. Received-note references accept positive integers or legacy -1.
- Updates are partial patches; omitted values remain unchanged. Date/time strings must be exact YYYY-MM-DD HH:MM:SS, with blank/null stored as SQL NULL. customValues must be valid JSON/native JSON and replaces the complete value. Ordinary text "null" is preserved as text.
- Presentation readonly/hidden flags generally do not restrict header writes: dates, totals and delivery values remain writable. lastEdited is server-owned; supplied values are ignored.
- Line edits do not reconcile catalog stock/warehouse containers, calculate totals or touch header timestamps. A supplied grtID must refer to an existing parent. No supplierID alias is mapped.
- Creation ignores id; timestamps default to server now, header customValues defaults to {}, and other omissions use database defaults. Metadata-only line creation still allows omitted parent/quantity.
- Composite stock members override scalar aliases, including zero/blank, on create and update. Supplied stockType must be 1 or 2. qty rejects fractions rather than truncating. grtID and grne_id are integer-mapped.
Side effects
- Changed writes advance last_edited, invalidate the table cache and atomically record field history. noRecord hides named field history; noRecordCustom hides named custom-key history. Neither skips persistence or removes history.
- No notification, PDF generation, accounting export or warehouse/container movement.
See it in Fieldmotion
CRM1
CRM1’s goods-return pages use the legacy GoodsReturned/GoodsReturnedNote calls instead of this mapped operation.
CRM2
CRM2’s goodsReturnedEntry mapping uses this family. Its configured GoodsReturnedEntry_getLayoutDetails now delegates to the authenticated safe detail reader; Layout_getValue resolves it.