Local accounting agent queue
Queue local accounting synchronization
/a/DataSyncs_run
Validate local accounting prerequisites and enqueue a sync for every saved DataSync.
When to use this endpoint
Finish code mapping first and ensure no unfinished instruction remains. This tenant-wide operation has no DataSync ID selector; cloud Accounting_sync is a separate workflow.
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
This endpoint has no operation-specific parameters.
Example request
$result = FM_api('DataSyncs_run', []);
Example response
{
"ok": 1
}
Database numeric values can be strings. Read the JSON error/warning fields as well as the HTTP status.
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":"Existing DataSync run already active. If you want to start a new run, please cancel the existing run."} | At least one tenant instruction has no done_date. |
{"error":["Nominals not yet mapped: Office Sage","Taxes not yet mapped: Office Sage"]} | Any saved connection lacks a readiness flag; other validation errors can be accumulated in the same array. |
{"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
- An unfinished instruction attached to a saved local Sage/GnuCash connection blocks the run, returning an error string and syncs containing those whole rows. Historical cloud rows and their pending instructions are excluded from this local batch.
- Collects readiness errors for saved local Sage/GnuCash rows with false nominal/tax mapped flags. These failures return error as an array of strings, unlike the existing-run error string.
- Rejects duplicate stock codes grouped by lower(code) among deleted=0 rows, including archived stock and duplicate blank codes. If any Sage record exists, validates every nondeleted invoice: num must contain digits only and have at most 5 bytes; order_no at most 7 bytes. These checks are not limited by the later invoice export age/status selectors.
- After checks it queues method sync with params:[] and status 0 for each local DataSync, setting each connection locked=1 and last_edited=Unix now. Inserts and lock updates share one transaction. It returns no instruction IDs and does not wait for completion. No local connections can still yield ok:1 after stock validation.
- Agent execution follows its selective policy, mapped identifiers and invoice selectors. Fieldmotion invoices are outbound; inbound invoice handling updates linked/already-matchable rows without creating accounting-only invoices. Read accounting logs for per-object outcomes.
- 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
- Inserts tenant instruction rows for agents to fetch. The HTTP response itself performs no local-accounting export; remote/local business writes occur later through the agent service.
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. Click Sync to queue the tenant batch and then inspect connection history.
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. Click Sync to queue the tenant batch and then inspect connection history.
Related endpoints
DataSync_setNominalAndTaxMappings— Save both code maps.DataSync_getLogs— Read agent activity.DataSyncs_cancelRun— Cancel the tenant instruction queue.Accounting_syncPolicyGet— Read phase modes and supported keys.