Goods Received
Apply a receipt to an existing job
/a/GoodsReceivedNote_jobCreate
Copy received goods onto an existing job, create a draft invoice and deduct catalog warehouse stock.
When to use this endpoint
CRM1 first creates a job in its Job editor and passes its saved job_id here. This endpoint adds the receipt stock to that existing job and creates its draft invoice; it does not create the job itself.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Session CSRF, account-active and IP restrictions still apply. These handlers add no receipt-specific page, finance, department or record-owner permission check.
Records are scoped to the authenticated tenant. CRM1 displays Goods Received with employer feature bit 262144; CRM2 checks features2.goodsReceivedNotes. Those screen gates are not enforced by these handlers. Mobile receipt routes run separately through the mobile intermediary and have different permission and ownership checks.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
grn_id | Integer | Yes | Receipt ID; intval must be positive and the receipt must have at least one line. |
job_id | Integer | Yes | Positive existing active job ID. Missing/invalid IDs or missing/deleted jobs reject the operation before conversion writes. |
Example request
FM_api('GoodsReceivedNote_jobCreate', ['grn_id'=>'531', 'job_id'=>'8042']);Example response
{"ok":1,"id":8042}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":"no goods received note id specified"} | grn_id omitted/invalid. |
{"error":"goods received note does not exist"} | Receipt read failed/missing. |
{"error":"no line items recorded for this goods received note"} | Line read failed/empty. |
{"error":"missing or invalid parameter: job_id"} | Missing/invalid positive job ID. |
{"error":"job does not exist"} | Job is missing/deleted. |
{"error":"goods received note already linked to another job"} | Receipt already has a different job_id. |
{"error":"insufficient stock"} | Active catalog quantity is below aggregate conversion consumption. |
{"error":"goods receipt write failed"} | Checked conversion persistence failed; transaction rolls back. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Locks the receipt and active job, then receipt lines and active catalog stock. Missing lines, malformed existing job JSON, missing/deleted stock or insufficient aggregate catalog stock reject the transaction.
- Preserves existing job metadata, sets po_id from the receipt header and grn_id, and appends catalog {id,amt,source:0} entries to existing stock_used. Free-text lines appear in invoice rows only. Job last_edited and edited_uuid advance; receipt job_id and last_edited advance together.
- Catalog pricing comes from current stock.price; free-text pricing comes from the linked PO entry cost_net (missing entry gives zero). Decimal quantities are not truncated. Row net is rounded quantity × price; row gross includes default-vat percentage. Invoice total_net and total sum those net/gross amounts.
- Job customer details drive invoice ownership; asset jobs require an active asset and resolve its owner. The first type-2 job-to-quote link in ID order supplies quote_id.
- Creates a status=-1 invoice using Invoice_getNumNext (acc-inv-num-method: 1 increments the largest number, 2 leaves it blank, otherwise the latest invoice supplies the sequence). Canonical Invoice_rowsStore persists rows and storage is checked before commit. The returned id is the job ID, not the invoice ID.
- Deducts aggregate catalog quantities with stock history, last_edited and edited_uuid changes. No inventory/container movement is performed. The customer invoice marker is updated after the main conversion commits; no email or event helper is invoked.
Side effects
- Atomic job metadata/stock append, receipt link, draft invoice/row storage and catalog stock deduction with history/edit markers. Same-receipt/job retries have no conversion side effects. Customer invoice marker is refreshed after commit.
See it in Fieldmotion
CRM1
Click Create Job on a receipt row. CRM1 opens jobEdit first and calls GoodsReceivedNote_jobCreate with its saved ID; watch both requests to distinguish job creation from this conversion.
CRM2
No direct CRM2 caller was found. CRM2 receipt widgets use GoodReceived_createData allocation/dispatch and do not invoke this legacy invoice conversion.
Related endpoints
GoodsReceivedEntries_get— inspect quantities before applying them.GoodReceived_createData— different CRM2 intake/dispatch workflow.