Skip to content

Submit a MAD batch

When to use this

You need Docmation to file a new VLM MAD (Mestafzetdocument) transport document with the Flemish VLM portal. Each call to AddWorkItemCreate appends one work item to the tenant's open MAD batch (or auto-creates a batch if none is open). The batch is later picked up by a WebBot worker and processed against the live VLM system.

Prerequisites

  • A valid JWT (see Authentication) issued for an API key with Role.ApiKey.
  • The shipment data ready: operator code, sender + receiver UBNs, manure type, planned load, transport plate, etc.
  • (Optional) A webhookUrl your service can receive a callback on once processing completes — see Receive webhooks.

Walkthrough

1. POST the work item

POST /api/VlmMad/AddWorkItemCreate

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

body.json:

{
  "customerReference": "ORDER-2026-0001",
  "documentReference": null,
  "webhookUrl": "https://example.com/docmation/webhook/{0}",
  "operatorCode": "OP-001",
  "deliveredApproval": "...",
  "deliveredApprovalNumber": "...",
  "transporter": "BE0123456789",
  "contractCode": "C-2026-42",
  "sender": "BE12345-0001",
  "senderAlias": "",
  "senderCountry": "BE",
  "senderTransportCharacter": "A",
  "senderCharacterNumber": "1",
  "receiver": "BE67890-0001",
  "receiverAlias": "",
  "receiverCountry": "BE",
  "receiverTransportCharacter": "A",
  "receiverCharacterNumber": "1",
  "manureType": "RUNDERMENGMEST",
  "manureContentValue": "STANDARD",
  "date": "2026-06-04T08:00:00+02:00",
  "resumeDate": null,
  "licensePlate": "1ABC123",
  "licensePlateTrailer": null,
  "plannedLoad": 28.5,
  "contentKgTonN": 4.2,
  "contentKgTonP2O2": 1.8,
  "plannedFreights": 1,
  "previousDocumentReference": null,
  "previousDocumentId": null
}

Response (HTTP 200 OK):

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

Store both ids: workItemId is what you poll/cancel/download against later; workBatchId is the batch it landed in.

2. (Optional) Wait for completion

Either listen for the webhook (see Receive webhooks) or poll the result endpoint:

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

See Poll work-item status for the response shape and polling strategy.

What to watch for

  • 422 Unprocessable Entity — domain validation rejected the payload (e.g. unknown operatorCode, missing required field). The body is IList<string> of error messages; fix the fields and resubmit. Do not retry the same payload.
  • 401 Unauthorized — the JWT expired or is missing the Role.ApiKey claim. Re-authenticate via /api/Login/Authenticate.
  • Duplicate submissions — there is no idempotency key. If a submit times out and you have no workItemId, look the work item up by customerReference via GET /api/VlmMad/GetResultByReference?reference=<your-ref>&taskType=Vlm_Mad_Create before resubmitting.
  • Background processing — the API call only enqueues the work item; actual document creation happens later in a batch. Until the bot picks it up, status stays Queued/Created.

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