Reconcile an uncertain receipt

When to use this endpoint

A client administrator must first determine the provider outcome independently. Supply a reason describing that evidence; this API trusts the supplied resolution and does not query the provider.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session; session dispatch applies CSRF checks. The authenticated tenant must have features2.ukDigitalWasteManagement=1. The feature is read from the account record, not trusted from request input.

Requires client-administrator access. A page Edit permission or wildcard role alone does not replace the client-admin check.

Parameters

Parameter	Type	Required	Description
`job_id`	Integer-compatible	Yes	Nonzero tenant Job with a latest ambiguous/ambiguous: mapping.
`outcome`	String enum	Yes	accepted or not_accepted after trimming. Other values fail.
`reason`	Nonblank string	Yes	Trimmed audit reason. The service requires it; the CRM records it in a Job edit log.
`tracking_id`	String	Required for accepted	Accepted outcome requires 1–32 ASCII letters/digits/hyphens. not_accepted ignores the submitted value and retains any previous known tracking ID.

Example request

$result = FM_api('DigitalWasteTracking_reconcile', [
	'job_id'=>'1042',
	'outcome'=>'accepted',
	'reason'=>'Confirmed in the provider test portal',
	'tracking_id'=>'WT-SYNTHETIC-1042',
]);

Example response

{
  "ok": 1
}

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":"UK Digital Waste Tracking is not enabled for this account"}`	The account feature is disabled.
`{"error":"outcome and reason are required"}`	The CRM rejects an invalid outcome or blank reason.
`{"error":"invalid_reconciliation"}`	The mapping is not ambiguous or the service rejects the supplied outcome/reason.
`{"error":"submission_may_be_in_progress_wait_five_minutes"}`	The ambiguity marker is newer than five minutes.
`{"error":"valid_tracking_id_required"}`	accepted has a blank or invalid tracking ID.
`{"error":"client administrator access required"}`	The identity is not a client administrator.

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 CRM forwards this operation to its signed on-complete service with the tenant and actor installed server-side. A caller cannot choose another tenant. Missing service configuration returns Digital Waste Tracking service is not configured; a non-JSON service reply returns Digital Waste Tracking service returned an invalid response.
Requires the ambiguous marker to be at least five minutes old (mapping cdate in Unix seconds); newer markers return submission_may_be_in_progress_wait_five_minutes. A local file lock and tenant Job-row/mapping transaction serialize the resolution against submission.
accepted writes the provided tracking ID and converts the instance to profile:. not_accepted retains a previous tracking ID if one existed (for example an uncertain update), converting that historical mapping back to submitted; if no ID existed it removes the empty ambiguity mapping, allowing a new submission.
No provider request is made and no receipt is withdrawn. A subsequent status/Operations read reflects the local mapping. This does not repair a provider receipt or prove that the caller’s declared outcome is correct.
Service mapping and reconciliation history writes are checked before transaction commit; a failure rolls back the resolution. A subsequent CRM history failure returns ok=1,reconciled=1 with a warning because the service resolution is already saved. Reload before any further send.

Side effects

Updates or removes the retained ambiguity mapping and writes service/CRM Job history. Does not contact the provider, alter Job answers or queue a retry.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found in the production JavaScript source. The operator workflow is implemented in CRM2.

CRM2

Operations > ambiguous row > Reconcile opens provider outcome, tracking ID and audit reason controls. The UI hides tracking_id for not_accepted and sends the administrator’s resolution.

Related endpoints

DigitalWasteTracking_operations — Find ambiguous entries and reload their state.
DigitalWasteTracking_status — Verify the resulting local submitted/ambiguity state.
DigitalWasteTracking_submit — Continue only after reconciliation succeeds.