Fieldmotion API Getting started

Goods Received

Update receipt header fields

POST /a/GoodReceived_updateData

Edit receipt metadata without replaying stock intake.

When to use this endpoint

Edit receipt metadata without replaying stock intake.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Session CSRF, account-active and IP restrictions still apply. These handlers add no receipt-specific page, finance, department or record-owner permission check.

Records are scoped to the authenticated tenant. CRM1 displays Goods Received with employer feature bit 262144; CRM2 checks features2.goodsReceivedNotes. Those screen gates are not enforced by these handlers. Mobile receipt routes run separately through the mobile intermediary and have different permission and ownership checks.

Mapped handlers require both a logged-in user and a tenant context before loading the tenant field map.

Parameters

ParameterTypeRequiredDescription
idInteger or native arrayYesOne header ID or a native bulk list. No existence validation beyond the helper read.
supplierID, poIDIntegerNoSupplier and purchase-order IDs, converted with intval. No existence, approval, supplier/PO consistency or ownership validation.
cDate, lastEditedDate/time stringNoMapped cdate / last_edited. Creation defaults both to server now; blank datetime input becomes SQL NULL. No tenant-timezone conversion or strict datetime validation. Changed updates also append a server last_edited assignment; do not supply lastEdited to override it.
createdByIntegerNoStored created_by; GoodReceived_createData forces the authenticated user. Other mapped writes do not enforce that identity.
notesText or native structured valueNoWhole notes replacement; native arrays/objects are JSON-encoded. UI uses structured notesboxReverse notes.
targetNative objectNoComposite {id,type} expands to targetID / targetType. UI choices: 0 no link, 1 contract, 2 customer, 3 quote, 4 job. Numeric aliases themselves are not enum-validated.
targetID, targetType, jobIDIntegerNoDirect stored link aliases. jobID is writable despite UI readonly metadata; targetType/targetID do not synchronize jobID.
suppInvoice, suppDNNTextNoSupplier invoice and delivery-note references; no uniqueness or supplier validation.
purchaseOrdersTextNoStored purchase_orders value. UI readonly metadata is not a server write restriction; this is not the poID alias.
customValuesJSON text or native objectNoWhole custom_values replacement; creation defaults to {}. No per-key merge. Invalid stored JSON can be rejected by the database.
noRecord, noRecordCustomNative arraysNoLegacy history-hidden controls, not authorization or no-write switches. noRecordCustom controls custom-key history; do not rely on noRecord to suppress creation history because the helper compares a reused loop key.

Example request

FM_api('GoodReceived_updateData', ['id'=>'531', 'suppInvoice'=>'INV-1042', 'notes'=>'Checked by stores']);

Example response

{"ok":1}

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"error":"missing or invalid parameter: id"}id is omitted.
{"error":"Unable to update record"}A mapped update failed; a bulk error includes updatedIds and failedId.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Mapped integer fields use intval; UI hidden/readonly metadata is not a server authorization rule. Unmapped keys are ignored. The literal string null is treated as SQL NULL even for ordinary text, while omitted/null keys are generally skipped by isset.
  • Scalar updates compare converted values and return {"warning":"No Change."} if unchanged. Missing targets return {"warning":"No data."}; unknown-only changes return {"warning":"no updated fields."}. An id-only request returns {"ok":1}. These warnings are not errors.
  • Native id arrays are processed sequentially, not transactionally. A write error stops the loop and returns updatedIds (the processed prefix) and failedId; prior changes remain. Warning-only rows count as processed; an empty list returns ok.
  • Changed writes invalidate the mapped table cache, advance last_edited and append field/custom-value history after persistence. History is not part of an all-or-nothing transaction.
  • widgetGoodReceivedEntry is not processed on update. Editing supplier, links, received date or notes does not reconcile stock, reservations, PO status or receipt lines.
  • sendNotices is called for supplied structured notes after any non-error result. This call does not request oldData from DataProcessClass, so mention deduplication against previous notes is not reliable.

Side effects

  • Changed header persistence/cache, edit timestamp and mapped history. Structured notes can create mention notices; no stock intake or invoice creation.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found. CRM1 uses the legacy GoodsReceived_newNote, GoodsReceivedEntries_get and GoodsReceivedNote_* workflow instead.

CRM2

In CRM2 open Goods Received and a receipt layout, then filter browser requests for Layout_getValue / Layout_setValue. The goodReceived table mapping dispatches header reads to GoodReceived_getLayoutDetails and creates/updates to GoodReceived_createData / GoodReceived_updateData.

Related endpoints