Stock items and catalogue maintenance
Read selected mapped stock fields
/a/Stock_getRequestedDetails
Return projected stock rows with optional supplier and allocation summaries.
When to use this endpoint
Use fields as a native array. Supply id/ids deliberately: omitting the ID selection can return all matching undeleted stock; an explicit empty array returns [].
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 |
|---|---|---|---|
id / ids | Scalar ID or native ID array | No | id takes precedence over ids. Without either, reads can return all matching undeleted stock. Explicit empty ID arrays return an empty result; JSON-encoded ID lists are not decoded here. |
fields | Native array of field names | Yes for this wrapper | Use mapped names, not snake_case columns. 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. |
order | Native array | No | Mapped field names or {id:field,dir:asc|desc} objects; no order is added unless supplied. |
Mapped filters | Scalars/native arrays | No | Known map keys filter by exact normalized value/list. Numeric filters integer-convert. No implicit archive restriction. Typed advanceSearch is a native list of {id:stock_name,condition:equal,value:Valve} rules. Supported conditions: equal,contains,notEqual,greaterThan,greaterThanOrEqual,lesserThan,lesserThanOrEqual. A rule containing raw where SQL is rejected. |
Example request
$result = FM_api('Stock_getRequestedDetails', ['id'=>['18'], 'fields'=>['id','name','averageCost','price']]);
Example response
[
{
"id": "18",
"name": "Valve",
"averageCost": "12.5",
"price": "20.0000"
}
]
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":"invalid advanced search"} | Raw SQL advanceSearch controls are rejected. |
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.
- Returns a bare row array. The shared reader adds id, excludes deleted rows, omits missing IDs, and leaves saved JSON fields encoded; it does not paginate or preserve requested ID order. Includes archived items unless explicitly filtered.
- Empty-choice filtering is distinct from zero: advanceSearch with id=stock_categoryIDS,condition=equal,value="" matches uncategorized stock. For metaReferrenceType, value 2 means No Reference and 0 means Batch; do not substitute zero for an unset choice.
- 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.
Side effects
- Database reads only; unlike Stock_get, no category repair is performed.
See it in Fieldmotion
CRM1
No direct CRM1 caller for this mapped reader was found. CRM1 uses Stock_get and legacy list/grid endpoints.
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. Open a Stock record or its allocation/inventory screens; they request selected fields via Stock_getRequestedDetails.
Related endpoints
Stocks_getDataTable— Return named stock rows with mapped filters, paging and optional supplier/allocation summaries.Stock_getLayoutDetails— Read mapped stock rows while adapting price-band widgets and tax category selections.Stock_get— Read the full saved stock row, with selected manufacturing metadata flattened for the legacy editor.