Validate one invoice, as XML or as a PDF with embedded invoice XML

Body. Send the document itself with Content-Type application/xml, text/xml or application/pdf, choosing with the query parameters. Or send multipart/form-data with one document part (one of those media types) and an optional options part holding a JSON ValidationOptions object; query parameters are not read for multipart requests. The media type is a hint: the content is inspected, and an XML part holding a PDF (or the reverse) is 415 unsupported_content_type. Archives and compressed bodies are refused the same way.

Limits. XML at most 5 MiB (5,242,880 bytes), 64 levels deep, 250,000 elements. PDF at most 20 MiB, 200 pages and 20 embedded files; the embedded invoice XML at most 5 MiB; 25 MiB of decoded attachment data in total; 256 MiB of compressed (Flate) content decoded across the whole PDF. Over a byte limit is 413; over any other processing limit is 422 processing_limit, which is not a verdict on the invoice. The XML deadline is 10 seconds and the hybrid deadline 30 seconds; exceeding it is indeterminate (504).

Selection. ruleset is latest (default) or an exact ruleset id.

• With an exact id, the release supplies family, variant, syntax, document type and scope. Any selector also sent must equal the release's value, or the request is 422 selection_conflict; the document must fit the release (422 unsupported_document_type, 422 family_mismatch).
• With latest, the family is the one requested or, without family, the one the document declares (selection_method: detected); an undeclared or unknown family is 422 family_undetected. A requested family the document contradicts is 422 family_mismatch, and the Problem's detected says what the document declares, so a client can offer the right tool; the document is never validated under the wrong family. The variant is the one the document declares; a variant Ironfang recognises but does not validate is 422 unsupported_variant, never a fallback to a weaker profile.
• scope defaults to xml for XML and hybrid_pdf for a PDF. Any other combination is 422 scope_unavailable. To inspect only the XML inside a PDF, extract it explicitly (POST /tools/v2/invoice/extract) and validate that XML.

PDF inputs. An encrypted PDF is 422 encrypted_pdf. A PDF with no identifiable embedded invoice XML is 422 no_embedded_invoice, and one with more than one plausible invoice XML is 422 ambiguous_embedded_invoice: no attachment is ever chosen arbitrarily. These three are uncharged. Everything wrong with an identified embedded invoice - its name, relationship, media type, metadata, PDF/A conformance, or the XML itself - is a finding in a completed validation.

Outcome. 200 is always a verdict: status: completed, outcome valid or invalid, and every check that ran completed. A deterministic defect makes the outcome invalid, and checks it prevented are skipped with a reason. A timeout, an unavailable validator or an internal failure is a Problem with outcome: indeterminate; known findings are never presented as a verdict.

Usage. One completed validation is one operation, whatever the scope; the checks inside it are not billed separately. As in V1, a completed validation is charged once its schema check (xsd) reached a verdict, passed or failed; a document that is not well-formed XML ends before it and is not charged. Rejected requests and indeterminate outcomes are not charged. An authenticated verdict carries operation_id and usage, and is retained for 30 days as V1 results are; it is served only through V2, never through a V1 result, list or report.

Idempotency. As V1, with the request identified by the input bytes (for a PDF, the PDF's own bytes), the selectors and the scope. A replay returns the original operation and its result, even if latest has since moved.

Findings. At most 1,000 inline, ordered by the pipeline's layer order, then severity (fatal, warning, information), then rule_id, then location, then message. findings_summary states the totals and whether truncation happened.