Cloud accounting and selective sync
Start cloud accounting authorization
/a/Accounting_authorisation
Obtain the provider’s OAuth consent URL before connecting or renewing permissions.
When to use this endpoint
Select a provider, request ret=1, then open the returned url in a browser. Complete the provider callback before checking Accounting_status. An authorization URL alone does not establish a connection.
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.
Only Xero authorization bypasses the facade login requirement; this does not make status, logs, sync or disconnect public. No extra CRM2 role is imposed here.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
provider | String | Yes | Case-insensitive after trimming: quickbooks, xero, or microsoftbusinesscentral. Other names, including datasync, are rejected by the cloud facade. |
ret | Present value | No | For Xero and Business Central, any non-null supplied value, including 0 or an empty string, selects a JSON URL response. Omit it for an HTTP redirect. QuickBooks returns JSON regardless. |
api_server | HTTPS URL | No | Callback host override, otherwise the current HTTP host. Xero and QuickBooks accept only https:// followed by a lowercase alphanumeric Fieldmotion subdomain and trailing slash; Business Central uses its broader Fieldmotion host pattern. Use the account’s configured API server. |
reconnect | Legacy UI value | No | The Xero UI sends 1 when renewing consent. This authorization function does not branch on this flag; callback/session behavior controls reconnection. |
Example request
$result = FM_api('Accounting_authorisation', ['provider'=>'xero', 'ret'=>'1']);
Example response
{
"url": "https://login.xero.com/identity/connect/authorize?...",
"redirect": "https://replace-with-your-host.fieldmotion.com/a/Xero_callback",
"provider": "xero",
"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":"missing or invalid parameter: provider"} | The provider is absent or outside the facade whitelist. |
{"error":"Xero client info not configured"} | Server OAuth credentials are missing for Xero. |
{"error":"Microsoft Business Central client info not configured"} | Server OAuth credentials are missing for Business Central. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- The facade appends provider and supplies ok:1 only when the returned array has no error or ok. Provider-specific fields remain intact; early provider validation errors have no provider field.
- Xero is the facade’s public authorization exception and is reachable through the dispatcher’s public Xero GET flow. QuickBooks and Business Central require login. A signed-in request still follows normal session/CSRF handling.
- Callbacks remain PluginQuickBooks_registerToken, Xero_callback and SyncMicrosoftBusinessCentral_callback. Provider application credentials must already be configured on the server.
- Xero requests granular invoice/payment scopes. Renew consent without disconnecting or clearing links; its signed-in callback retains the linked organization. Authorization does not configure tax/account mappings or select a Business Central company.
Side effects
- Stores the callback API server in the session. Xero and Business Central create a global oauth_logins state row; the provider callback later saves tokens/connection state.
- Opening the returned URL starts external provider consent. The no-ret redirect paths exit before JSON normalization.
See it in Fieldmotion
CRM1
Open Settings → Finances and the QuickBooks or Xero integration. Filter the browser Network panel for this Accounting route; these screens send provider explicitly. Provider-specific setup remains on the original provider routes. Click Connect or renew Xero permissions; ret=1 returns a URL for the consent popup. Business Central has no CRM1 settings caller; its configuration UI is CRM2-only.
CRM2
Open Settings → Finances and the corresponding provider. The QuickBooks widget, Xero settings/background sync, and Business Central action wrapper call this facade with provider. Filter the browser Network panel for the endpoint name. Click Connect or renew Xero permissions; ret=1 returns a URL for the consent popup.
Related endpoints
Accounting_status— Check connection state.Accounting_providerCapabilities— Read the provider catalogue.Accounting_disconnect— Remove cloud credentials.