Stock items and catalogue maintenance
Filter and page mapped stock
/a/Stocks_getDataTable
Return named stock rows with mapped filters, paging and optional supplier/allocation summaries.
When to use this endpoint
Use this for the CRM2 catalogue table. Unlike Stock_getDT it returns named mapped fields, not positional cells.
Authentication and permissions
Authenticate with a signed API key or a logged-in CRM session on the account’s routed host. API keys act as their owner; session calls require dispatcher CSRF protection where configured. IDs address the authenticated tenant.
These stock handlers do not add a Stock page-action or CRM2 role check, and the dispatcher has no Stock/Stocks TeamAccess object mapping. CRM2 screen controls are separate from this shared API contract; their roles must not be assumed to apply to CRM1.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
fields | Native array | Yes | Mapped names: id,name,averageCost (alias cost),cDate,ownerID,inStock,categories,categoryIDS,lastEdited,code,isArchived,amtTrigger,description,supplierID,price,notes,nominalCode,taxRate,meta,editedUUID,priceBands. Metadata projections: metaManufacturer,metaBarcode,metaManufacturerPartNo,metaSupplierPartNo,metaSuppliers,metaUnit,metaTaxRateID,metaNominalCodeID,metaNominalID,metaNominalName,customValues,metaReferrenceType. taxType is a composite picker with id,taxRate,nominalID,nominalName,nominalCode. Preserve the misspelling metaReferrenceType. Special computed fields: suppliers,allocated,container. |
isTable / start / length / draw | Integer-compatible | No | isTable defaults 1; start=0,length=10,draw=0. Table mode returns data/draw/recordsTotal/recordsFiltered. isTable=0 returns data only; limit>0 can cap that non-table result. |
orderBy / orderDesc | Mapped field / direction | No | Paired explicit field/direction or DataTables order[0].column/dir. DataTables column is offset by one before resolving a selected field. Use trusted asc/desc; main.id ascending provides a stable tie-breaker. |
searchField / searchValue | Field(s) / text | No | Mapped substring search; omitted searchField searches All. searchField=metaUnit translates pcs/length/weight to 0/1/2 and an unknown nonblank label matches nothing. |
categoryIDS | Scalar/native list | No | OR membership via JSON_SEARCH; handled specially before mapped filters. Use the numeric selections sent by the UI, not arbitrary SQL text. |
suppliers | Positive integer or native list | No | Positive numeric scalar/native ID list. Filters stock_suppliers through EXISTS, avoiding duplicate rows/counts. |
locationTagsFilter / batch | Text | No | Location searches stored meta.location_tags text. batch joins undeleted stock_inventories by reference substring. |
hasFiles | Native selection list | No | Native selection list: 0 has current file; 1 no current file; both means unrestricted. Uses undeleted file type 20. |
Mapped filters / advanceSearch | Mapped values / native filter structures | No | Known mapped scalar text filters use contains matching; numeric filters use the shared numeric coercion and native lists form membership filters. No implicit isArchived=0. advanceSearch is a native list, for example [{id:stock_categoryIDS,condition:equal,value:""}]. Conditions: equal,contains,notEqual,greaterThan,greaterThanOrEqual,lesserThan,lesserThanOrEqual. Raw where rules are rejected. |
Example request
$result = FM_api('Stocks_getDataTable', ['fields'=>['id','name','inStock','allocated'], 'start'=>'0', 'length'=>'25', 'draw'=>'1', 'isArchived'=>'0']);
Example response
{
"data": [],
"draw": 1,
"recordsTotal": "0",
"recordsFiltered": "0"
}
Application errors can use HTTP 200. Inspect error/warning fields; database numeric values can be strings unless this handler explicitly converts them.
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: suppliers"} | A supplier ID is not a positive digit string/integer. |
{"error":"invalid advanced search"} | Raw advanceSearch SQL is rejected. |
{"error":"invalid stored location tags"} | Projected metadata contains an unsupported tag shape. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- container begins with {id:0,type:0,qty:warehouseQuantity}, followed by {id,type,qty} allocation entries. allocated is the floating-point sum of the non-outbound allocations, excluding warehouse quantity. Known type-2 vehicle rows retain uuid alongside their local id.
- Supplier link entries contain numeric id,cost,price,onHold plus name. A fallback has an empty id, item cost/price and the default supplier name, without onHold.
- Deleted catalogue items are excluded; archives are included unless isArchived=0 is requested. recordsTotal counts all undeleted stock; recordsFiltered counts each matching stock item once. Native table paging defaults to start=0,length=10.
- There is no account setting or schema feature check here to turn the raw quantities into reservations/available stock. The warehouse and allocated figures describe different balances.
- Unset category choice filtering treats an empty category selection separately from zero; advanceSearch stock_categoryIDS equal empty string matches uncategorized items. metaReferrenceType=2 is No Reference and 0 is Batch, as verified by the existing unset-choice regression.
- Allocated/container quantities remain floating-point values, including warehouse quantity. Both mapped readers exclude outbound types 14,18,20 from allocation totals. Type-2 vehicle UUID mapping retains uuid alongside the local vehicle ID when known.
- Supplier entries use stock_suppliers values. With no explicit link, the fallback uses the default supplier’s name and item cost/price, with an empty supplier-link ID.
- Automatically appended supporting fields are removed unless requested; id remains included. Native fields must be a nonempty list of strings. Explicit empty ID selections in Stock_getRequestedDetails return [] rather than broadening the query.
- Supplier and batch selections use EXISTS predicates, so multiple matching links/inventories do not duplicate rows or recordsFiltered. Category OR membership predicates are grouped with other filters.
- categoryIDS accepts positive numeric scalar/native selections; blank/empty selection means no restriction. batch/location filters must be strings. Unsafe sort directions and malformed paging/file controls return parameter errors.
- Attachment filtering uses type_enum=20 and excludes deleted file references. Legacy location-tag lists are still presented as newline text without rewriting saved metadata.
Side effects
- Read only; no category repair or persisted metadata normalization.
See it in Fieldmotion
CRM1
The CRM1 main Stock grid uses Stock_getDT. No direct current CRM1 caller of this mapped table was found.
CRM2
Open Stocks in CRM2. Stock layouts derive Stock_createData, Stock_updateData and Stock_getLayoutDetails through the shared helpers; the grid calls Stocks_getDataTable. Inspect the exact function name in Network requests. moduleStocks requests configured fields/filter selections for Stocks_getDataTable; its QR selection workflow uses the same filters.
Related endpoints
Stock_getDT— Return positional cells and DataTables counts for the CRM1 catalogue grid.Stock_getRequestedDetails— Return projected stock rows with optional supplier and allocation summaries.Stocks_list— Stream a bare JSON stock list with warehouse quantities and an optional field projection.