Fieldmotion API Getting started

Stock catalog fields and lookups

Save a stock nominal code

POST /a/Stock_nominalSet

Replace the stock ledger code without looking up or validating a local account.

When to use this endpoint

Use only when the caller already knows the intended accounting code. An account ID is not automatically converted into its code.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. This handler requires both a user identity and tenant context; it adds no stock-page, finance or administrator permission check.

All queries use the authenticated tenant. API signing and session CSRF checks still apply; see Getting started.

Parameters

ParameterTypeRequiredDescription
idInteger-compatible stringYesStock ID, converted with intval; use a positive tenant-local ID.
valStringYesRequired scalar, string-normalized; blank is accepted. Maximum 10 bytes. No account-existence/code-format check: supply the intended literal ledger code, not an account ID.

Example request

$result = FM_api('Stock_nominalSet', ['id'=>'1042', 'val'=>'4000']);

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"}Missing/nonpositive id.
{"error":"missing or invalid parameter: val"}val is absent/null.
{"error":"stock catalog write failed"}A primary write or required history insert fails; the transaction rolls back.
{"error":"stock catalog read failed"}A checked read fails; a normalization or write transaction is rolled back.
{"error":"stock catalog transaction failed"}Transaction start or commit fails; no success is returned.
{"error":"stock catalog operation failed"}Unexpected database/runtime failure during the transaction.
{"error":"Stock item does not exist"}Missing/deleted target.
{"error":"parameter too long: val"}Normalized val exceeds 10 bytes.

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

Behaviour and edge cases

  • Locks and validates a non-deleted target. Archived stock remains eligible; missing/deleted stock produces an error rather than false success.
  • Repeated unchanged code returns ok without touching timestamps, history or listeners.
  • Only nominal_code is changed, not meta nominal-account selections, tax_rate or customer pricing. The literal code is not resolved against local accounts.
  • Stock_edit runs after the checked write/history transaction commits. No finance permission or integration feature gate is enforced.
  • No direct mobile caller was found in the current app JavaScript or m/www intermediary. The app receives stock through syncDownloads, which selects non-deleted stock by edit timestamp; these calls are not the app synchronization protocol.

Side effects

  • On change, atomically writes nominal_code, server last_edited and edited_uuid=Stock_nominalSet and checked field history; invalidates stocks cache.
  • Runs configured Stock_edit after commit; no stock movement.

See it in Fieldmotion

CRM1

No direct caller was found. CRM1 displays nominal_code from the stock table; do not infer that clicking the display invokes this endpoint.

CRM2

No direct CRM2 browser caller was found for this exact endpoint; the Stocks module uses mapped Stock reads and writes.

Related endpoints