Cancel a document¶

When to use this¶

A previously submitted document needs to be withdrawn at the source portal (VLM MAD or EU Traces DOCOM). You enqueue a cancel work item — it is processed in the same batch pipeline as create/download and the actual cancellation happens server-side when a bot worker picks it up. The NVWA RVDM channel does not expose a cancel endpoint today; cancellation there is manual.

Prerequisites¶

A valid JWT (see Authentication) issued for an API key with Role.ApiKey.
The documentReference (or original customerReference) of the document you want to cancel.
For VLM MAD: the operatorCode that owns the document.

Walkthrough¶

1a. VLM MAD — POST a cancel work item¶

POST /api/VlmMad/AddWorkItemCancel

curl -X POST "https://api.docmation.eu/api/VlmMad/AddWorkItemCancel" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json:

{
  "customerReference": "ORDER-2026-0001-cancel",
  "documentReference": "MAD-BE-2026-000123456",
  "webhookUrl": "https://example.com/docmation/webhook/{0}",
  "operatorCode": "OP-001"
}

Response (HTTP 200 OK):

{
  "workBatchId": 12345,
  "workItemId": 67891
}

1b. Traces DOCOM — POST a cancel work item¶

POST /api/TracesDocom/AddWorkItemCancel

curl -X POST "https://api.docmation.eu/api/TracesDocom/AddWorkItemCancel" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json:

{
  "customerReference": "DOCOM-2026-0001-cancel",
  "documentReference": "DOCOM-BE-2026-987654",
  "webhookUrl": "https://example.com/docmation/webhook/{0}"
}

(Traces DOCOM cancel takes only the base fields — no extra cancel-specific properties.)

Response (HTTP 200 OK):

{
  "workBatchId": 23456,
  "workItemId": 78902
}

2. Confirm the cancellation¶

Either rely on the webhook callback (see Receive webhooks) or poll the result of the cancel work item itself:

curl "https://api.docmation.eu/api/VlmMad/GetResult?workItemId=67891" \
  -H "Authorization: Bearer <jwt>"

A status of Finished (60) means the source portal accepted the cancellation; Faulted (50) means it was rejected — inspect the log array for the reason.

What to watch for¶

422 Unprocessable Entity — most often a documentReference the portal does not recognise, or an operatorCode the bot is not authorised for. Body is IList<string>; fix and resubmit.
401 Unauthorized — re-authenticate via /api/Login/Authenticate.
No NVWA cancel — NvwaRvdmController has no AddWorkItemCancel. Treat NVWA cancellations as out-of-band; do not retry against this API.
Background processing — the cancel is enqueued, not executed inline. The document remains "alive" at the portal until the bot processes the cancel work item.
Idempotency — cancelling an already-cancelled document at the portal will typically come back as a Faulted work item with a WorkLogCode indicating the portal's "already cancelled" response. Treat that as a success on your side.

AI-drafted from VlmMadController.cs and TracesDocomController.cs. Verify field names against the live Swagger UI before publishing.