Fieldmotion API Getting started

Goods Received

Set one mapped receipt header alias

POST /a/GoodReceived_updateField

Change one receipt header field across selected IDs.

When to use this endpoint

Change one receipt header field across selected IDs.

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
id, idsInteger or native arrayYesPositive receipt ID or nonempty native list of positive IDs; id takes precedence. Every requested record must exist. Duplicate IDs are deduplicated.
fieldMapped aliasYesMapped header alias with a physical column, except id and lastEdited. The composite target is not directly supported; use targetID/targetType.
valMapped valueYesReplacement value. Integer fields require valid finite integers; text accepts strings/numbers or JSON-encoded native structured values. customValues must be valid JSON. Date/time values are validated; null fails the required isset check.

Example request

FM_api('GoodReceived_updateField', ['id'=>'531', 'field'=>'suppDNN', 'val'=>'DEL-1042']);

Example response

{"ok":1,"oldData":[{"id":"531","supp_dnn":"DEL-1041"}]}

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: field"}field omitted.
{"error":"missing or invalid parameter: val"}val omitted/null.
{"error":"missing or invalid field"}Unknown alias.
{"error":"missing or invalid parameter: id/ids"}Neither selector supplied.
{"error":"goods received note does not exist"}At least one requested header is missing; no field changes commit.
{"error":"goods receipt write failed"}A checked field/history write failed; transaction rolls back.

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

Behaviour and edge cases

  • One checked transaction locks all requested receipt headers. A missing target, failed update/history write or failed commit rejects the complete field-save batch; no prefix remains committed.
  • Primary id, lastEdited and unsupported composite target fields are not writable through this route. Use targetID/targetType for the separate link columns. UI readonly metadata is not otherwise an authorization rule.
  • Changed saves update server last_edited, add per-receipt field history and invalidate receipt caches. Stored values are compared without SQL escaping, so unchanged quoted text does not trigger a rewrite.
  • Returns oldData containing all selected rows with id and the physical selected column name, not the public alias. An unchanged batch returns {"ok":"1","warning":"no change required"}.
  • Integer aliases require a finite integer in the supported range. Datetime input accepts YYYY-MM-DD or YYYY-MM-DD HH:MM:SS, with blank/null-text clearing it. customValues accepts valid JSON text or native structured values, without a per-key merge.
  • The literal string null clears mapped text/JSON fields. There is no mention-notification helper on this narrow route; saving notes here is not the creation mention workflow.

Side effects

  • Atomic header field/edit-timestamp/history writes and receipt cache invalidation. No stock/line/PO recalculation or mention notifications.

See it in Fieldmotion

CRM1

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

CRM2

No direct named CRM2 caller was found. Standard receipt layouts dispatch GoodReceived_updateData through Layout_setValue, not this narrow field route.

Related endpoints