Submit DDS

The local pre-submission gate only approximates TRACES. The authoritative check is a live round-trip of the byte-identical filing envelope against the EU TRACES acceptance environment (never production), which catches opaque server-side rejections the local rules can't predict.

mode: "validate" — a dry run as a task. Accepts the same editable blocks as submit and runs the same local gate, then returns 202 with a dds_record_task (operation validate). The task plans every TRACES statement the filing would need, checks each against acceptance (filed under a PF-… reference and withdrawn again), and files nothing. It does not lock the version. When it completes, result.traces_preflight holds the verdict:

{ "status": "accepted", "checked_at": "2026-10-06T…", "statement_count": 2, "errors": [] }

• accepted — every statement passed acceptance; a submit should file.
• rejected — a business-rules fault; errors[] carry the TRACES code and field detail.
• unverified — acceptance could not give an authoritative answer. Never a silent green.

One DDS task runs per record: a repeated validate returns the running validation; a validate during a submit (or the reverse) is a 409.

Enforcement on mode: "submit" — the submit request no longer runs the check; it returns 202 and the submit task runs it. The task plans every TRACES statement the filing needs and checks each one against acceptance (filed under a separate PF-… internal reference and withdrawn again). It files nothing to the real target unless every statement is accepted. A rejection, or an acceptance environment that cannot answer, fails the task with nothing filed; the task's error_message and traces_fault say which statement and why. The only case the check cannot cover is the real target rejecting a statement acceptance accepted: the task then fails with fm-api:FilingRejectedAfterPreflight, the version stays locked, and a later submit files the rest.

The last verdict is surfaced read-only on Get Audit Record Summary as meta.submission.submit.traces_preflight, and is refreshed proactively by a Update DDS Record that leaves the record submit-ready (best-effort — never fails the PATCH).

Body is optional — bare POST with no body defaults to mode: submit. The 202 response carries a dds_record_task with operation: "submit" and status: "pending". Poll GET /dds/:recordId/tasks/:taskId to watch progress.

"result": {
  "version_id": "<uuid>",
  "version_number": 2,
  "traces_reference_number": "DLE25/12345",
  "traces_verification_number": "ABC123",
  "traces_dds_uuid": "<uuid|null>",
  "submitted_at": "..."
}

Body fields:

Records the result inline (no SOAP), emits a version.marked_submitted event in the audit log (distinct from version.submitted so the trail tells you whether TRACES was actually hit by fm-api or filed externally), and returns 200 with the submission envelope.

Before claiming the version, the handler runs the pre-submission gate. Any blocker → 422 PRE_SUBMISSION_BLOCKED with the failing checks in details.blockers[]:

This is the same findPreSubmissionBlockers gate that the audit-trail record summary surfaces per filing mode in meta.submission.submit.blockers / meta.submission.submit.can_submit (and the manual counterpart), so the summary predicts the submit outcome. The operator / country checks that used to be separate synchronous 400s are now uniform blockers here (all 422 PRE_SUBMISSION_BLOCKED):

Coffee policy note: TRACES acceptance accepts bare 0901 (IMPORT and EXPORT re-probed on 2026-10-19), and Epoch now accepts the bare heading alongside its five subheadings. Production has not been verified. The examples show current fm-api behaviour, including blocker messages for codes that remain unsupported.

Example body for the authorization_missing case:

{
  "data": {
    "error": "DDS submission blocked by pre-flight checks",
    "code": "PRE_SUBMISSION_BLOCKED",
    "tracking_id": "...",
    "details": {
      "blockers": [
        {
          "type": "authorization_missing",
          "text_version": "v2",
          "message": "§9 step 3 requires the operator to authorise Epoch to submit on their behalf; POST /authorisations with the current text_version before submitting"
        }
      ]
    }
  }
}

To clear it: POST to Authorisations with { confirmed: true, text_version: "v2" } (plus an optional signee name), then retry the submit.

A DDS submission files only the compliant supply base. Before the gate above runs, the handler automatically excludes every included plot whose effective compliance verdict is non_compliant (an alert-derived non-compliance, or an operator override to non_compliant). Those plots drop out of the filing rather than blocking it — so plots_non_compliant is not a submit blocker. Each auto-exclusion is recorded in the audit log (config.exclusion_added, source: "system") and the excluded plots remain visible in the record's excluded set and the audit-trail PDF appendix.

An operator override to compliant (via a plot justification) keeps that plot in the filing. If auto-exclusion leaves zero compliant plots, the submit is rejected with 422 PRE_SUBMISSION_BLOCKED ("No compliant plots to file …") — override a plot to compliant, or add compliant plots, then retry.

The editable submission metadata (activity type, country of activity, internal reference number, geolocation-confidential, comment) is finalised on this request (see "One-call submit" above). The write-once identity field — operator role — is set at create; this endpoint also checks (mode: "submit") that an Authorisation exists.

TRACES requires countryOfActivity (and, for cross-border movements, borderCrossCountry) on every DDS. Both must be one of EU-27 or XI (Northern Ireland under the Windsor Framework); any other value is rejected before the SOAP call is made.

The submit flow derives the two fields from the version's submission metadata per the EUDR Validation Rules v1.3:

The producer/plot country (the record's top-level country_code — e.g. GH for Ghanaian cocoa) is never the activity country; that's the country of production, not of the EU diligence activity.

{
  "code": "fm-api:InvalidCountryOfActivity",
  "message": "countryOfActivity US is not in the TRACES-accepted set (EU-27 + XI)",
  "details": [
    {
      "field": "countryOfActivity",
      "message": "Country US is not accepted by TRACES; must be one of EU-27 or XI (Northern Ireland)"
    }
  ]
}

Required scope: eudr:write