When to use this endpoint

Use remote=1 to request fresh codes, poll the returned instruction ID, then omit remote to reload saved catalogues. The immediate queue response contains the old catalogues.

Authentication and permissions

Use signed API-key authentication or a logged-in CRM session on the account’s routed host. API keys act as their owner; session requests require the dispatcher’s CSRF token where configured. Tenant rows and settings belong to that authenticated account.

These handlers add no accounting page or CRM2 role check. The dispatcher has no Accounting/DataSync object-scope mapping. Settings-screen access controls are separate from these shared API handlers; CRM2 screen roles are not a CRM1 API requirement.

Parameters

ParameterTypeRequiredDescription
idInteger-compatibleYesPositive DataSync record ID from DataSync_new or DataSyncs_list, not an instruction ID.
remoteInteger-compatibleNoOmitted/zero reads saved catalogues; any nonzero integer-converted value queues a refresh and requires unlocked state.

Example request

$result = FM_api('DataSync_getNominalsAndTaxes', ['id'=>'14', 'remote'=>'1']);

Example response

{
  "ok": 1,
  "id": 82,
  "nominals": "{}",
  "taxes": "{}"
}

Database numeric values can be strings. Read the JSON error/warning fields as well as the HTTP status.

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, zero or negative ID.
{"error":"DataSync does not exist"}No matching tenant DataSync.
{"error":"cloud Data Sync is retired and no longer available"}The stored sync_type is not sage50accounts or gnucash.
{"error":"DataSync is locked. Please cancel whatever is running"}The saved locked value is nonzero; the operation is not queued.
{"error":"DataSync settings are busy. Please try again."}Another tenant DataSync mutation owns the lease.
{"error":"Unable to save DataSync changes. Please reload before retrying."}A transaction/read/write/commit failed. Reload saved state before retrying.

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

Behaviour and edge cases

  • Read mode returns a bare object id,locked,nominals,taxes,sync_type, with no ok. Its id is the DataSync record ID. Queue mode returns ok,id,nominals,taxes, where id is the new instruction ID.
  • nominals/taxes remain encoded JSON strings in both modes. The mapper decodes their catalogues and map keys in the UI; they are not converted into normalized arrays here.
  • The observed mapper expects a remote list plus map inside each decoded catalogue. Nominal remote entries expose number/name; tax entries expose name/description/rate. The CRM1 tax selector offers matching tax rates, but this endpoint does not impose that UI filter.
  • Only local sync types are accepted. Queue mode checks locked state and pending instructions, but does not require logged_in=1; it inserts method syncNominalsAndTaxes with params:[].
  • Uses a tenant mutation lease and a checked database transaction. Queue, mapping and connection-creation writes commit together or return an error with rollback. Busy requests must be retried after reloading; an uncertain commit requires a fresh read before retrying.

Side effects

  • Read mode is database-only. Queue mode atomically inserts an instruction and sets locked=1,last_edited=Unix now; the agent later updates catalogues and releases the lock.

See it in Fieldmotion

CRM1

Open Settings → Data Sync. The pageSettingsDataSync screen uses this route for the operation described above; filter browser Network requests by the exact function name. Local-agent setup is separate from the cloud Finance integrations. Open the nominal/tax mapper; the UI first sends remote=1, polls the instruction and then rereads without remote.

CRM2

Open Settings → Data Sync. The CRM2 pageSettingsDataSync screen retains this local-agent workflow; filter browser Network requests by the exact function name. Its screen permissions do not add a role check to this shared handler. Open the nominal/tax mapper; the UI first sends remote=1, polls the instruction and then rereads without remote.

Related endpoints