Validate one e-invoice XML document

Validates a single UBL Invoice or CreditNote document synchronously and returns a ValidationVerdict.

Body. Send the raw XML as the request body with Content-Type: application/xml or text/xml, choosing the ruleset with the query parameters. Or send multipart/form-data with a document part holding the XML and an optional options part holding a JSON ValidationOptions object; query parameters are not read for multipart requests. The multipart form is the one to use from browsers and low-code tools.

Strictness. For raw XML bodies, a query parameter that is repeated or not one of ruleset, profile and document_type is 400 malformed_request, so a misspelt selector cannot silently fall back to a default. For multipart bodies, exactly one document part (an XML media type) and at most one options part (application/json) are accepted; a repeated or unknown part is 400 malformed_request. A Content-Encoding other than identity is 415 unsupported_content_type.

Correlation. Every response carries X-Ironfang-Request-ID, Ironfang's id for the request, which every Problem repeats as request_id. Send your own X-Request-ID and it is echoed back unchanged.

Limits. The XML is at most 5 MiB (5,242,880 bytes), 64 levels deep and 250,000 elements. Archives and compressed bodies (Content-Encoding other than identity, ZIP, gzip) are refused with 415 unsupported_content_type; a larger body with 413 payload_too_large. The validation deadline is 10 seconds; a validation that exceeds it is indeterminate (504).

Ruleset selection. ruleset is either the keyword latest or an exact immutable ruleset id (fwrs_...).

• latest resolves to the currently sendable release for the document's profile family at the moment of the request. With a profile, the result reports selection_method: latest; without one, the family is detected from the document's CustomizationID and ProfileID and the result reports selection_method: detected. Detection is for validation only; it is never a statement about what the document should be. A document whose profile cannot be detected - including XML that does not parse - is 422 profile_undetected; name a profile or an exact ruleset to obtain a verdict on it.
• An exact id validates against that release whatever its state among scheduled (migration testing), sendable (current) and historical (audit and reproduction). The result reports selection_method: exact and the release's state. An id that is unknown - or names an internal candidate, which is indistinguishable from unknown - is 422 unknown_ruleset; a withdrawn release is 410 ruleset_disabled.

The result always names the resolved immutable id in ruleset.id.

Outcome versus status. The result separates how far execution got (status) from what the standard concluded (outcome). A document that fails the standard at any layer - including malformed XML at the xml layer - is a successfully processed validation: HTTP 200 with outcome: invalid, and every deeper layer that could not run is reported as skipped, never omitted. Only the request itself being wrong, or Ironfang Finance being unable to decide, produces a Problem.

Idempotency. Authenticated requests may send an Idempotency-Key (8-128 characters of A-Z a-z 0-9 _ -). The key is scoped to the organisation and the validation endpoint. Replaying the same request with the same key returns the original operation and its result - the same operation_id, no second execution, no second charge - even if latest has since come to mean a newer release. A request is identified by its content: reusing a key with different document bytes (a different input SHA-256) or a different ruleset, profile or document type is 409 idempotency_conflict. Requests without a key always create a new operation. Anonymous requests do not use the header.

Findings. At most 1,000 findings are returned inline, in deterministic order: layer order, then severity (fatal before warning), then rule_id, then location, then message. findings_summary always states how many were returned, how many exist, the cap, and whether truncation happened.