Fieldmotion API Getting started

Stock exports and reporting

Export stock dispatched to jobs

POST /a/Stock_exportJobsDispatched

Compare positive dispatched job balances without losing fractional quantities.

When to use this endpoint

Use to reconcile outgoing job quantities; it does not mix allocated Job containers into the matrix.

Authentication and permissions

Authenticate with a signed API-key request or a logged-in CRM session. Requires Stock view (pageStocks_view) and table export (pageMain_exportTableData) permissions through the shared export guard; denial returns permission denied.

Client administrators and the all permission satisfy the checks. Legacy users with no role use the helper’s allow fallback when no explicit permission list is loaded. This is not merely the CRM1 export-button bit check.

Queries use the authenticated tenant. No department/owner restriction or stock-tracking feature gate is added by these handlers. CRM2 features2.stockTracking changes the export choices offered, not server authorization. Session CSRF and API signing still apply.

Parameters

ParameterTypeRequiredDescription
yesStringYesMust equal really. This compatibility confirmation is checked before the handler login/permission checks; it does not authorize the export.
stockIDsFilterComma-separated stringNoOptional comma-separated positive decimal IDs, with whitespace trimmed and duplicates removed. Empty/whitespace means unfiltered. Non-string, malformed, zero or negative tokens are rejected before output.

Example request

$csv = FM_api('Stock_exportJobsDispatched', ['yes'=>'really']);

Example response

ID,Name,Code,TOTAL,COST,"TOTAL COST",2042
1042,"Filter cartridge",FLT-01,0.5,4.5,2.25,0.5

Success is raw CSV, not JSON: retain the response body instead of JSON-decoding it. The response uses text/csv and the final download filename stock-jobs-dispatched.csv. Column positions and blank cells are meaningful.

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":"permission denied"}Either required export permission is denied.
{"error":"yes is not really"}yes is omitted or differs from really.
{"error":"invalid parameter: stockIDsFilter"}Selected-ID input is non-string or contains no positive integer-converted IDs.
{"error":"could not load dispatched stock"}Aggregate read returns false; no CSV has been streamed.
{"error":"invalid parameter: stockIDsFilter"}A supplied selected-ID list is not a string of positive decimal IDs.
{"error":"invalid parameter: search"}A supplied stock/date filter is an array or other non-scalar value; the error names that parameter.

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

Behaviour and edge cases

  • Uses container type 18 (OutJob), amt>0 and non-deleted stock. Archived stock is included; no job deletion/status/department check is added.
  • Both axes are derived from the same dispatched aggregate query. Stock rows and numeric job-ID columns are ordered by IDs.
  • Preserves float sums; missing cells are blank. COST is stock average cost and TOTAL COST is quantity total × that cost.
  • Shared name/category/trigger/date filters are not consumed.
  • No pagination or result limit is implemented. The entire result is exported; a header-only CSV is a valid empty result.
  • No stock quantity, audit, edit timestamp, notification or event is changed. Reads across multiple queries are not a transactionally frozen snapshot.
  • No direct caller for this exact endpoint was found in the current app JavaScript or m/www intermediary; these are office reporting/source-selection calls, not the app download protocol.
  • The shared guard rejects non-scalar supplied stock/date filters and validates any supplied stockIDsFilter even on reports that do not use it for selection.

Side effects

  • Streams CSV directly to the response, closes the output stream and exits.

See it in Fieldmotion

CRM1

No direct caller for this exact endpoint was found in CRM1. Its Stock page has separate warehouse, user, vehicle, customer and cost export actions.

CRM2

Open Stocks, choose Export, select the matching report and submit. Filter Network for Stock_exportJobsDispatched (the posted form uses php/api.php with extra=/Stock_exportJobsDispatched). CRM2 supplies yes=really and a comma-separated stockIDsFilter for the selected export scope.

Related endpoints