{ "auth": { "bearer": [ { "key": "token", "type": "string", "value": "{{IRONFANG_API_KEY}}" } ], "type": "bearer" }, "info": { "description": "V2 validates an e-invoice against the exact, immutable ruleset of its\nfamily and reports precisely what was checked. It exists beside V1,\nwhich is unchanged: V1 clients keep their Peppol-only shapes, and a V2\nresult is never returned through a V1 route.\n\n**Families.** `xrechnung` (the German CIUS of EN 16931, in UBL or\nUN/CEFACT CII), `zugferd-facturx` (the shared ZUGFeRD / Factur-X\nimplementation, as CII XML or embedded in a PDF/A-3) and\n`peppol-bis-billing-3`. ZUGFeRD and Factur-X are corresponding release\nnames of one standard, validated once. `GET /v2/einvoices/rulesets` lists\nexactly which family, variant, syntax, document type and scope each\nactive release covers; nothing else is supported.\n\n**Scope.** An XML body is checked at `xml` scope: the invoice XML\nagainst its schema and rules. A PDF body is checked at `hybrid_pdf`\nscope: PDF/A-3 conformance, the invoice attachment and its metadata,\nand the embedded invoice XML, each reported separately. A PDF is never\nsilently checked as XML only, and XML success never reads as a complete\nhybrid check. `coverage` lists what was not checked: a PDF that was not\nsupplied, the visual PDF content against the XML (never compared), and\ndigital signatures (never verified).\n\n**Reduced profiles.** ZUGFeRD / Factur-X MINIMUM and BASIC WL are not\nfull EN 16931 invoices. A pass against them is a pass against that\nprofile's rules, and `coverage` says the EN 16931 semantic model was not\nestablished.\n\n**What a result is not.** Validation does not transmit invoices,\ncertify legal or tax compliance, or guarantee acceptance by a recipient\nor a submission portal. Documents are never corrected.\n\n**Authentication, anonymous use, idempotency and retention** follow V1:\nIronfang platform API keys (`Authorization: Bearer`), anonymous\nvalidation with nothing stored and tighter rate limits, optional\n`Idempotency-Key` on authenticated requests, 30-day retained results.\nUploaded XML or PDF bytes are not stored by synchronous validation.\n\n**Durable jobs.** `POST /v2/einvoices/jobs` queues one validation and\n`POST /v2/einvoices/batches` 1 to 100 together, each document base64 in\nJSON. Everything synchronous validation decides before it validates is\ndecided when a job is accepted, so a document it would refuse is\nrefused then, and nothing is queued or charged. An accepted job's\ndocument is held encrypted until it finishes, at most 24 hours. Its\nresult, usage and webhook or S3 event are exactly a synchronous\nvalidation's.\n\n**Problems.** Every error is an RFC 9457 Problem\n(`application/problem+json`); branch on `code`:\n\n| code | status | meaning |\n| --- | --- | --- |\n| `malformed_request` | 400 | The request is malformed: an unknown or repeated parameter or part, an invalid value, or a body that is not one document. |\n| `unauthenticated` | 401 | The credential is missing, malformed, unknown or revoked. |\n| `paid_usage_paused` | 402 | Paid usage is paused for the billing account and the free allowance is used up. |\n| `payment_required` | 402 | Paid usage needs a working payment method. |\n| `payment_action_required` | 402 | A payment needs the account holder's confirmation before paid usage continues. |\n| `account_restricted` | 402 | Paid usage is restricted on the billing account. |\n| `product_not_eligible` | 403 | Paid Ironfang Finance usage needs an approved business; the free allowance is used up. |\n| `insufficient_scope` | 403 | The key lacks the scope this operation needs. |\n| `not_found` | 404 | No such resource is visible to the caller. |\n| `idempotency_conflict` | 409 | The Idempotency-Key was used for a different request. |\n| `ruleset_disabled` | 410 | The ruleset was withdrawn from every use. |\n| `account_closed` | 410 | The billing account is closed. |\n| `result_gone` | 410 | The original result behind this Idempotency-Key has expired or was deleted; nothing was run again. |\n| `payload_too_large` | 413 | The body is over the published limit for its media type. |\n| `unsupported_content_type` | 415 | The body's media type, encoding or content is not one this operation accepts. |\n| `unknown_ruleset` | 422 | The ruleset id names no release that can be validated against, or no current release exists for the selection. |\n| `selection_conflict` | 422 | The selectors disagree with each other or with the named ruleset. |\n| `family_undetected` | 422 | The document declares no family Ironfang recognises; name a family or an exact ruleset. |\n| `family_mismatch` | 422 | The document declares a different family from the one requested. |\n| `unsupported_variant` | 422 | The document declares a variant or profile Ironfang recognises but does not validate yet. |\n| `unsupported_document_type` | 422 | The document type is not one the selected ruleset validates, or it contradicts the document. |\n| `scope_unavailable` | 422 | The requested scope cannot be checked with this input, such as hybrid scope for an XML body or XML scope for a PDF. |\n| `no_embedded_invoice` | 422 | The PDF carries no embedded invoice XML Ironfang could identify. |\n| `ambiguous_embedded_invoice` | 422 | The PDF carries more than one plausible invoice XML; none was chosen. |\n| `encrypted_pdf` | 422 | The PDF is encrypted or password-protected. |\n| `processing_limit` | 422 | The document is over a published processing limit (pages, attachments, decoded size); this is not a verdict on the invoice. |\n| `rate_limited` | 429 | Too many requests from this caller. |\n| `free_allowance_exhausted` | 429 | This month's free allowance is used up and paid usage is not enabled. |\n| `account_budget_exhausted` | 429 | The billing account's monthly usage limit is reached. |\n| `product_budget_exhausted` | 429 | The monthly usage limit for Ironfang Finance is reached. |\n| `exemption_limit_reached` | 429 | The account's agreed monthly limit is reached. |\n| `quota_exhausted` | 429 | The organisation's queue of unfinished jobs is full (job and batch submission). |\n| `internal_error` | 500 | Ironfang Finance failed while processing the request. |\n| `validator_unavailable` | 503 | The validator for the selected ruleset is not available. |\n| `delivery_unavailable` | 503 | Destination delivery is not configured (delivery retry). |\n| `jobs_unavailable` | 503 | Durable jobs are not configured on this deployment (job and batch submission). |\n| `billing_temporarily_unavailable` | 503 | Billing is briefly unavailable; retry shortly. |\n| `report_incomplete` | 422 | The retained result's findings were truncated, so no complete signed report can be issued. |\n| `report_unavailable` | 503 | Signed report issuance is not configured, or a readable PDF was asked for a result that has none. |\n| `validation_timeout` | 504 | Validation did not finish within the deadline. |\n\n`validator_unavailable`, `validation_timeout` and, on validation,\n`internal_error` are indeterminate: they carry `outcome: indeterminate`\nand `usage_charged: false`, and nothing is billed.\n\nGenerated from info.version 2.0.0. Start with the Getting started folder: its requests need no credential. For everything else set IRONFANG_API_KEY in a private Postman environment or vault reference; no credential is included in this collection. Validation takes the XML or PDF itself: select the file in Body and set media_type to application/xml or application/pdf. Jobs and batches take the document base64-encoded in document_base64. Supply path variables before sending. DELETE permanently deletes a retained result. Do not export credentials.", "name": "Ironfang Finance E-Invoicing API V2", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "description": "Three anonymous requests that work from a fresh fork with nothing configured. Run them in order. Nothing here needs an API key; the folders below do.", "item": [ { "name": "1. List the V2 rulesets", "request": { "auth": { "type": "noauth" }, "description": "Lists every release V2 validates against: Peppol BIS Billing 3, XRechnung and ZUGFeRD / Factur-X, each with its family, variant, syntax and scope (xml, or hybrid_pdf for a PDF with its embedded XML). It needs no credential. `ruleset=latest` resolves to the sendable release that fits your document.", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "rulesets" ], "query": [], "raw": "{{base_url}}/v2/einvoices/rulesets" } }, "response": [] }, { "name": "2. Validate an XRechnung invoice", "request": { "auth": { "type": "noauth" }, "body": { "mode": "raw", "options": { "raw": { "language": "xml" } }, "raw": "\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!--\n A fictional XRechnung 3.0 invoice in UBL, published by Ironfang for the\n free XRechnung tools at https://ironfang.uk/tools/xrechnung-validator and\n https://ironfang.uk/tools/xrechnung-viewer. Every party, identifier,\n address, account and amount is invented: example.test addresses, the VAT\n identifier DE000000000, and an IBAN whose bank code 00000000 belongs to no\n bank. The same invoice is published in CII as\n xrechnung-3-0-cii-invoice-v1.xml. Reuse it freely.\n--\u003e\n\u003cInvoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\"\n xmlns:cac=\"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2\"\n xmlns:cbc=\"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2\"\u003e\n \u003ccbc:CustomizationID\u003eurn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0\u003c/cbc:CustomizationID\u003e\n \u003ccbc:ProfileID\u003eurn:fdc:peppol.eu:2017:poacc:billing:01:1.0\u003c/cbc:ProfileID\u003e\n \u003ccbc:ID\u003eXR-2026-0001\u003c/cbc:ID\u003e\n \u003ccbc:IssueDate\u003e2026-09-15\u003c/cbc:IssueDate\u003e\n \u003ccbc:DueDate\u003e2026-10-15\u003c/cbc:DueDate\u003e\n \u003ccbc:InvoiceTypeCode\u003e380\u003c/cbc:InvoiceTypeCode\u003e\n \u003ccbc:Note\u003eFiktive Beispielrechnung für die XRechnung-Werkzeuge von Ironfang.\u003c/cbc:Note\u003e\n \u003ccbc:DocumentCurrencyCode\u003eEUR\u003c/cbc:DocumentCurrencyCode\u003e\n \u003ccbc:BuyerReference\u003e04011000-12345-67\u003c/cbc:BuyerReference\u003e\n \u003ccac:AccountingSupplierParty\u003e\n \u003ccac:Party\u003e\n \u003ccbc:EndpointID schemeID=\"EM\"\u003erechnung@beispiel-technik.example.test\u003c/cbc:EndpointID\u003e\n \u003ccac:PartyName\u003e\n \u003ccbc:Name\u003eBeispiel Technik\u003c/cbc:Name\u003e\n \u003c/cac:PartyName\u003e\n \u003ccac:PostalAddress\u003e\n \u003ccbc:StreetName\u003eMusterstraße 1\u003c/cbc:StreetName\u003e\n \u003ccbc:CityName\u003eBerlin\u003c/cbc:CityName\u003e\n \u003ccbc:PostalZone\u003e10115\u003c/cbc:PostalZone\u003e\n \u003ccac:Country\u003e\n \u003ccbc:IdentificationCode\u003eDE\u003c/cbc:IdentificationCode\u003e\n \u003c/cac:Country\u003e\n \u003c/cac:PostalAddress\u003e\n \u003ccac:PartyTaxScheme\u003e\n \u003ccbc:CompanyID\u003eDE000000000\u003c/cbc:CompanyID\u003e\n \u003ccac:TaxScheme\u003e\n \u003ccbc:ID\u003eVAT\u003c/cbc:ID\u003e\n \u003c/cac:TaxScheme\u003e\n \u003c/cac:PartyTaxScheme\u003e\n \u003ccac:PartyLegalEntity\u003e\n \u003ccbc:RegistrationName\u003eBeispiel Technik GmbH\u003c/cbc:RegistrationName\u003e\n \u003c/cac:PartyLegalEntity\u003e\n \u003ccac:Contact\u003e\n \u003ccbc:Name\u003eBuchhaltung\u003c/cbc:Name\u003e\n \u003ccbc:Telephone\u003e+49 30 0000000\u003c/cbc:Telephone\u003e\n \u003ccbc:ElectronicMail\u003ebuchhaltung@beispiel-technik.example.test\u003c/cbc:ElectronicMail\u003e\n \u003c/cac:Contact\u003e\n \u003c/cac:Party\u003e\n \u003c/cac:AccountingSupplierParty\u003e\n \u003ccac:AccountingCustomerParty\u003e\n \u003ccac:Party\u003e\n \u003ccbc:EndpointID schemeID=\"EM\"\u003eeingang@musterstadt.example.test\u003c/cbc:EndpointID\u003e\n \u003ccac:PostalAddress\u003e\n \u003ccbc:StreetName\u003eRathausplatz 5\u003c/cbc:StreetName\u003e\n \u003ccbc:CityName\u003eMusterstadt\u003c/cbc:CityName\u003e\n \u003ccbc:PostalZone\u003e12345\u003c/cbc:PostalZone\u003e\n \u003ccac:Country\u003e\n \u003ccbc:IdentificationCode\u003eDE\u003c/cbc:IdentificationCode\u003e\n \u003c/cac:Country\u003e\n \u003c/cac:PostalAddress\u003e\n \u003ccac:PartyLegalEntity\u003e\n \u003ccbc:RegistrationName\u003eStadtverwaltung Musterstadt\u003c/cbc:RegistrationName\u003e\n \u003c/cac:PartyLegalEntity\u003e\n \u003c/cac:Party\u003e\n \u003c/cac:AccountingCustomerParty\u003e\n \u003ccac:Delivery\u003e\n \u003ccbc:ActualDeliveryDate\u003e2026-09-12\u003c/cbc:ActualDeliveryDate\u003e\n \u003c/cac:Delivery\u003e\n \u003ccac:PaymentMeans\u003e\n \u003ccbc:PaymentMeansCode\u003e58\u003c/cbc:PaymentMeansCode\u003e\n \u003ccbc:PaymentID\u003eXR-2026-0001\u003c/cbc:PaymentID\u003e\n \u003ccac:PayeeFinancialAccount\u003e\n \u003ccbc:ID\u003eDE52000000000012345678\u003c/cbc:ID\u003e\n \u003ccbc:Name\u003eBeispiel Technik GmbH\u003c/cbc:Name\u003e\n \u003c/cac:PayeeFinancialAccount\u003e\n \u003c/cac:PaymentMeans\u003e\n \u003ccac:PaymentTerms\u003e\n \u003ccbc:Note\u003eZahlbar innerhalb von 30 Tagen ohne Abzug.\u003c/cbc:Note\u003e\n \u003c/cac:PaymentTerms\u003e\n \u003ccac:TaxTotal\u003e\n \u003ccbc:TaxAmount currencyID=\"EUR\"\u003e190.00\u003c/cbc:TaxAmount\u003e\n \u003ccac:TaxSubtotal\u003e\n \u003ccbc:TaxableAmount currencyID=\"EUR\"\u003e1000.00\u003c/cbc:TaxableAmount\u003e\n \u003ccbc:TaxAmount currencyID=\"EUR\"\u003e190.00\u003c/cbc:TaxAmount\u003e\n \u003ccac:TaxCategory\u003e\n \u003ccbc:ID\u003eS\u003c/cbc:ID\u003e\n \u003ccbc:Percent\u003e19\u003c/cbc:Percent\u003e\n \u003ccac:TaxScheme\u003e\n \u003ccbc:ID\u003eVAT\u003c/cbc:ID\u003e\n \u003c/cac:TaxScheme\u003e\n \u003c/cac:TaxCategory\u003e\n \u003c/cac:TaxSubtotal\u003e\n \u003c/cac:TaxTotal\u003e\n \u003ccac:LegalMonetaryTotal\u003e\n \u003ccbc:LineExtensionAmount currencyID=\"EUR\"\u003e1000.00\u003c/cbc:LineExtensionAmount\u003e\n \u003ccbc:TaxExclusiveAmount currencyID=\"EUR\"\u003e1000.00\u003c/cbc:TaxExclusiveAmount\u003e\n \u003ccbc:TaxInclusiveAmount currencyID=\"EUR\"\u003e1190.00\u003c/cbc:TaxInclusiveAmount\u003e\n \u003ccbc:PayableAmount currencyID=\"EUR\"\u003e1190.00\u003c/cbc:PayableAmount\u003e\n \u003c/cac:LegalMonetaryTotal\u003e\n \u003ccac:InvoiceLine\u003e\n \u003ccbc:ID\u003e1\u003c/cbc:ID\u003e\n \u003ccbc:InvoicedQuantity unitCode=\"HUR\"\u003e8\u003c/cbc:InvoicedQuantity\u003e\n \u003ccbc:LineExtensionAmount currencyID=\"EUR\"\u003e760.00\u003c/cbc:LineExtensionAmount\u003e\n \u003ccac:Item\u003e\n \u003ccbc:Name\u003eBeratung Datenmigration\u003c/cbc:Name\u003e\n \u003ccac:ClassifiedTaxCategory\u003e\n \u003ccbc:ID\u003eS\u003c/cbc:ID\u003e\n \u003ccbc:Percent\u003e19\u003c/cbc:Percent\u003e\n \u003ccac:TaxScheme\u003e\n \u003ccbc:ID\u003eVAT\u003c/cbc:ID\u003e\n \u003c/cac:TaxScheme\u003e\n \u003c/cac:ClassifiedTaxCategory\u003e\n \u003c/cac:Item\u003e\n \u003ccac:Price\u003e\n \u003ccbc:PriceAmount currencyID=\"EUR\"\u003e95.00\u003c/cbc:PriceAmount\u003e\n \u003c/cac:Price\u003e\n \u003c/cac:InvoiceLine\u003e\n \u003ccac:InvoiceLine\u003e\n \u003ccbc:ID\u003e2\u003c/cbc:ID\u003e\n \u003ccbc:InvoicedQuantity unitCode=\"C62\"\u003e1\u003c/cbc:InvoicedQuantity\u003e\n \u003ccbc:LineExtensionAmount currencyID=\"EUR\"\u003e240.00\u003c/cbc:LineExtensionAmount\u003e\n \u003ccac:Item\u003e\n \u003ccbc:Name\u003eSoftwarelizenz, 12 Monate\u003c/cbc:Name\u003e\n \u003ccac:ClassifiedTaxCategory\u003e\n \u003ccbc:ID\u003eS\u003c/cbc:ID\u003e\n \u003ccbc:Percent\u003e19\u003c/cbc:Percent\u003e\n \u003ccac:TaxScheme\u003e\n \u003ccbc:ID\u003eVAT\u003c/cbc:ID\u003e\n \u003c/cac:TaxScheme\u003e\n \u003c/cac:ClassifiedTaxCategory\u003e\n \u003c/cac:Item\u003e\n \u003ccac:Price\u003e\n \u003ccbc:PriceAmount currencyID=\"EUR\"\u003e240.00\u003c/cbc:PriceAmount\u003e\n \u003c/cac:Price\u003e\n \u003c/cac:InvoiceLine\u003e\n\u003c/Invoice\u003e" }, "description": "Validates the XRechnung UBL invoice in the body. V2 detects the family from the document's own declaration, so no selector is needed; expect `outcome: valid` with the XRechnung release named in `ruleset`, and the layers and check groups it ran. The body is a fictional sample. Anonymous validation stores nothing.", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/xml" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "validate" ], "query": [], "raw": "{{base_url}}/v2/einvoices/validate" } }, "response": [] }, { "name": "3. Validate a ZUGFeRD / Factur-X invoice", "request": { "auth": { "type": "noauth" }, "body": { "mode": "raw", "options": { "raw": { "language": "xml" } }, "raw": "\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!--\n A fictional ZUGFeRD 2.5 / Factur-X 1.09 invoice in the EN 16931 profile\n (UN/CEFACT CII D22B), published by Ironfang for its free ZUGFeRD tools at\n https://ironfang.uk/tools/zugferd-validator. Every party, identifier,\n address, account and amount is invented: example.test addresses, the VAT\n identifier DE000000000, and an IBAN whose bank code 00000000 belongs to no\n bank. The same invoice is published as a hybrid PDF with this XML\n embedded as factur-x.xml. Reuse it freely.\n--\u003e\n\u003crsm:CrossIndustryInvoice xmlns:rsm=\"urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100\"\n xmlns:ram=\"urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100\"\n xmlns:udt=\"urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100\"\u003e\n \u003crsm:ExchangedDocumentContext\u003e\n \u003cram:BusinessProcessSpecifiedDocumentContextParameter\u003e\n \u003cram:ID\u003eurn:fdc:peppol.eu:2017:poacc:billing:01:1.0\u003c/ram:ID\u003e\n \u003c/ram:BusinessProcessSpecifiedDocumentContextParameter\u003e\n \u003cram:GuidelineSpecifiedDocumentContextParameter\u003e\n \u003cram:ID\u003eurn:cen.eu:en16931:2017\u003c/ram:ID\u003e\n \u003c/ram:GuidelineSpecifiedDocumentContextParameter\u003e\n \u003c/rsm:ExchangedDocumentContext\u003e\n \u003crsm:ExchangedDocument\u003e\n \u003cram:ID\u003eXR-2026-0001\u003c/ram:ID\u003e\n \u003cram:TypeCode\u003e380\u003c/ram:TypeCode\u003e\n \u003cram:IssueDateTime\u003e\n \u003cudt:DateTimeString format=\"102\"\u003e20260915\u003c/udt:DateTimeString\u003e\n \u003c/ram:IssueDateTime\u003e\n \u003cram:IncludedNote\u003e\n \u003cram:Content\u003eFiktive Beispielrechnung für die ZUGFeRD-Werkzeuge von Ironfang.\u003c/ram:Content\u003e\n \u003c/ram:IncludedNote\u003e\n \u003c/rsm:ExchangedDocument\u003e\n \u003crsm:SupplyChainTradeTransaction\u003e\n \u003cram:IncludedSupplyChainTradeLineItem\u003e\n \u003cram:AssociatedDocumentLineDocument\u003e\n \u003cram:LineID\u003e1\u003c/ram:LineID\u003e\n \u003c/ram:AssociatedDocumentLineDocument\u003e\n \u003cram:SpecifiedTradeProduct\u003e\n \u003cram:Name\u003eBeratung Datenmigration\u003c/ram:Name\u003e\n \u003c/ram:SpecifiedTradeProduct\u003e\n \u003cram:SpecifiedLineTradeAgreement\u003e\n \u003cram:NetPriceProductTradePrice\u003e\n \u003cram:ChargeAmount\u003e95.00\u003c/ram:ChargeAmount\u003e\n \u003c/ram:NetPriceProductTradePrice\u003e\n \u003c/ram:SpecifiedLineTradeAgreement\u003e\n \u003cram:SpecifiedLineTradeDelivery\u003e\n \u003cram:BilledQuantity unitCode=\"HUR\"\u003e8\u003c/ram:BilledQuantity\u003e\n \u003c/ram:SpecifiedLineTradeDelivery\u003e\n \u003cram:SpecifiedLineTradeSettlement\u003e\n \u003cram:ApplicableTradeTax\u003e\n \u003cram:TypeCode\u003eVAT\u003c/ram:TypeCode\u003e\n \u003cram:CategoryCode\u003eS\u003c/ram:CategoryCode\u003e\n \u003cram:RateApplicablePercent\u003e19\u003c/ram:RateApplicablePercent\u003e\n \u003c/ram:ApplicableTradeTax\u003e\n \u003cram:SpecifiedTradeSettlementLineMonetarySummation\u003e\n \u003cram:LineTotalAmount\u003e760.00\u003c/ram:LineTotalAmount\u003e\n \u003c/ram:SpecifiedTradeSettlementLineMonetarySummation\u003e\n \u003c/ram:SpecifiedLineTradeSettlement\u003e\n \u003c/ram:IncludedSupplyChainTradeLineItem\u003e\n \u003cram:IncludedSupplyChainTradeLineItem\u003e\n \u003cram:AssociatedDocumentLineDocument\u003e\n \u003cram:LineID\u003e2\u003c/ram:LineID\u003e\n \u003c/ram:AssociatedDocumentLineDocument\u003e\n \u003cram:SpecifiedTradeProduct\u003e\n \u003cram:Name\u003eSoftwarelizenz, 12 Monate\u003c/ram:Name\u003e\n \u003c/ram:SpecifiedTradeProduct\u003e\n \u003cram:SpecifiedLineTradeAgreement\u003e\n \u003cram:NetPriceProductTradePrice\u003e\n \u003cram:ChargeAmount\u003e240.00\u003c/ram:ChargeAmount\u003e\n \u003c/ram:NetPriceProductTradePrice\u003e\n \u003c/ram:SpecifiedLineTradeAgreement\u003e\n \u003cram:SpecifiedLineTradeDelivery\u003e\n \u003cram:BilledQuantity unitCode=\"C62\"\u003e1\u003c/ram:BilledQuantity\u003e\n \u003c/ram:SpecifiedLineTradeDelivery\u003e\n \u003cram:SpecifiedLineTradeSettlement\u003e\n \u003cram:ApplicableTradeTax\u003e\n \u003cram:TypeCode\u003eVAT\u003c/ram:TypeCode\u003e\n \u003cram:CategoryCode\u003eS\u003c/ram:CategoryCode\u003e\n \u003cram:RateApplicablePercent\u003e19\u003c/ram:RateApplicablePercent\u003e\n \u003c/ram:ApplicableTradeTax\u003e\n \u003cram:SpecifiedTradeSettlementLineMonetarySummation\u003e\n \u003cram:LineTotalAmount\u003e240.00\u003c/ram:LineTotalAmount\u003e\n \u003c/ram:SpecifiedTradeSettlementLineMonetarySummation\u003e\n \u003c/ram:SpecifiedLineTradeSettlement\u003e\n \u003c/ram:IncludedSupplyChainTradeLineItem\u003e\n \u003cram:ApplicableHeaderTradeAgreement\u003e\n \u003cram:BuyerReference\u003e04011000-12345-67\u003c/ram:BuyerReference\u003e\n \u003cram:SellerTradeParty\u003e\n \u003cram:Name\u003eBeispiel Technik GmbH\u003c/ram:Name\u003e\n \u003cram:SpecifiedLegalOrganization\u003e\n \u003cram:TradingBusinessName\u003eBeispiel Technik\u003c/ram:TradingBusinessName\u003e\n \u003c/ram:SpecifiedLegalOrganization\u003e\n \u003cram:DefinedTradeContact\u003e\n \u003cram:PersonName\u003eBuchhaltung\u003c/ram:PersonName\u003e\n \u003cram:TelephoneUniversalCommunication\u003e\n \u003cram:CompleteNumber\u003e+49 30 0000000\u003c/ram:CompleteNumber\u003e\n \u003c/ram:TelephoneUniversalCommunication\u003e\n \u003cram:EmailURIUniversalCommunication\u003e\n \u003cram:URIID\u003ebuchhaltung@beispiel-technik.example.test\u003c/ram:URIID\u003e\n \u003c/ram:EmailURIUniversalCommunication\u003e\n \u003c/ram:DefinedTradeContact\u003e\n \u003cram:PostalTradeAddress\u003e\n \u003cram:PostcodeCode\u003e10115\u003c/ram:PostcodeCode\u003e\n \u003cram:LineOne\u003eMusterstraße 1\u003c/ram:LineOne\u003e\n \u003cram:CityName\u003eBerlin\u003c/ram:CityName\u003e\n \u003cram:CountryID\u003eDE\u003c/ram:CountryID\u003e\n \u003c/ram:PostalTradeAddress\u003e\n \u003cram:URIUniversalCommunication\u003e\n \u003cram:URIID schemeID=\"EM\"\u003erechnung@beispiel-technik.example.test\u003c/ram:URIID\u003e\n \u003c/ram:URIUniversalCommunication\u003e\n \u003cram:SpecifiedTaxRegistration\u003e\n \u003cram:ID schemeID=\"VA\"\u003eDE000000000\u003c/ram:ID\u003e\n \u003c/ram:SpecifiedTaxRegistration\u003e\n \u003c/ram:SellerTradeParty\u003e\n \u003cram:BuyerTradeParty\u003e\n \u003cram:Name\u003eStadtverwaltung Musterstadt\u003c/ram:Name\u003e\n \u003cram:PostalTradeAddress\u003e\n \u003cram:PostcodeCode\u003e12345\u003c/ram:PostcodeCode\u003e\n \u003cram:LineOne\u003eRathausplatz 5\u003c/ram:LineOne\u003e\n \u003cram:CityName\u003eMusterstadt\u003c/ram:CityName\u003e\n \u003cram:CountryID\u003eDE\u003c/ram:CountryID\u003e\n \u003c/ram:PostalTradeAddress\u003e\n \u003cram:URIUniversalCommunication\u003e\n \u003cram:URIID schemeID=\"EM\"\u003eeingang@musterstadt.example.test\u003c/ram:URIID\u003e\n \u003c/ram:URIUniversalCommunication\u003e\n \u003c/ram:BuyerTradeParty\u003e\n \u003c/ram:ApplicableHeaderTradeAgreement\u003e\n \u003cram:ApplicableHeaderTradeDelivery\u003e\n \u003cram:ActualDeliverySupplyChainEvent\u003e\n \u003cram:OccurrenceDateTime\u003e\n \u003cudt:DateTimeString format=\"102\"\u003e20260912\u003c/udt:DateTimeString\u003e\n \u003c/ram:OccurrenceDateTime\u003e\n \u003c/ram:ActualDeliverySupplyChainEvent\u003e\n \u003c/ram:ApplicableHeaderTradeDelivery\u003e\n \u003cram:ApplicableHeaderTradeSettlement\u003e\n \u003cram:PaymentReference\u003eXR-2026-0001\u003c/ram:PaymentReference\u003e\n \u003cram:InvoiceCurrencyCode\u003eEUR\u003c/ram:InvoiceCurrencyCode\u003e\n \u003cram:SpecifiedTradeSettlementPaymentMeans\u003e\n \u003cram:TypeCode\u003e58\u003c/ram:TypeCode\u003e\n \u003cram:PayeePartyCreditorFinancialAccount\u003e\n \u003cram:IBANID\u003eDE52000000000012345678\u003c/ram:IBANID\u003e\n \u003cram:AccountName\u003eBeispiel Technik GmbH\u003c/ram:AccountName\u003e\n \u003c/ram:PayeePartyCreditorFinancialAccount\u003e\n \u003c/ram:SpecifiedTradeSettlementPaymentMeans\u003e\n \u003cram:ApplicableTradeTax\u003e\n \u003cram:CalculatedAmount\u003e190.00\u003c/ram:CalculatedAmount\u003e\n \u003cram:TypeCode\u003eVAT\u003c/ram:TypeCode\u003e\n \u003cram:BasisAmount\u003e1000.00\u003c/ram:BasisAmount\u003e\n \u003cram:CategoryCode\u003eS\u003c/ram:CategoryCode\u003e\n \u003cram:RateApplicablePercent\u003e19\u003c/ram:RateApplicablePercent\u003e\n \u003c/ram:ApplicableTradeTax\u003e\n \u003cram:SpecifiedTradePaymentTerms\u003e\n \u003cram:Description\u003eZahlbar innerhalb von 30 Tagen ohne Abzug.\u003c/ram:Description\u003e\n \u003cram:DueDateDateTime\u003e\n \u003cudt:DateTimeString format=\"102\"\u003e20261015\u003c/udt:DateTimeString\u003e\n \u003c/ram:DueDateDateTime\u003e\n \u003c/ram:SpecifiedTradePaymentTerms\u003e\n \u003cram:SpecifiedTradeSettlementHeaderMonetarySummation\u003e\n \u003cram:LineTotalAmount\u003e1000.00\u003c/ram:LineTotalAmount\u003e\n \u003cram:TaxBasisTotalAmount\u003e1000.00\u003c/ram:TaxBasisTotalAmount\u003e\n \u003cram:TaxTotalAmount currencyID=\"EUR\"\u003e190.00\u003c/ram:TaxTotalAmount\u003e\n \u003cram:GrandTotalAmount\u003e1190.00\u003c/ram:GrandTotalAmount\u003e\n \u003cram:DuePayableAmount\u003e1190.00\u003c/ram:DuePayableAmount\u003e\n \u003c/ram:SpecifiedTradeSettlementHeaderMonetarySummation\u003e\n \u003c/ram:ApplicableHeaderTradeSettlement\u003e\n \u003c/rsm:SupplyChainTradeTransaction\u003e\n\u003c/rsm:CrossIndustryInvoice\u003e" }, "description": "Validates the ZUGFeRD / Factur-X EN 16931 invoice XML in the body, detected from its guideline identifier. For the PDF with this XML embedded, use Validation in the reference folders with media_type application/pdf: the PDF/A, the attachment metadata and the XML are then checked together. The body is a fictional sample.", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/xml" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "validate" ], "query": [], "raw": "{{base_url}}/v2/einvoices/validate" } }, "response": [] } ], "name": "Getting started" }, { "description": "Validate one invoice, XML or PDF.", "item": [ { "name": "Validate one invoice, as XML or as a PDF with embedded invoice XML", "request": { "body": { "file": { "src": "" }, "mode": "file" }, "description": "**Body.** Send the document itself with `Content-Type`\n`application/xml`, `text/xml` or `application/pdf`, choosing with the\nquery parameters. Or send `multipart/form-data` with one `document`\npart (one of those media types) and an optional `options` part\nholding a JSON `ValidationOptions` object; query parameters are not\nread for multipart requests. The media type is a hint: the content\nis inspected, and an XML part holding a PDF (or the reverse) is\n`415 unsupported_content_type`. Archives and compressed bodies are\nrefused the same way.\n\n**Limits.** XML at most 5 MiB (5,242,880 bytes), 64 levels deep,\n250,000 elements. PDF at most 20 MiB, 200 pages and 20 embedded\nfiles; the embedded invoice XML at most 5 MiB; 25 MiB of decoded\nattachment data in total; 256 MiB of compressed (Flate) content\ndecoded across the whole PDF. Over a byte limit is `413`; over any other\nprocessing limit is `422 processing_limit`, which is not a verdict on\nthe invoice. The XML deadline is 10 seconds and the hybrid deadline\n30 seconds; exceeding it is indeterminate (`504`).\n\n**Selection.** `ruleset` is `latest` (default) or an exact ruleset\nid.\n\n- With an exact id, the release supplies family, variant, syntax,\n document type and scope. Any selector also sent must equal the\n release's value, or the request is `422 selection_conflict`; the\n document must fit the release (`422 unsupported_document_type`,\n `422 family_mismatch`).\n- With `latest`, the family is the one requested or, without\n `family`, the one the document declares\n (`selection_method: detected`); an undeclared or unknown family is\n `422 family_undetected`. A requested family the document\n contradicts is `422 family_mismatch`, and the Problem's\n `detected` says what the document declares, so a client can offer\n the right tool; the document is never validated under the wrong\n family. The variant is the one the document declares; a variant\n Ironfang recognises but does not validate is\n `422 unsupported_variant`, never a fallback to a weaker profile.\n- `scope` defaults to `xml` for XML and `hybrid_pdf` for a PDF.\n Any other combination is `422 scope_unavailable`. To inspect only\n the XML inside a PDF, extract it explicitly\n (`POST /tools/v2/invoice/extract`) and validate that XML.\n\n**PDF inputs.** An encrypted PDF is `422 encrypted_pdf`. A PDF with\nno identifiable embedded invoice XML is `422 no_embedded_invoice`,\nand one with more than one plausible invoice XML is\n`422 ambiguous_embedded_invoice`: no attachment is ever chosen\narbitrarily. These three are uncharged. Everything wrong with an\nidentified embedded invoice - its name, relationship, media type,\nmetadata, PDF/A conformance, or the XML itself - is a finding in a\ncompleted validation.\n\n**Outcome.** `200` is always a verdict: `status: completed`,\n`outcome` `valid` or `invalid`, and every check that ran completed.\nA deterministic defect makes the outcome `invalid`, and checks it\nprevented are `skipped` with a reason. A timeout, an unavailable\nvalidator or an internal failure is a Problem with\n`outcome: indeterminate`; known findings are never presented as a\nverdict.\n\n**Usage.** One completed validation is one operation, whatever the\nscope; the checks inside it are not billed separately. As in V1, a\ncompleted validation is charged once its schema check (`xsd`)\nreached a verdict, passed or failed; a document that is not\nwell-formed XML ends before it and is not charged. Rejected\nrequests and indeterminate outcomes are not charged. An\nauthenticated verdict carries `operation_id` and `usage`, and is\nretained for 30 days as V1 results are; it is served only through\nV2, never through a V1 result, list or report.\n\n**Idempotency.** As V1, with the request identified by the input\nbytes (for a PDF, the PDF's own bytes), the selectors and the scope.\nA replay returns the original operation and its result, even if\n`latest` has since moved.\n\n**Findings.** At most 1,000 inline, ordered by the pipeline's layer\norder, then severity (`fatal`, `warning`, `information`), then\n`rule_id`, then location, then message. `findings_summary` states\nthe totals and whether truncation happened.\n\nSelect your invoice in Body: the XML, or a ZUGFeRD / Factur-X PDF with media_type set to application/pdf. The file is sent to Ironfang Finance for validation.", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "{{media_type}}" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "validate" ], "query": [ { "disabled": true, "key": "ruleset", "value": "{{ruleset}}" }, { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "variant", "value": "{{variant}}" }, { "disabled": true, "key": "document_type", "value": "{{document_type}}" }, { "disabled": true, "key": "scope", "value": "{{scope}}" } ], "raw": "{{base_url}}/v2/einvoices/validate" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/validation-result/v2\",\n \"status\": \"completed\",\n \"outcome\": \"valid\",\n \"input\": {\n \"media_type\": \"application/xml\",\n \"bytes\": 9228,\n \"sha256\": \"1b7cc3ff1834c8963f2c93f30f171b58002cbf0b2c52dc8765e7e83aebb9f7c9\",\n \"document_type\": \"invoice\"\n },\n \"declared\": {\n \"syntax\": \"ubl\",\n \"root\": \"Invoice\",\n \"specification_id\": \"urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0\",\n \"business_process_id\": \"urn:fdc:peppol.eu:2017:poacc:billing:01:1.0\",\n \"type_code\": \"380\",\n \"family\": \"peppol-bis-billing-3\"\n },\n \"ruleset\": {\n \"requested\": \"latest\",\n \"id\": \"fwrs_bis3_billing_invoice_2026_5_r5\",\n \"selection_method\": \"detected\",\n \"state\": \"sendable\",\n \"family\": \"peppol-bis-billing-3\",\n \"syntax\": \"ubl-2.1\",\n \"scope\": \"xml\",\n \"official_release\": \"2026.5 (May 2026 release, aka BIS Billing 3.0.21)\"\n },\n \"coverage\": {\n \"scope\": \"xml\",\n \"checked\": [\n \"input\",\n \"xml\",\n \"xsd\",\n \"en16931\",\n \"peppol\"\n ],\n \"not_checked\": []\n },\n \"groups\": [\n {\n \"group\": \"invoice_xml\",\n \"status\": \"passed\",\n \"layers\": [\n \"input\",\n \"xml\",\n \"xsd\",\n \"en16931\",\n \"peppol\"\n ]\n }\n ],\n \"layers\": [\n {\n \"layer\": \"input\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"xml\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"xsd\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"en16931\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"peppol\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n }\n ],\n \"counts\": {\n \"by_severity\": {\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n }\n },\n \"findings\": [],\n \"findings_summary\": {\n \"returned\": 0,\n \"total\": 0,\n \"cap\": 1000,\n \"truncated\": false\n },\n \"timing\": {\n \"started_at\": \"2026-09-02T12:00:00.2928494Z\",\n \"completed_at\": \"2026-09-02T12:00:00.62107524Z\",\n \"duration_ms\": 328\n },\n \"engines\": [\n {\n \"role\": \"xml\",\n \"name\": \"phive 12.1.0 / phive-rules-peppol 4.5.6 / Saxon-HE 12.10\",\n \"image_digest\": \"sha256:cb9b2a0aea77e6c210aa9407937d2ee7af4ec24d203c39cf498462cf9590f21d\"\n }\n ],\n \"next_actions\": [\n \"view\"\n ]\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "200 A Peppol BIS Billing 3 invoice, detected and run on the Peppol validator its release is pinned to", "originalRequest": { "body": { "file": { "src": "" }, "mode": "file" }, "description": "**Body.** Send the document itself with `Content-Type`\n`application/xml`, `text/xml` or `application/pdf`, choosing with the\nquery parameters. Or send `multipart/form-data` with one `document`\npart (one of those media types) and an optional `options` part\nholding a JSON `ValidationOptions` object; query parameters are not\nread for multipart requests. The media type is a hint: the content\nis inspected, and an XML part holding a PDF (or the reverse) is\n`415 unsupported_content_type`. Archives and compressed bodies are\nrefused the same way.\n\n**Limits.** XML at most 5 MiB (5,242,880 bytes), 64 levels deep,\n250,000 elements. PDF at most 20 MiB, 200 pages and 20 embedded\nfiles; the embedded invoice XML at most 5 MiB; 25 MiB of decoded\nattachment data in total; 256 MiB of compressed (Flate) content\ndecoded across the whole PDF. Over a byte limit is `413`; over any other\nprocessing limit is `422 processing_limit`, which is not a verdict on\nthe invoice. The XML deadline is 10 seconds and the hybrid deadline\n30 seconds; exceeding it is indeterminate (`504`).\n\n**Selection.** `ruleset` is `latest` (default) or an exact ruleset\nid.\n\n- With an exact id, the release supplies family, variant, syntax,\n document type and scope. Any selector also sent must equal the\n release's value, or the request is `422 selection_conflict`; the\n document must fit the release (`422 unsupported_document_type`,\n `422 family_mismatch`).\n- With `latest`, the family is the one requested or, without\n `family`, the one the document declares\n (`selection_method: detected`); an undeclared or unknown family is\n `422 family_undetected`. A requested family the document\n contradicts is `422 family_mismatch`, and the Problem's\n `detected` says what the document declares, so a client can offer\n the right tool; the document is never validated under the wrong\n family. The variant is the one the document declares; a variant\n Ironfang recognises but does not validate is\n `422 unsupported_variant`, never a fallback to a weaker profile.\n- `scope` defaults to `xml` for XML and `hybrid_pdf` for a PDF.\n Any other combination is `422 scope_unavailable`. To inspect only\n the XML inside a PDF, extract it explicitly\n (`POST /tools/v2/invoice/extract`) and validate that XML.\n\n**PDF inputs.** An encrypted PDF is `422 encrypted_pdf`. A PDF with\nno identifiable embedded invoice XML is `422 no_embedded_invoice`,\nand one with more than one plausible invoice XML is\n`422 ambiguous_embedded_invoice`: no attachment is ever chosen\narbitrarily. These three are uncharged. Everything wrong with an\nidentified embedded invoice - its name, relationship, media type,\nmetadata, PDF/A conformance, or the XML itself - is a finding in a\ncompleted validation.\n\n**Outcome.** `200` is always a verdict: `status: completed`,\n`outcome` `valid` or `invalid`, and every check that ran completed.\nA deterministic defect makes the outcome `invalid`, and checks it\nprevented are `skipped` with a reason. A timeout, an unavailable\nvalidator or an internal failure is a Problem with\n`outcome: indeterminate`; known findings are never presented as a\nverdict.\n\n**Usage.** One completed validation is one operation, whatever the\nscope; the checks inside it are not billed separately. As in V1, a\ncompleted validation is charged once its schema check (`xsd`)\nreached a verdict, passed or failed; a document that is not\nwell-formed XML ends before it and is not charged. Rejected\nrequests and indeterminate outcomes are not charged. An\nauthenticated verdict carries `operation_id` and `usage`, and is\nretained for 30 days as V1 results are; it is served only through\nV2, never through a V1 result, list or report.\n\n**Idempotency.** As V1, with the request identified by the input\nbytes (for a PDF, the PDF's own bytes), the selectors and the scope.\nA replay returns the original operation and its result, even if\n`latest` has since moved.\n\n**Findings.** At most 1,000 inline, ordered by the pipeline's layer\norder, then severity (`fatal`, `warning`, `information`), then\n`rule_id`, then location, then message. `findings_summary` states\nthe totals and whether truncation happened.\n\nSelect your invoice in Body: the XML, or a ZUGFeRD / Factur-X PDF with media_type set to application/pdf. The file is sent to Ironfang Finance for validation.", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "{{media_type}}" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "validate" ], "query": [ { "disabled": true, "key": "ruleset", "value": "{{ruleset}}" }, { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "variant", "value": "{{variant}}" }, { "disabled": true, "key": "document_type", "value": "{{document_type}}" }, { "disabled": true, "key": "scope", "value": "{{scope}}" } ], "raw": "{{base_url}}/v2/einvoices/validate" } }, "status": "OK" }, { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/validation-result/v2\",\n \"operation_id\": \"0192b3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b\",\n \"status\": \"completed\",\n \"outcome\": \"invalid\",\n \"input\": {\n \"media_type\": \"application/xml\",\n \"bytes\": 9127,\n \"sha256\": \"a0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566778899aabbccddeeff\",\n \"document_type\": \"invoice\"\n },\n \"declared\": {\n \"syntax\": \"cii\",\n \"root\": \"CrossIndustryInvoice\",\n \"specification_id\": \"urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0\",\n \"business_process_id\": \"urn:fdc:peppol.eu:2017:poacc:billing:01:1.0\",\n \"type_code\": \"380\",\n \"family\": \"xrechnung\",\n \"variant\": \"core\"\n },\n \"ruleset\": {\n \"requested\": \"latest\",\n \"id\": \"fwrs_example_xrechnung_cii_invoice\",\n \"selection_method\": \"latest\",\n \"state\": \"sendable\",\n \"family\": \"xrechnung\",\n \"variant\": \"core\",\n \"syntax\": \"cii-d16b\",\n \"scope\": \"xml\",\n \"official_release\": \"3.0.2\",\n \"technical_release\": \"2026-08-31\"\n },\n \"coverage\": {\n \"scope\": \"xml\",\n \"checked\": [\n \"input\",\n \"xml\",\n \"xsd\",\n \"en16931\",\n \"xrechnung\"\n ],\n \"not_checked\": []\n },\n \"groups\": [\n {\n \"group\": \"invoice_xml\",\n \"status\": \"failed\",\n \"layers\": [\n \"input\",\n \"xml\",\n \"xsd\",\n \"en16931\",\n \"xrechnung\"\n ]\n }\n ],\n \"layers\": [\n {\n \"layer\": \"input\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"xml\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"xsd\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"en16931\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"xrechnung\",\n \"status\": \"failed\",\n \"fatal\": 1,\n \"warning\": 0,\n \"information\": 1\n }\n ],\n \"counts\": {\n \"by_severity\": {\n \"fatal\": 1,\n \"warning\": 0,\n \"information\": 1\n }\n },\n \"findings\": [\n {\n \"severity\": \"fatal\",\n \"rule_flag\": \"fatal\",\n \"layer\": \"xrechnung\",\n \"rule_id\": \"BR-DE-15\",\n \"rule_source\": \"official\",\n \"message\": \"An XRechnung rule failed at this location.\",\n \"location\": {\n \"kind\": \"xpath\",\n \"value\": \"/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeAgreement\"\n },\n \"hint_code\": \"xrechnung-buyer-reference\"\n },\n {\n \"severity\": \"information\",\n \"rule_flag\": \"information\",\n \"layer\": \"xrechnung\",\n \"rule_id\": \"BR-DE-TMP-32\",\n \"rule_source\": \"official\",\n \"message\": \"An XRechnung rule failed at this location.\",\n \"location\": {\n \"kind\": \"xpath\",\n \"value\": \"/rsm:CrossIndustryInvoice\"\n }\n }\n ],\n \"findings_summary\": {\n \"returned\": 2,\n \"total\": 2,\n \"cap\": 1000,\n \"truncated\": false\n },\n \"timing\": {\n \"started_at\": \"2026-09-24T10:15:02Z\",\n \"completed_at\": \"2026-09-24T10:15:02Z\",\n \"duration_ms\": 47\n },\n \"engines\": [\n {\n \"role\": \"xml\",\n \"name\": \"phive-xml 12.1.0 / Saxon-HE 12.10 / XRechnung bundle 2026-08-31\",\n \"image_digest\": \"sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\"\n }\n ],\n \"next_actions\": [\n \"view\"\n ],\n \"usage\": {\n \"charged\": true,\n \"credits\": 1\n }\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "200 An XRechnung CII invoice without a buyer reference, family requested", "originalRequest": { "body": { "file": { "src": "" }, "mode": "file" }, "description": "**Body.** Send the document itself with `Content-Type`\n`application/xml`, `text/xml` or `application/pdf`, choosing with the\nquery parameters. Or send `multipart/form-data` with one `document`\npart (one of those media types) and an optional `options` part\nholding a JSON `ValidationOptions` object; query parameters are not\nread for multipart requests. The media type is a hint: the content\nis inspected, and an XML part holding a PDF (or the reverse) is\n`415 unsupported_content_type`. Archives and compressed bodies are\nrefused the same way.\n\n**Limits.** XML at most 5 MiB (5,242,880 bytes), 64 levels deep,\n250,000 elements. PDF at most 20 MiB, 200 pages and 20 embedded\nfiles; the embedded invoice XML at most 5 MiB; 25 MiB of decoded\nattachment data in total; 256 MiB of compressed (Flate) content\ndecoded across the whole PDF. Over a byte limit is `413`; over any other\nprocessing limit is `422 processing_limit`, which is not a verdict on\nthe invoice. The XML deadline is 10 seconds and the hybrid deadline\n30 seconds; exceeding it is indeterminate (`504`).\n\n**Selection.** `ruleset` is `latest` (default) or an exact ruleset\nid.\n\n- With an exact id, the release supplies family, variant, syntax,\n document type and scope. Any selector also sent must equal the\n release's value, or the request is `422 selection_conflict`; the\n document must fit the release (`422 unsupported_document_type`,\n `422 family_mismatch`).\n- With `latest`, the family is the one requested or, without\n `family`, the one the document declares\n (`selection_method: detected`); an undeclared or unknown family is\n `422 family_undetected`. A requested family the document\n contradicts is `422 family_mismatch`, and the Problem's\n `detected` says what the document declares, so a client can offer\n the right tool; the document is never validated under the wrong\n family. The variant is the one the document declares; a variant\n Ironfang recognises but does not validate is\n `422 unsupported_variant`, never a fallback to a weaker profile.\n- `scope` defaults to `xml` for XML and `hybrid_pdf` for a PDF.\n Any other combination is `422 scope_unavailable`. To inspect only\n the XML inside a PDF, extract it explicitly\n (`POST /tools/v2/invoice/extract`) and validate that XML.\n\n**PDF inputs.** An encrypted PDF is `422 encrypted_pdf`. A PDF with\nno identifiable embedded invoice XML is `422 no_embedded_invoice`,\nand one with more than one plausible invoice XML is\n`422 ambiguous_embedded_invoice`: no attachment is ever chosen\narbitrarily. These three are uncharged. Everything wrong with an\nidentified embedded invoice - its name, relationship, media type,\nmetadata, PDF/A conformance, or the XML itself - is a finding in a\ncompleted validation.\n\n**Outcome.** `200` is always a verdict: `status: completed`,\n`outcome` `valid` or `invalid`, and every check that ran completed.\nA deterministic defect makes the outcome `invalid`, and checks it\nprevented are `skipped` with a reason. A timeout, an unavailable\nvalidator or an internal failure is a Problem with\n`outcome: indeterminate`; known findings are never presented as a\nverdict.\n\n**Usage.** One completed validation is one operation, whatever the\nscope; the checks inside it are not billed separately. As in V1, a\ncompleted validation is charged once its schema check (`xsd`)\nreached a verdict, passed or failed; a document that is not\nwell-formed XML ends before it and is not charged. Rejected\nrequests and indeterminate outcomes are not charged. An\nauthenticated verdict carries `operation_id` and `usage`, and is\nretained for 30 days as V1 results are; it is served only through\nV2, never through a V1 result, list or report.\n\n**Idempotency.** As V1, with the request identified by the input\nbytes (for a PDF, the PDF's own bytes), the selectors and the scope.\nA replay returns the original operation and its result, even if\n`latest` has since moved.\n\n**Findings.** At most 1,000 inline, ordered by the pipeline's layer\norder, then severity (`fatal`, `warning`, `information`), then\n`rule_id`, then location, then message. `findings_summary` states\nthe totals and whether truncation happened.\n\nSelect your invoice in Body: the XML, or a ZUGFeRD / Factur-X PDF with media_type set to application/pdf. The file is sent to Ironfang Finance for validation.", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "{{media_type}}" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "validate" ], "query": [ { "disabled": true, "key": "ruleset", "value": "{{ruleset}}" }, { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "variant", "value": "{{variant}}" }, { "disabled": true, "key": "document_type", "value": "{{document_type}}" }, { "disabled": true, "key": "scope", "value": "{{scope}}" } ], "raw": "{{base_url}}/v2/einvoices/validate" } }, "status": "OK" }, { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/validation-result/v2\",\n \"status\": \"completed\",\n \"outcome\": \"valid\",\n \"input\": {\n \"media_type\": \"application/xml\",\n \"bytes\": 8312,\n \"sha256\": \"4f9a1c1e8a2b6d7e3f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e\",\n \"document_type\": \"invoice\"\n },\n \"declared\": {\n \"syntax\": \"ubl\",\n \"root\": \"Invoice\",\n \"specification_id\": \"urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0\",\n \"business_process_id\": \"urn:fdc:peppol.eu:2017:poacc:billing:01:1.0\",\n \"type_code\": \"380\",\n \"family\": \"xrechnung\",\n \"variant\": \"core\"\n },\n \"ruleset\": {\n \"requested\": \"latest\",\n \"id\": \"fwrs_example_xrechnung_ubl_invoice\",\n \"selection_method\": \"detected\",\n \"state\": \"sendable\",\n \"family\": \"xrechnung\",\n \"variant\": \"core\",\n \"syntax\": \"ubl-2.1\",\n \"scope\": \"xml\",\n \"official_release\": \"3.0.2\",\n \"technical_release\": \"2026-08-31\"\n },\n \"coverage\": {\n \"scope\": \"xml\",\n \"checked\": [\n \"input\",\n \"xml\",\n \"xsd\",\n \"en16931\",\n \"xrechnung\"\n ],\n \"not_checked\": []\n },\n \"groups\": [\n {\n \"group\": \"invoice_xml\",\n \"status\": \"passed\",\n \"layers\": [\n \"input\",\n \"xml\",\n \"xsd\",\n \"en16931\",\n \"xrechnung\"\n ]\n }\n ],\n \"layers\": [\n {\n \"layer\": \"input\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"xml\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"xsd\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"en16931\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"xrechnung\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 1\n }\n ],\n \"counts\": {\n \"by_severity\": {\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 1\n }\n },\n \"findings\": [\n {\n \"severity\": \"information\",\n \"rule_flag\": \"information\",\n \"layer\": \"xrechnung\",\n \"rule_id\": \"BR-DE-TMP-32\",\n \"rule_source\": \"official\",\n \"message\": \"An XRechnung rule failed at this location.\",\n \"location\": {\n \"kind\": \"xpath\",\n \"value\": \"/Invoice\"\n }\n }\n ],\n \"findings_summary\": {\n \"returned\": 1,\n \"total\": 1,\n \"cap\": 1000,\n \"truncated\": false\n },\n \"timing\": {\n \"started_at\": \"2026-09-24T10:15:02Z\",\n \"completed_at\": \"2026-09-24T10:15:02Z\",\n \"duration_ms\": 41\n },\n \"engines\": [\n {\n \"role\": \"xml\",\n \"name\": \"phive-xml 12.1.0 / Saxon-HE 12.10 / XRechnung bundle 2026-08-31\",\n \"image_digest\": \"sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\"\n }\n ],\n \"next_actions\": [\n \"view\"\n ]\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "200 A valid XRechnung UBL invoice, family detected; information findings do not fail it", "originalRequest": { "body": { "file": { "src": "" }, "mode": "file" }, "description": "**Body.** Send the document itself with `Content-Type`\n`application/xml`, `text/xml` or `application/pdf`, choosing with the\nquery parameters. Or send `multipart/form-data` with one `document`\npart (one of those media types) and an optional `options` part\nholding a JSON `ValidationOptions` object; query parameters are not\nread for multipart requests. The media type is a hint: the content\nis inspected, and an XML part holding a PDF (or the reverse) is\n`415 unsupported_content_type`. Archives and compressed bodies are\nrefused the same way.\n\n**Limits.** XML at most 5 MiB (5,242,880 bytes), 64 levels deep,\n250,000 elements. PDF at most 20 MiB, 200 pages and 20 embedded\nfiles; the embedded invoice XML at most 5 MiB; 25 MiB of decoded\nattachment data in total; 256 MiB of compressed (Flate) content\ndecoded across the whole PDF. Over a byte limit is `413`; over any other\nprocessing limit is `422 processing_limit`, which is not a verdict on\nthe invoice. The XML deadline is 10 seconds and the hybrid deadline\n30 seconds; exceeding it is indeterminate (`504`).\n\n**Selection.** `ruleset` is `latest` (default) or an exact ruleset\nid.\n\n- With an exact id, the release supplies family, variant, syntax,\n document type and scope. Any selector also sent must equal the\n release's value, or the request is `422 selection_conflict`; the\n document must fit the release (`422 unsupported_document_type`,\n `422 family_mismatch`).\n- With `latest`, the family is the one requested or, without\n `family`, the one the document declares\n (`selection_method: detected`); an undeclared or unknown family is\n `422 family_undetected`. A requested family the document\n contradicts is `422 family_mismatch`, and the Problem's\n `detected` says what the document declares, so a client can offer\n the right tool; the document is never validated under the wrong\n family. The variant is the one the document declares; a variant\n Ironfang recognises but does not validate is\n `422 unsupported_variant`, never a fallback to a weaker profile.\n- `scope` defaults to `xml` for XML and `hybrid_pdf` for a PDF.\n Any other combination is `422 scope_unavailable`. To inspect only\n the XML inside a PDF, extract it explicitly\n (`POST /tools/v2/invoice/extract`) and validate that XML.\n\n**PDF inputs.** An encrypted PDF is `422 encrypted_pdf`. A PDF with\nno identifiable embedded invoice XML is `422 no_embedded_invoice`,\nand one with more than one plausible invoice XML is\n`422 ambiguous_embedded_invoice`: no attachment is ever chosen\narbitrarily. These three are uncharged. Everything wrong with an\nidentified embedded invoice - its name, relationship, media type,\nmetadata, PDF/A conformance, or the XML itself - is a finding in a\ncompleted validation.\n\n**Outcome.** `200` is always a verdict: `status: completed`,\n`outcome` `valid` or `invalid`, and every check that ran completed.\nA deterministic defect makes the outcome `invalid`, and checks it\nprevented are `skipped` with a reason. A timeout, an unavailable\nvalidator or an internal failure is a Problem with\n`outcome: indeterminate`; known findings are never presented as a\nverdict.\n\n**Usage.** One completed validation is one operation, whatever the\nscope; the checks inside it are not billed separately. As in V1, a\ncompleted validation is charged once its schema check (`xsd`)\nreached a verdict, passed or failed; a document that is not\nwell-formed XML ends before it and is not charged. Rejected\nrequests and indeterminate outcomes are not charged. An\nauthenticated verdict carries `operation_id` and `usage`, and is\nretained for 30 days as V1 results are; it is served only through\nV2, never through a V1 result, list or report.\n\n**Idempotency.** As V1, with the request identified by the input\nbytes (for a PDF, the PDF's own bytes), the selectors and the scope.\nA replay returns the original operation and its result, even if\n`latest` has since moved.\n\n**Findings.** At most 1,000 inline, ordered by the pipeline's layer\norder, then severity (`fatal`, `warning`, `information`), then\n`rule_id`, then location, then message. `findings_summary` states\nthe totals and whether truncation happened.\n\nSelect your invoice in Body: the XML, or a ZUGFeRD / Factur-X PDF with media_type set to application/pdf. The file is sent to Ironfang Finance for validation.", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "{{media_type}}" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "validate" ], "query": [ { "disabled": true, "key": "ruleset", "value": "{{ruleset}}" }, { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "variant", "value": "{{variant}}" }, { "disabled": true, "key": "document_type", "value": "{{document_type}}" }, { "disabled": true, "key": "scope", "value": "{{scope}}" } ], "raw": "{{base_url}}/v2/einvoices/validate" } }, "status": "OK" }, { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/validation-result/v2\",\n \"status\": \"completed\",\n \"outcome\": \"invalid\",\n \"input\": {\n \"media_type\": \"application/pdf\",\n \"bytes\": 184220,\n \"sha256\": \"9e8d7c6b5a4938271605f4e3d2c1b0a99887766554433221100ffeeddccbbaa9\",\n \"document_type\": \"invoice\",\n \"embedded_xml\": {\n \"bytes\": 11532,\n \"sha256\": \"5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f7081920a\",\n \"file_name\": \"invoice.xml\"\n }\n },\n \"declared\": {\n \"syntax\": \"cii\",\n \"root\": \"CrossIndustryInvoice\",\n \"specification_id\": \"urn:cen.eu:en16931:2017\",\n \"type_code\": \"380\",\n \"family\": \"zugferd-facturx\",\n \"variant\": \"en16931\",\n \"pdf\": {\n \"conformance_level\": \"EN 16931\",\n \"document_file_name\": \"factur-x.xml\",\n \"document_type\": \"INVOICE\",\n \"version\": \"1.0\",\n \"pdfa_part\": \"3\",\n \"pdfa_conformance\": \"B\"\n }\n },\n \"ruleset\": {\n \"requested\": \"latest\",\n \"id\": \"fwrs_example_zugferd_en16931_invoice_pdf\",\n \"selection_method\": \"detected\",\n \"state\": \"sendable\",\n \"family\": \"zugferd-facturx\",\n \"variant\": \"en16931\",\n \"syntax\": \"cii-d22b\",\n \"scope\": \"hybrid_pdf\",\n \"official_release\": \"2.5.2\",\n \"technical_release\": \"1.09.2\"\n },\n \"coverage\": {\n \"scope\": \"hybrid_pdf\",\n \"checked\": [\n \"input\",\n \"pdfa\",\n \"hybrid_binding\",\n \"xml\",\n \"xsd\",\n \"zugferd_profile\"\n ],\n \"not_checked\": [\n {\n \"aspect\": \"visual_consistency\",\n \"reason\": \"not_implemented\"\n },\n {\n \"aspect\": \"digital_signature\",\n \"reason\": \"outside_scope\"\n }\n ]\n },\n \"groups\": [\n {\n \"group\": \"pdfa\",\n \"status\": \"passed\",\n \"layers\": [\n \"input\",\n \"pdfa\"\n ]\n },\n {\n \"group\": \"attachment_metadata\",\n \"status\": \"failed\",\n \"layers\": [\n \"hybrid_binding\"\n ]\n },\n {\n \"group\": \"invoice_xml\",\n \"status\": \"passed\",\n \"layers\": [\n \"xml\",\n \"xsd\",\n \"zugferd_profile\"\n ]\n }\n ],\n \"layers\": [\n {\n \"layer\": \"input\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"pdfa\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"hybrid_binding\",\n \"status\": \"failed\",\n \"fatal\": 1,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"xml\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"xsd\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"zugferd_profile\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n }\n ],\n \"counts\": {\n \"by_severity\": {\n \"fatal\": 1,\n \"warning\": 0,\n \"information\": 0\n }\n },\n \"findings\": [\n {\n \"severity\": \"fatal\",\n \"rule_flag\": \"fatal\",\n \"layer\": \"hybrid_binding\",\n \"rule_id\": \"FW-HYB-003\",\n \"rule_source\": \"ironfang\",\n \"message\": \"The embedded invoice file does not have the name this profile requires.\",\n \"location\": {\n \"kind\": \"pdf\",\n \"value\": \"/Root/Names/EmbeddedFiles\"\n }\n }\n ],\n \"findings_summary\": {\n \"returned\": 1,\n \"total\": 1,\n \"cap\": 1000,\n \"truncated\": false\n },\n \"timing\": {\n \"started_at\": \"2026-09-24T10:15:02Z\",\n \"completed_at\": \"2026-09-24T10:15:02Z\",\n \"duration_ms\": 1840\n },\n \"engines\": [\n {\n \"role\": \"xml\",\n \"name\": \"phive-xml 12.1.0 / Saxon-HE 12.10 / phive-rules-zugferd 4.5.6\",\n \"image_digest\": \"sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\"\n },\n {\n \"role\": \"pdf\",\n \"name\": \"PDFBox 3.0.8 / veraPDF 1.30.2 / Ironfang binding 1\",\n \"image_digest\": \"sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff\"\n }\n ],\n \"next_actions\": [\n \"view\",\n \"extract_xml\"\n ]\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "200 Invoice XML passed; the PDF container checks failed", "originalRequest": { "body": { "file": { "src": "" }, "mode": "file" }, "description": "**Body.** Send the document itself with `Content-Type`\n`application/xml`, `text/xml` or `application/pdf`, choosing with the\nquery parameters. Or send `multipart/form-data` with one `document`\npart (one of those media types) and an optional `options` part\nholding a JSON `ValidationOptions` object; query parameters are not\nread for multipart requests. The media type is a hint: the content\nis inspected, and an XML part holding a PDF (or the reverse) is\n`415 unsupported_content_type`. Archives and compressed bodies are\nrefused the same way.\n\n**Limits.** XML at most 5 MiB (5,242,880 bytes), 64 levels deep,\n250,000 elements. PDF at most 20 MiB, 200 pages and 20 embedded\nfiles; the embedded invoice XML at most 5 MiB; 25 MiB of decoded\nattachment data in total; 256 MiB of compressed (Flate) content\ndecoded across the whole PDF. Over a byte limit is `413`; over any other\nprocessing limit is `422 processing_limit`, which is not a verdict on\nthe invoice. The XML deadline is 10 seconds and the hybrid deadline\n30 seconds; exceeding it is indeterminate (`504`).\n\n**Selection.** `ruleset` is `latest` (default) or an exact ruleset\nid.\n\n- With an exact id, the release supplies family, variant, syntax,\n document type and scope. Any selector also sent must equal the\n release's value, or the request is `422 selection_conflict`; the\n document must fit the release (`422 unsupported_document_type`,\n `422 family_mismatch`).\n- With `latest`, the family is the one requested or, without\n `family`, the one the document declares\n (`selection_method: detected`); an undeclared or unknown family is\n `422 family_undetected`. A requested family the document\n contradicts is `422 family_mismatch`, and the Problem's\n `detected` says what the document declares, so a client can offer\n the right tool; the document is never validated under the wrong\n family. The variant is the one the document declares; a variant\n Ironfang recognises but does not validate is\n `422 unsupported_variant`, never a fallback to a weaker profile.\n- `scope` defaults to `xml` for XML and `hybrid_pdf` for a PDF.\n Any other combination is `422 scope_unavailable`. To inspect only\n the XML inside a PDF, extract it explicitly\n (`POST /tools/v2/invoice/extract`) and validate that XML.\n\n**PDF inputs.** An encrypted PDF is `422 encrypted_pdf`. A PDF with\nno identifiable embedded invoice XML is `422 no_embedded_invoice`,\nand one with more than one plausible invoice XML is\n`422 ambiguous_embedded_invoice`: no attachment is ever chosen\narbitrarily. These three are uncharged. Everything wrong with an\nidentified embedded invoice - its name, relationship, media type,\nmetadata, PDF/A conformance, or the XML itself - is a finding in a\ncompleted validation.\n\n**Outcome.** `200` is always a verdict: `status: completed`,\n`outcome` `valid` or `invalid`, and every check that ran completed.\nA deterministic defect makes the outcome `invalid`, and checks it\nprevented are `skipped` with a reason. A timeout, an unavailable\nvalidator or an internal failure is a Problem with\n`outcome: indeterminate`; known findings are never presented as a\nverdict.\n\n**Usage.** One completed validation is one operation, whatever the\nscope; the checks inside it are not billed separately. As in V1, a\ncompleted validation is charged once its schema check (`xsd`)\nreached a verdict, passed or failed; a document that is not\nwell-formed XML ends before it and is not charged. Rejected\nrequests and indeterminate outcomes are not charged. An\nauthenticated verdict carries `operation_id` and `usage`, and is\nretained for 30 days as V1 results are; it is served only through\nV2, never through a V1 result, list or report.\n\n**Idempotency.** As V1, with the request identified by the input\nbytes (for a PDF, the PDF's own bytes), the selectors and the scope.\nA replay returns the original operation and its result, even if\n`latest` has since moved.\n\n**Findings.** At most 1,000 inline, ordered by the pipeline's layer\norder, then severity (`fatal`, `warning`, `information`), then\n`rule_id`, then location, then message. `findings_summary` states\nthe totals and whether truncation happened.\n\nSelect your invoice in Body: the XML, or a ZUGFeRD / Factur-X PDF with media_type set to application/pdf. The file is sent to Ironfang Finance for validation.", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "{{media_type}}" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "validate" ], "query": [ { "disabled": true, "key": "ruleset", "value": "{{ruleset}}" }, { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "variant", "value": "{{variant}}" }, { "disabled": true, "key": "document_type", "value": "{{document_type}}" }, { "disabled": true, "key": "scope", "value": "{{scope}}" } ], "raw": "{{base_url}}/v2/einvoices/validate" } }, "status": "OK" }, { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/validation-result/v2\",\n \"status\": \"completed\",\n \"outcome\": \"valid\",\n \"input\": {\n \"media_type\": \"application/xml\",\n \"bytes\": 2144,\n \"sha256\": \"1b2c3d4e5f60718293a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f8091\",\n \"document_type\": \"invoice\"\n },\n \"declared\": {\n \"syntax\": \"cii\",\n \"root\": \"CrossIndustryInvoice\",\n \"specification_id\": \"urn:factur-x.eu:1p0:minimum\",\n \"type_code\": \"380\",\n \"family\": \"zugferd-facturx\",\n \"variant\": \"minimum\"\n },\n \"ruleset\": {\n \"requested\": \"latest\",\n \"id\": \"fwrs_example_zugferd_minimum_invoice\",\n \"selection_method\": \"detected\",\n \"state\": \"sendable\",\n \"family\": \"zugferd-facturx\",\n \"variant\": \"minimum\",\n \"syntax\": \"cii-d22b\",\n \"scope\": \"xml\",\n \"official_release\": \"2.5.2\",\n \"technical_release\": \"1.09.2\"\n },\n \"coverage\": {\n \"scope\": \"xml\",\n \"checked\": [\n \"input\",\n \"xml\",\n \"xsd\",\n \"zugferd_profile\"\n ],\n \"not_checked\": [\n {\n \"aspect\": \"pdf_container\",\n \"reason\": \"no_pdf_supplied\"\n },\n {\n \"aspect\": \"en16931_semantics\",\n \"reason\": \"reduced_profile\"\n }\n ]\n },\n \"groups\": [\n {\n \"group\": \"invoice_xml\",\n \"status\": \"passed\",\n \"layers\": [\n \"input\",\n \"xml\",\n \"xsd\",\n \"zugferd_profile\"\n ]\n }\n ],\n \"layers\": [\n {\n \"layer\": \"input\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"xml\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"xsd\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n },\n {\n \"layer\": \"zugferd_profile\",\n \"status\": \"passed\",\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n }\n ],\n \"counts\": {\n \"by_severity\": {\n \"fatal\": 0,\n \"warning\": 0,\n \"information\": 0\n }\n },\n \"findings\": [],\n \"findings_summary\": {\n \"returned\": 0,\n \"total\": 0,\n \"cap\": 1000,\n \"truncated\": false\n },\n \"timing\": {\n \"started_at\": \"2026-09-24T10:15:02Z\",\n \"completed_at\": \"2026-09-24T10:15:02Z\",\n \"duration_ms\": 18\n },\n \"engines\": [\n {\n \"role\": \"xml\",\n \"name\": \"phive-xml 12.1.0 / Saxon-HE 12.10 / phive-rules-zugferd 4.5.6\",\n \"image_digest\": \"sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\"\n }\n ],\n \"next_actions\": [\n \"view\"\n ]\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "200 A ZUGFeRD MINIMUM XML passes its reduced profile; no PDF was supplied", "originalRequest": { "body": { "file": { "src": "" }, "mode": "file" }, "description": "**Body.** Send the document itself with `Content-Type`\n`application/xml`, `text/xml` or `application/pdf`, choosing with the\nquery parameters. Or send `multipart/form-data` with one `document`\npart (one of those media types) and an optional `options` part\nholding a JSON `ValidationOptions` object; query parameters are not\nread for multipart requests. The media type is a hint: the content\nis inspected, and an XML part holding a PDF (or the reverse) is\n`415 unsupported_content_type`. Archives and compressed bodies are\nrefused the same way.\n\n**Limits.** XML at most 5 MiB (5,242,880 bytes), 64 levels deep,\n250,000 elements. PDF at most 20 MiB, 200 pages and 20 embedded\nfiles; the embedded invoice XML at most 5 MiB; 25 MiB of decoded\nattachment data in total; 256 MiB of compressed (Flate) content\ndecoded across the whole PDF. Over a byte limit is `413`; over any other\nprocessing limit is `422 processing_limit`, which is not a verdict on\nthe invoice. The XML deadline is 10 seconds and the hybrid deadline\n30 seconds; exceeding it is indeterminate (`504`).\n\n**Selection.** `ruleset` is `latest` (default) or an exact ruleset\nid.\n\n- With an exact id, the release supplies family, variant, syntax,\n document type and scope. Any selector also sent must equal the\n release's value, or the request is `422 selection_conflict`; the\n document must fit the release (`422 unsupported_document_type`,\n `422 family_mismatch`).\n- With `latest`, the family is the one requested or, without\n `family`, the one the document declares\n (`selection_method: detected`); an undeclared or unknown family is\n `422 family_undetected`. A requested family the document\n contradicts is `422 family_mismatch`, and the Problem's\n `detected` says what the document declares, so a client can offer\n the right tool; the document is never validated under the wrong\n family. The variant is the one the document declares; a variant\n Ironfang recognises but does not validate is\n `422 unsupported_variant`, never a fallback to a weaker profile.\n- `scope` defaults to `xml` for XML and `hybrid_pdf` for a PDF.\n Any other combination is `422 scope_unavailable`. To inspect only\n the XML inside a PDF, extract it explicitly\n (`POST /tools/v2/invoice/extract`) and validate that XML.\n\n**PDF inputs.** An encrypted PDF is `422 encrypted_pdf`. A PDF with\nno identifiable embedded invoice XML is `422 no_embedded_invoice`,\nand one with more than one plausible invoice XML is\n`422 ambiguous_embedded_invoice`: no attachment is ever chosen\narbitrarily. These three are uncharged. Everything wrong with an\nidentified embedded invoice - its name, relationship, media type,\nmetadata, PDF/A conformance, or the XML itself - is a finding in a\ncompleted validation.\n\n**Outcome.** `200` is always a verdict: `status: completed`,\n`outcome` `valid` or `invalid`, and every check that ran completed.\nA deterministic defect makes the outcome `invalid`, and checks it\nprevented are `skipped` with a reason. A timeout, an unavailable\nvalidator or an internal failure is a Problem with\n`outcome: indeterminate`; known findings are never presented as a\nverdict.\n\n**Usage.** One completed validation is one operation, whatever the\nscope; the checks inside it are not billed separately. As in V1, a\ncompleted validation is charged once its schema check (`xsd`)\nreached a verdict, passed or failed; a document that is not\nwell-formed XML ends before it and is not charged. Rejected\nrequests and indeterminate outcomes are not charged. An\nauthenticated verdict carries `operation_id` and `usage`, and is\nretained for 30 days as V1 results are; it is served only through\nV2, never through a V1 result, list or report.\n\n**Idempotency.** As V1, with the request identified by the input\nbytes (for a PDF, the PDF's own bytes), the selectors and the scope.\nA replay returns the original operation and its result, even if\n`latest` has since moved.\n\n**Findings.** At most 1,000 inline, ordered by the pipeline's layer\norder, then severity (`fatal`, `warning`, `information`), then\n`rule_id`, then location, then message. `findings_summary` states\nthe totals and whether truncation happened.\n\nSelect your invoice in Body: the XML, or a ZUGFeRD / Factur-X PDF with media_type set to application/pdf. The file is sent to Ironfang Finance for validation.", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "{{media_type}}" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "validate" ], "query": [ { "disabled": true, "key": "ruleset", "value": "{{ruleset}}" }, { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "variant", "value": "{{variant}}" }, { "disabled": true, "key": "document_type", "value": "{{document_type}}" }, { "disabled": true, "key": "scope", "value": "{{scope}}" } ], "raw": "{{base_url}}/v2/einvoices/validate" } }, "status": "OK" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"https://ironfang.com/problems/family_mismatch\",\n \"title\": \"Family mismatch\",\n \"status\": 422,\n \"detail\": \"The document declares Peppol BIS Billing 3, not the requested family xrechnung. It was not validated.\",\n \"instance\": \"/finance/v2/einvoices/validate\",\n \"code\": \"family_mismatch\",\n \"request_id\": \"01a0d509-24aa-74ef-9a25-5db40e20f85a\",\n \"detected\": {\n \"syntax\": \"ubl\",\n \"root\": \"Invoice\",\n \"specification_id\": \"urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0\",\n \"business_process_id\": \"urn:fdc:peppol.eu:2017:poacc:billing:01:1.0\",\n \"family\": \"peppol-bis-billing-3\"\n }\n}", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "name": "422 A Peppol invoice sent to the XRechnung validator", "originalRequest": { "body": { "file": { "src": "" }, "mode": "file" }, "description": "**Body.** Send the document itself with `Content-Type`\n`application/xml`, `text/xml` or `application/pdf`, choosing with the\nquery parameters. Or send `multipart/form-data` with one `document`\npart (one of those media types) and an optional `options` part\nholding a JSON `ValidationOptions` object; query parameters are not\nread for multipart requests. The media type is a hint: the content\nis inspected, and an XML part holding a PDF (or the reverse) is\n`415 unsupported_content_type`. Archives and compressed bodies are\nrefused the same way.\n\n**Limits.** XML at most 5 MiB (5,242,880 bytes), 64 levels deep,\n250,000 elements. PDF at most 20 MiB, 200 pages and 20 embedded\nfiles; the embedded invoice XML at most 5 MiB; 25 MiB of decoded\nattachment data in total; 256 MiB of compressed (Flate) content\ndecoded across the whole PDF. Over a byte limit is `413`; over any other\nprocessing limit is `422 processing_limit`, which is not a verdict on\nthe invoice. The XML deadline is 10 seconds and the hybrid deadline\n30 seconds; exceeding it is indeterminate (`504`).\n\n**Selection.** `ruleset` is `latest` (default) or an exact ruleset\nid.\n\n- With an exact id, the release supplies family, variant, syntax,\n document type and scope. Any selector also sent must equal the\n release's value, or the request is `422 selection_conflict`; the\n document must fit the release (`422 unsupported_document_type`,\n `422 family_mismatch`).\n- With `latest`, the family is the one requested or, without\n `family`, the one the document declares\n (`selection_method: detected`); an undeclared or unknown family is\n `422 family_undetected`. A requested family the document\n contradicts is `422 family_mismatch`, and the Problem's\n `detected` says what the document declares, so a client can offer\n the right tool; the document is never validated under the wrong\n family. The variant is the one the document declares; a variant\n Ironfang recognises but does not validate is\n `422 unsupported_variant`, never a fallback to a weaker profile.\n- `scope` defaults to `xml` for XML and `hybrid_pdf` for a PDF.\n Any other combination is `422 scope_unavailable`. To inspect only\n the XML inside a PDF, extract it explicitly\n (`POST /tools/v2/invoice/extract`) and validate that XML.\n\n**PDF inputs.** An encrypted PDF is `422 encrypted_pdf`. A PDF with\nno identifiable embedded invoice XML is `422 no_embedded_invoice`,\nand one with more than one plausible invoice XML is\n`422 ambiguous_embedded_invoice`: no attachment is ever chosen\narbitrarily. These three are uncharged. Everything wrong with an\nidentified embedded invoice - its name, relationship, media type,\nmetadata, PDF/A conformance, or the XML itself - is a finding in a\ncompleted validation.\n\n**Outcome.** `200` is always a verdict: `status: completed`,\n`outcome` `valid` or `invalid`, and every check that ran completed.\nA deterministic defect makes the outcome `invalid`, and checks it\nprevented are `skipped` with a reason. A timeout, an unavailable\nvalidator or an internal failure is a Problem with\n`outcome: indeterminate`; known findings are never presented as a\nverdict.\n\n**Usage.** One completed validation is one operation, whatever the\nscope; the checks inside it are not billed separately. As in V1, a\ncompleted validation is charged once its schema check (`xsd`)\nreached a verdict, passed or failed; a document that is not\nwell-formed XML ends before it and is not charged. Rejected\nrequests and indeterminate outcomes are not charged. An\nauthenticated verdict carries `operation_id` and `usage`, and is\nretained for 30 days as V1 results are; it is served only through\nV2, never through a V1 result, list or report.\n\n**Idempotency.** As V1, with the request identified by the input\nbytes (for a PDF, the PDF's own bytes), the selectors and the scope.\nA replay returns the original operation and its result, even if\n`latest` has since moved.\n\n**Findings.** At most 1,000 inline, ordered by the pipeline's layer\norder, then severity (`fatal`, `warning`, `information`), then\n`rule_id`, then location, then message. `findings_summary` states\nthe totals and whether truncation happened.\n\nSelect your invoice in Body: the XML, or a ZUGFeRD / Factur-X PDF with media_type set to application/pdf. The file is sent to Ironfang Finance for validation.", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "{{media_type}}" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "validate" ], "query": [ { "disabled": true, "key": "ruleset", "value": "{{ruleset}}" }, { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "variant", "value": "{{variant}}" }, { "disabled": true, "key": "document_type", "value": "{{document_type}}" }, { "disabled": true, "key": "scope", "value": "{{scope}}" } ], "raw": "{{base_url}}/v2/einvoices/validate" } }, "status": "Unprocessable Entity" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"https://ironfang.com/problems/no_embedded_invoice\",\n \"title\": \"No embedded invoice\",\n \"status\": 422,\n \"detail\": \"The PDF carries no embedded invoice XML. It may be an ordinary PDF invoice rather than ZUGFeRD or Factur-X. Nothing was charged.\",\n \"instance\": \"/finance/v2/einvoices/validate\",\n \"code\": \"no_embedded_invoice\",\n \"request_id\": \"01a0d509-2726-7606-9b45-1ae8f03c3856\"\n}", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "name": "422 An ordinary PDF with no invoice XML inside", "originalRequest": { "body": { "file": { "src": "" }, "mode": "file" }, "description": "**Body.** Send the document itself with `Content-Type`\n`application/xml`, `text/xml` or `application/pdf`, choosing with the\nquery parameters. Or send `multipart/form-data` with one `document`\npart (one of those media types) and an optional `options` part\nholding a JSON `ValidationOptions` object; query parameters are not\nread for multipart requests. The media type is a hint: the content\nis inspected, and an XML part holding a PDF (or the reverse) is\n`415 unsupported_content_type`. Archives and compressed bodies are\nrefused the same way.\n\n**Limits.** XML at most 5 MiB (5,242,880 bytes), 64 levels deep,\n250,000 elements. PDF at most 20 MiB, 200 pages and 20 embedded\nfiles; the embedded invoice XML at most 5 MiB; 25 MiB of decoded\nattachment data in total; 256 MiB of compressed (Flate) content\ndecoded across the whole PDF. Over a byte limit is `413`; over any other\nprocessing limit is `422 processing_limit`, which is not a verdict on\nthe invoice. The XML deadline is 10 seconds and the hybrid deadline\n30 seconds; exceeding it is indeterminate (`504`).\n\n**Selection.** `ruleset` is `latest` (default) or an exact ruleset\nid.\n\n- With an exact id, the release supplies family, variant, syntax,\n document type and scope. Any selector also sent must equal the\n release's value, or the request is `422 selection_conflict`; the\n document must fit the release (`422 unsupported_document_type`,\n `422 family_mismatch`).\n- With `latest`, the family is the one requested or, without\n `family`, the one the document declares\n (`selection_method: detected`); an undeclared or unknown family is\n `422 family_undetected`. A requested family the document\n contradicts is `422 family_mismatch`, and the Problem's\n `detected` says what the document declares, so a client can offer\n the right tool; the document is never validated under the wrong\n family. The variant is the one the document declares; a variant\n Ironfang recognises but does not validate is\n `422 unsupported_variant`, never a fallback to a weaker profile.\n- `scope` defaults to `xml` for XML and `hybrid_pdf` for a PDF.\n Any other combination is `422 scope_unavailable`. To inspect only\n the XML inside a PDF, extract it explicitly\n (`POST /tools/v2/invoice/extract`) and validate that XML.\n\n**PDF inputs.** An encrypted PDF is `422 encrypted_pdf`. A PDF with\nno identifiable embedded invoice XML is `422 no_embedded_invoice`,\nand one with more than one plausible invoice XML is\n`422 ambiguous_embedded_invoice`: no attachment is ever chosen\narbitrarily. These three are uncharged. Everything wrong with an\nidentified embedded invoice - its name, relationship, media type,\nmetadata, PDF/A conformance, or the XML itself - is a finding in a\ncompleted validation.\n\n**Outcome.** `200` is always a verdict: `status: completed`,\n`outcome` `valid` or `invalid`, and every check that ran completed.\nA deterministic defect makes the outcome `invalid`, and checks it\nprevented are `skipped` with a reason. A timeout, an unavailable\nvalidator or an internal failure is a Problem with\n`outcome: indeterminate`; known findings are never presented as a\nverdict.\n\n**Usage.** One completed validation is one operation, whatever the\nscope; the checks inside it are not billed separately. As in V1, a\ncompleted validation is charged once its schema check (`xsd`)\nreached a verdict, passed or failed; a document that is not\nwell-formed XML ends before it and is not charged. Rejected\nrequests and indeterminate outcomes are not charged. An\nauthenticated verdict carries `operation_id` and `usage`, and is\nretained for 30 days as V1 results are; it is served only through\nV2, never through a V1 result, list or report.\n\n**Idempotency.** As V1, with the request identified by the input\nbytes (for a PDF, the PDF's own bytes), the selectors and the scope.\nA replay returns the original operation and its result, even if\n`latest` has since moved.\n\n**Findings.** At most 1,000 inline, ordered by the pipeline's layer\norder, then severity (`fatal`, `warning`, `information`), then\n`rule_id`, then location, then message. `findings_summary` states\nthe totals and whether truncation happened.\n\nSelect your invoice in Body: the XML, or a ZUGFeRD / Factur-X PDF with media_type set to application/pdf. The file is sent to Ironfang Finance for validation.", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "{{media_type}}" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "validate" ], "query": [ { "disabled": true, "key": "ruleset", "value": "{{ruleset}}" }, { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "variant", "value": "{{variant}}" }, { "disabled": true, "key": "document_type", "value": "{{document_type}}" }, { "disabled": true, "key": "scope", "value": "{{scope}}" } ], "raw": "{{base_url}}/v2/einvoices/validate" } }, "status": "Unprocessable Entity" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"https://ironfang.com/problems/free_allowance_exhausted\",\n \"title\": \"Free allowance used up\",\n \"status\": 429,\n \"detail\": \"This month's free allowance is used up. Enable paid usage in Billing to continue. The free allowance renews on 1 October 2026 (UTC).\",\n \"instance\": \"/finance/v2/einvoices/validate\",\n \"code\": \"free_allowance_exhausted\",\n \"request_id\": \"01a0d509-24aa-74ef-9a25-5db40e20f85b\",\n \"billing\": {\n \"product\": \"finance\",\n \"meter\": \"finance.validation\",\n \"reset_at\": \"2026-10-01T00:00:00Z\"\n }\n}", "code": 429, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "name": "429 The month's free validations are used up", "originalRequest": { "body": { "file": { "src": "" }, "mode": "file" }, "description": "**Body.** Send the document itself with `Content-Type`\n`application/xml`, `text/xml` or `application/pdf`, choosing with the\nquery parameters. Or send `multipart/form-data` with one `document`\npart (one of those media types) and an optional `options` part\nholding a JSON `ValidationOptions` object; query parameters are not\nread for multipart requests. The media type is a hint: the content\nis inspected, and an XML part holding a PDF (or the reverse) is\n`415 unsupported_content_type`. Archives and compressed bodies are\nrefused the same way.\n\n**Limits.** XML at most 5 MiB (5,242,880 bytes), 64 levels deep,\n250,000 elements. PDF at most 20 MiB, 200 pages and 20 embedded\nfiles; the embedded invoice XML at most 5 MiB; 25 MiB of decoded\nattachment data in total; 256 MiB of compressed (Flate) content\ndecoded across the whole PDF. Over a byte limit is `413`; over any other\nprocessing limit is `422 processing_limit`, which is not a verdict on\nthe invoice. The XML deadline is 10 seconds and the hybrid deadline\n30 seconds; exceeding it is indeterminate (`504`).\n\n**Selection.** `ruleset` is `latest` (default) or an exact ruleset\nid.\n\n- With an exact id, the release supplies family, variant, syntax,\n document type and scope. Any selector also sent must equal the\n release's value, or the request is `422 selection_conflict`; the\n document must fit the release (`422 unsupported_document_type`,\n `422 family_mismatch`).\n- With `latest`, the family is the one requested or, without\n `family`, the one the document declares\n (`selection_method: detected`); an undeclared or unknown family is\n `422 family_undetected`. A requested family the document\n contradicts is `422 family_mismatch`, and the Problem's\n `detected` says what the document declares, so a client can offer\n the right tool; the document is never validated under the wrong\n family. The variant is the one the document declares; a variant\n Ironfang recognises but does not validate is\n `422 unsupported_variant`, never a fallback to a weaker profile.\n- `scope` defaults to `xml` for XML and `hybrid_pdf` for a PDF.\n Any other combination is `422 scope_unavailable`. To inspect only\n the XML inside a PDF, extract it explicitly\n (`POST /tools/v2/invoice/extract`) and validate that XML.\n\n**PDF inputs.** An encrypted PDF is `422 encrypted_pdf`. A PDF with\nno identifiable embedded invoice XML is `422 no_embedded_invoice`,\nand one with more than one plausible invoice XML is\n`422 ambiguous_embedded_invoice`: no attachment is ever chosen\narbitrarily. These three are uncharged. Everything wrong with an\nidentified embedded invoice - its name, relationship, media type,\nmetadata, PDF/A conformance, or the XML itself - is a finding in a\ncompleted validation.\n\n**Outcome.** `200` is always a verdict: `status: completed`,\n`outcome` `valid` or `invalid`, and every check that ran completed.\nA deterministic defect makes the outcome `invalid`, and checks it\nprevented are `skipped` with a reason. A timeout, an unavailable\nvalidator or an internal failure is a Problem with\n`outcome: indeterminate`; known findings are never presented as a\nverdict.\n\n**Usage.** One completed validation is one operation, whatever the\nscope; the checks inside it are not billed separately. As in V1, a\ncompleted validation is charged once its schema check (`xsd`)\nreached a verdict, passed or failed; a document that is not\nwell-formed XML ends before it and is not charged. Rejected\nrequests and indeterminate outcomes are not charged. An\nauthenticated verdict carries `operation_id` and `usage`, and is\nretained for 30 days as V1 results are; it is served only through\nV2, never through a V1 result, list or report.\n\n**Idempotency.** As V1, with the request identified by the input\nbytes (for a PDF, the PDF's own bytes), the selectors and the scope.\nA replay returns the original operation and its result, even if\n`latest` has since moved.\n\n**Findings.** At most 1,000 inline, ordered by the pipeline's layer\norder, then severity (`fatal`, `warning`, `information`), then\n`rule_id`, then location, then message. `findings_summary` states\nthe totals and whether truncation happened.\n\nSelect your invoice in Body: the XML, or a ZUGFeRD / Factur-X PDF with media_type set to application/pdf. The file is sent to Ironfang Finance for validation.", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "{{media_type}}" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "validate" ], "query": [ { "disabled": true, "key": "ruleset", "value": "{{ruleset}}" }, { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "variant", "value": "{{variant}}" }, { "disabled": true, "key": "document_type", "value": "{{document_type}}" }, { "disabled": true, "key": "scope", "value": "{{scope}}" } ], "raw": "{{base_url}}/v2/einvoices/validate" } }, "status": "Too Many Requests" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"https://ironfang.com/problems/validation_timeout\",\n \"title\": \"Validation timed out\",\n \"status\": 504,\n \"detail\": \"Validation did not finish within the deadline. The outcome is indeterminate and nothing was charged.\",\n \"instance\": \"/finance/v2/einvoices/validate\",\n \"code\": \"validation_timeout\",\n \"request_id\": \"01a0d509-275c-765c-bc80-d9e77f65556c\",\n \"operation_id\": \"0192b3c4-5d6e-7f80-9a1b-2c3d4e5f6a7c\",\n \"outcome\": \"indeterminate\",\n \"usage_charged\": false\n}", "code": 504, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "name": "504 A hybrid validation that did not finish", "originalRequest": { "body": { "file": { "src": "" }, "mode": "file" }, "description": "**Body.** Send the document itself with `Content-Type`\n`application/xml`, `text/xml` or `application/pdf`, choosing with the\nquery parameters. Or send `multipart/form-data` with one `document`\npart (one of those media types) and an optional `options` part\nholding a JSON `ValidationOptions` object; query parameters are not\nread for multipart requests. The media type is a hint: the content\nis inspected, and an XML part holding a PDF (or the reverse) is\n`415 unsupported_content_type`. Archives and compressed bodies are\nrefused the same way.\n\n**Limits.** XML at most 5 MiB (5,242,880 bytes), 64 levels deep,\n250,000 elements. PDF at most 20 MiB, 200 pages and 20 embedded\nfiles; the embedded invoice XML at most 5 MiB; 25 MiB of decoded\nattachment data in total; 256 MiB of compressed (Flate) content\ndecoded across the whole PDF. Over a byte limit is `413`; over any other\nprocessing limit is `422 processing_limit`, which is not a verdict on\nthe invoice. The XML deadline is 10 seconds and the hybrid deadline\n30 seconds; exceeding it is indeterminate (`504`).\n\n**Selection.** `ruleset` is `latest` (default) or an exact ruleset\nid.\n\n- With an exact id, the release supplies family, variant, syntax,\n document type and scope. Any selector also sent must equal the\n release's value, or the request is `422 selection_conflict`; the\n document must fit the release (`422 unsupported_document_type`,\n `422 family_mismatch`).\n- With `latest`, the family is the one requested or, without\n `family`, the one the document declares\n (`selection_method: detected`); an undeclared or unknown family is\n `422 family_undetected`. A requested family the document\n contradicts is `422 family_mismatch`, and the Problem's\n `detected` says what the document declares, so a client can offer\n the right tool; the document is never validated under the wrong\n family. The variant is the one the document declares; a variant\n Ironfang recognises but does not validate is\n `422 unsupported_variant`, never a fallback to a weaker profile.\n- `scope` defaults to `xml` for XML and `hybrid_pdf` for a PDF.\n Any other combination is `422 scope_unavailable`. To inspect only\n the XML inside a PDF, extract it explicitly\n (`POST /tools/v2/invoice/extract`) and validate that XML.\n\n**PDF inputs.** An encrypted PDF is `422 encrypted_pdf`. A PDF with\nno identifiable embedded invoice XML is `422 no_embedded_invoice`,\nand one with more than one plausible invoice XML is\n`422 ambiguous_embedded_invoice`: no attachment is ever chosen\narbitrarily. These three are uncharged. Everything wrong with an\nidentified embedded invoice - its name, relationship, media type,\nmetadata, PDF/A conformance, or the XML itself - is a finding in a\ncompleted validation.\n\n**Outcome.** `200` is always a verdict: `status: completed`,\n`outcome` `valid` or `invalid`, and every check that ran completed.\nA deterministic defect makes the outcome `invalid`, and checks it\nprevented are `skipped` with a reason. A timeout, an unavailable\nvalidator or an internal failure is a Problem with\n`outcome: indeterminate`; known findings are never presented as a\nverdict.\n\n**Usage.** One completed validation is one operation, whatever the\nscope; the checks inside it are not billed separately. As in V1, a\ncompleted validation is charged once its schema check (`xsd`)\nreached a verdict, passed or failed; a document that is not\nwell-formed XML ends before it and is not charged. Rejected\nrequests and indeterminate outcomes are not charged. An\nauthenticated verdict carries `operation_id` and `usage`, and is\nretained for 30 days as V1 results are; it is served only through\nV2, never through a V1 result, list or report.\n\n**Idempotency.** As V1, with the request identified by the input\nbytes (for a PDF, the PDF's own bytes), the selectors and the scope.\nA replay returns the original operation and its result, even if\n`latest` has since moved.\n\n**Findings.** At most 1,000 inline, ordered by the pipeline's layer\norder, then severity (`fatal`, `warning`, `information`), then\n`rule_id`, then location, then message. `findings_summary` states\nthe totals and whether truncation happened.\n\nSelect your invoice in Body: the XML, or a ZUGFeRD / Factur-X PDF with media_type set to application/pdf. The file is sent to Ironfang Finance for validation.", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "{{media_type}}" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "validate" ], "query": [ { "disabled": true, "key": "ruleset", "value": "{{ruleset}}" }, { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "variant", "value": "{{variant}}" }, { "disabled": true, "key": "document_type", "value": "{{document_type}}" }, { "disabled": true, "key": "scope", "value": "{{scope}}" } ], "raw": "{{base_url}}/v2/einvoices/validate" } }, "status": "Gateway Timeout" } ] } ], "name": "Validation" }, { "description": "The immutable releases a validation can name.", "item": [ { "name": "List the releases a V2 validation can name", "request": { "description": "The `scheduled`, `sendable` and `historical` releases of every\nfamily. Exactly one `sendable` release per capability (family,\nvariant, syntax, document type and scope) carries `latest: true`: the\none `ruleset=latest` resolves to now. A release of a family in this\nlist is the only evidence that the family is supported.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "rulesets" ], "query": [ { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "variant", "value": "{{variant}}" }, { "disabled": true, "key": "document_type", "value": "{{document_type}}" }, { "disabled": true, "key": "scope", "value": "{{scope}}" }, { "disabled": true, "key": "operation", "value": "{{operation}}" }, { "disabled": true, "key": "state", "value": "{{state}}" } ], "raw": "{{base_url}}/v2/einvoices/rulesets" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/ruleset-list/v2\",\n \"rulesets\": [\n {\n \"schema\": \"ironfang/finance/einvoice/ruleset/v2\",\n \"id\": \"fwrs_example_xrechnung_cii_invoice\",\n \"state\": \"sendable\",\n \"latest\": true,\n \"family\": \"xrechnung\",\n \"variant\": \"core\",\n \"syntax\": \"cii-d16b\",\n \"document_type\": \"invoice\",\n \"scope\": \"xml\",\n \"operations\": [\n \"validate\"\n ],\n \"official_release\": \"3.0.2\",\n \"technical_release\": \"2026-08-31\",\n \"en16931_release\": \"1.3.16\",\n \"layers\": [\n \"input\",\n \"xml\",\n \"xsd\",\n \"en16931\",\n \"xrechnung\"\n ],\n \"artifacts\": [\n {\n \"layer\": \"xsd\",\n \"role\": \"entry\",\n \"sha256\": \"9999999999999999999999999999999999999999999999999999999999999999\",\n \"licence\": \"NOASSERTION\",\n \"licence_status\": \"no-raw-redistribution\",\n \"source_url\": \"https://xeinkauf.de/xrechnung/versionen-und-bundles/\"\n },\n {\n \"layer\": \"xsd\",\n \"role\": \"dependency\",\n \"sha256\": \"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\n \"licence\": \"NOASSERTION\",\n \"licence_status\": \"no-raw-redistribution\",\n \"source_url\": \"https://xeinkauf.de/xrechnung/versionen-und-bundles/\"\n },\n {\n \"layer\": \"en16931\",\n \"role\": \"entry\",\n \"sha256\": \"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\n \"licence\": \"EUPL-1.2\",\n \"licence_status\": \"notice-required\",\n \"source_url\": \"https://xeinkauf.de/xrechnung/versionen-und-bundles/\"\n },\n {\n \"layer\": \"xrechnung\",\n \"role\": \"entry\",\n \"sha256\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n \"licence\": \"Apache-2.0\",\n \"licence_status\": \"permissive\",\n \"source_url\": \"https://xeinkauf.de/xrechnung/versionen-und-bundles/\"\n },\n {\n \"layer\": \"xrechnung\",\n \"role\": \"dependency\",\n \"sha256\": \"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n \"licence\": \"Apache-2.0\",\n \"licence_status\": \"permissive\",\n \"source_url\": \"https://xeinkauf.de/xrechnung/versionen-und-bundles/\"\n }\n ],\n \"manifest_sha256\": \"0000000000000000000000000000000000000000000000000000000000000001\",\n \"engine\": {\n \"name\": \"phive-xml 12.1.0 / Saxon-HE 12.10 / XRechnung bundle 2026-08-31\",\n \"image_digest\": \"sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\"\n },\n \"valid_from\": \"2026-09-01T00:00:00Z\",\n \"valid_until\": \"2027-07-31T23:59:59Z\",\n \"published_on\": \"2026-08-31\",\n \"sources\": [\n \"https://xeinkauf.de/xrechnung/versionen-und-bundles/\",\n \"https://projekte.kosit.org/xrechnung/validator-configuration-xrechnung/-/releases/v2026-08-31\"\n ]\n },\n {\n \"schema\": \"ironfang/finance/einvoice/ruleset/v2\",\n \"id\": \"fwrs_example_xrechnung_ubl_invoice\",\n \"state\": \"sendable\",\n \"latest\": true,\n \"family\": \"xrechnung\",\n \"variant\": \"core\",\n \"syntax\": \"ubl-2.1\",\n \"document_type\": \"invoice\",\n \"scope\": \"xml\",\n \"operations\": [\n \"validate\"\n ],\n \"official_release\": \"3.0.2\",\n \"technical_release\": \"2026-08-31\",\n \"en16931_release\": \"1.3.16\",\n \"layers\": [\n \"input\",\n \"xml\",\n \"xsd\",\n \"en16931\",\n \"xrechnung\"\n ],\n \"artifacts\": [\n {\n \"layer\": \"xsd\",\n \"role\": \"entry\",\n \"sha256\": \"8888888888888888888888888888888888888888888888888888888888888888\",\n \"licence\": \"NOASSERTION\",\n \"licence_status\": \"no-raw-redistribution\",\n \"source_url\": \"https://xeinkauf.de/xrechnung/versionen-und-bundles/\"\n },\n {\n \"layer\": \"xsd\",\n \"role\": \"dependency\",\n \"sha256\": \"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\n \"licence\": \"NOASSERTION\",\n \"licence_status\": \"no-raw-redistribution\",\n \"source_url\": \"https://xeinkauf.de/xrechnung/versionen-und-bundles/\"\n },\n {\n \"layer\": \"en16931\",\n \"role\": \"entry\",\n \"sha256\": \"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\n \"licence\": \"EUPL-1.2\",\n \"licence_status\": \"notice-required\",\n \"source_url\": \"https://xeinkauf.de/xrechnung/versionen-und-bundles/\"\n },\n {\n \"layer\": \"xrechnung\",\n \"role\": \"entry\",\n \"sha256\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n \"licence\": \"Apache-2.0\",\n \"licence_status\": \"permissive\",\n \"source_url\": \"https://xeinkauf.de/xrechnung/versionen-und-bundles/\"\n },\n {\n \"layer\": \"xrechnung\",\n \"role\": \"dependency\",\n \"sha256\": \"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n \"licence\": \"Apache-2.0\",\n \"licence_status\": \"permissive\",\n \"source_url\": \"https://xeinkauf.de/xrechnung/versionen-und-bundles/\"\n }\n ],\n \"manifest_sha256\": \"0000000000000000000000000000000000000000000000000000000000000001\",\n \"engine\": {\n \"name\": \"phive-xml 12.1.0 / Saxon-HE 12.10 / XRechnung bundle 2026-08-31\",\n \"image_digest\": \"sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\"\n },\n \"valid_from\": \"2026-09-01T00:00:00Z\",\n \"valid_until\": \"2027-07-31T23:59:59Z\",\n \"published_on\": \"2026-08-31\",\n \"sources\": [\n \"https://xeinkauf.de/xrechnung/versionen-und-bundles/\",\n \"https://projekte.kosit.org/xrechnung/validator-configuration-xrechnung/-/releases/v2026-08-31\"\n ]\n }\n ]\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "200 The XRechnung releases", "originalRequest": { "description": "The `scheduled`, `sendable` and `historical` releases of every\nfamily. Exactly one `sendable` release per capability (family,\nvariant, syntax, document type and scope) carries `latest: true`: the\none `ruleset=latest` resolves to now. A release of a family in this\nlist is the only evidence that the family is supported.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "rulesets" ], "query": [ { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "variant", "value": "{{variant}}" }, { "disabled": true, "key": "document_type", "value": "{{document_type}}" }, { "disabled": true, "key": "scope", "value": "{{scope}}" }, { "disabled": true, "key": "operation", "value": "{{operation}}" }, { "disabled": true, "key": "state", "value": "{{state}}" } ], "raw": "{{base_url}}/v2/einvoices/rulesets" } }, "status": "OK" } ] }, { "name": "One immutable release and its pipeline", "request": { "description": "One release by id, in any public state (scheduled, sendable or historical), with its pipeline, layers and pinned engine. A release never changes once published; results name the release that produced them, so this is how to see exactly what checked a document.", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "rulesets", "{{id}}" ], "query": [], "raw": "{{base_url}}/v2/einvoices/rulesets/{{id}}" } }, "response": [] } ], "name": "Rulesets" }, { "description": "Retained results, V1 and V2 together.", "item": [ { "name": "List retained results, V1 and V2 together", "request": { "description": "A page of the organisation's retained results, newest first:\nvalidations and generations made through V1 and validations made\nthrough V2, each saying which API made it (`api_version`), the\nschema of its retained document (`result_schema`) and its family.\n`total` counts every matching record, expired and deleted ones\nincluded; names are hidden after expiry or deletion and cannot\nmatch `q`. Pass `next_cursor` as `cursor` for the next page.\n\nV1's own result list shows only V1 results: a V2 result is not a\ndocument its schema describes.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "results" ], "query": [ { "disabled": true, "key": "cursor", "value": "{{cursor}}" }, { "disabled": true, "key": "limit", "value": "{{limit}}" }, { "disabled": true, "key": "kind", "value": "{{kind}}" }, { "disabled": true, "key": "outcome", "value": "{{outcome}}" }, { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "api_version", "value": "{{api_version}}" }, { "disabled": true, "key": "ruleset", "value": "{{ruleset}}" }, { "disabled": true, "key": "q", "value": "{{q}}" }, { "disabled": true, "key": "operation_id", "value": "{{operation_id}}" } ], "raw": "{{base_url}}/v2/einvoices/results" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/result-list/v2\",\n \"results\": [\n {\n \"operation_id\": \"0192a3b4-7c5d-7e6f-8a9b-0c1d2e3f4a5b\",\n \"kind\": \"validate\",\n \"api_version\": \"v2\",\n \"result_schema\": \"ironfang/finance/einvoice/validation-result/v2\",\n \"family\": \"xrechnung\",\n \"outcome\": \"invalid\",\n \"ruleset_id\": \"fwrs_xrechnung_3_0_2_cii_invoice_2026_08_31\",\n \"created_at\": \"2026-09-24T09:15:02.311Z\",\n \"expires_at\": \"2026-10-24T09:15:02.311Z\",\n \"available\": true\n },\n {\n \"operation_id\": \"0192a3a1-11e2-7f34-9a56-7b8c9d0e1f2a\",\n \"kind\": \"validate\",\n \"api_version\": \"v1\",\n \"result_schema\": \"financewolf/einvoice/validation-result/v1\",\n \"family\": \"peppol-bis-billing-3\",\n \"outcome\": \"valid\",\n \"ruleset_id\": \"fwrs_bis3_billing_invoice_2026_5_r4\",\n \"created_at\": \"2026-09-23T16:40:57.004Z\",\n \"expires_at\": \"2026-10-23T16:40:57.004Z\",\n \"available\": true,\n \"display_name\": \"INV-2026-0192.xml\"\n }\n ],\n \"next_cursor\": \"MjAyNi0wOS0yM1QxNjo0MDo1Ny4wMDRafDAxOTJhM2ExLTExZTItN2YzNC05YTU2LTdiOGM5ZDBlMWYyYQ\",\n \"total\": 2,\n \"retention_days\": 30\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "200 A V2 XRechnung validation beside a V1 Peppol one", "originalRequest": { "description": "A page of the organisation's retained results, newest first:\nvalidations and generations made through V1 and validations made\nthrough V2, each saying which API made it (`api_version`), the\nschema of its retained document (`result_schema`) and its family.\n`total` counts every matching record, expired and deleted ones\nincluded; names are hidden after expiry or deletion and cannot\nmatch `q`. Pass `next_cursor` as `cursor` for the next page.\n\nV1's own result list shows only V1 results: a V2 result is not a\ndocument its schema describes.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "results" ], "query": [ { "disabled": true, "key": "cursor", "value": "{{cursor}}" }, { "disabled": true, "key": "limit", "value": "{{limit}}" }, { "disabled": true, "key": "kind", "value": "{{kind}}" }, { "disabled": true, "key": "outcome", "value": "{{outcome}}" }, { "disabled": true, "key": "family", "value": "{{family}}" }, { "disabled": true, "key": "api_version", "value": "{{api_version}}" }, { "disabled": true, "key": "ruleset", "value": "{{ruleset}}" }, { "disabled": true, "key": "q", "value": "{{q}}" }, { "disabled": true, "key": "operation_id", "value": "{{operation_id}}" } ], "raw": "{{base_url}}/v2/einvoices/results" } }, "status": "OK" } ] }, { "name": "One retained result, in the schema it was made under", "request": { "description": "The exact retained document, byte for byte as it was first\nreturned: a V2 validation's `ironfang/finance/einvoice/validation-result/v2`,\nor, for an operation made through V1, V1's\n`financewolf/einvoice/validation-result/v1` or\n`financewolf/einvoice/generation-result/v1`, which the V1 contract\ndocuments. Branch on `schema`. Reading a result never validates or\ncharges again.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "results", "{{id}}" ], "query": [], "raw": "{{base_url}}/v2/einvoices/results/{{id}}" } }, "response": [] }, { "name": "Erase one retained result now", "request": { "description": "Erases the retained document and its name, V1 or V2, before its\n30 days are up. Deleting an already erased or expired result\nanswers `204` again. The operation record stays, so a replay under\nits Idempotency-Key answers `410 result_gone` and never runs or\ncharges again.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "results", "{{id}}" ], "query": [], "raw": "{{base_url}}/v2/einvoices/results/{{id}}" } }, "response": [] } ], "name": "Results" }, { "description": "Durable validation jobs and batches, V1 and V2 together.", "item": [ { "name": "List batches, V1 and V2 together", "request": { "description": "A page of the organisation's batches, newest first, made through V1\nor V2 (`api_version`). Pass `next_cursor` as `cursor` for the next\npage. V1's own list shows V1 batches only.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "batches" ], "query": [ { "disabled": true, "key": "cursor", "value": "{{cursor}}" }, { "disabled": true, "key": "limit", "value": "{{limit}}" }, { "disabled": true, "key": "api_version", "value": "{{api_version}}" } ], "raw": "{{base_url}}/v2/einvoices/batches" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/batch-list/v2\",\n \"batches\": [\n {\n \"id\": \"019c1a2b-3c4d-7e5f-8a6b-0000000000b1\",\n \"api_version\": \"v2\",\n \"status\": \"partial\",\n \"created_at\": \"2026-09-25T11:05:00Z\",\n \"counts\": { \"queued\": 0, \"running\": 0, \"completed\": 1, \"failed\": 1, \"cancelled\": 0 },\n \"job_count\": 2\n },\n {\n \"id\": \"019c1a2b-3c4d-7e5f-8a6b-0000000000b0\",\n \"api_version\": \"v1\",\n \"status\": \"completed\",\n \"created_at\": \"2026-09-24T16:20:00Z\",\n \"counts\": { \"queued\": 0, \"running\": 0, \"completed\": 3, \"failed\": 0, \"cancelled\": 0 },\n \"job_count\": 3\n }\n ]\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "200 A V2 batch beside a V1 one", "originalRequest": { "description": "A page of the organisation's batches, newest first, made through V1\nor V2 (`api_version`). Pass `next_cursor` as `cursor` for the next\npage. V1's own list shows V1 batches only.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "batches" ], "query": [ { "disabled": true, "key": "cursor", "value": "{{cursor}}" }, { "disabled": true, "key": "limit", "value": "{{limit}}" }, { "disabled": true, "key": "api_version", "value": "{{api_version}}" } ], "raw": "{{base_url}}/v2/einvoices/batches" } }, "status": "OK" } ] }, { "name": "Queue 1 to 100 validations as one batch", "request": { "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\"jobs\":[{\"document_base64\":\"{{document_base64}}\",\"media_type\":\"{{media_type}}\",\"options\":{\"ruleset\":\"{{ruleset}}\"}}]}" }, "description": "Accepts 1 to 100 jobs together, all or none: a job that would be\nrefused refuses the batch, and the Problem's `detail` names it by\nposition (`Job 3: ...`), as `errors[].field` does (`jobs[3].options`).\nThe documents together are at most 25 MiB (26,214,400 bytes) and the\nenvelope at most 36 MiB. PDFs are inspected on acceptance, within the\n30-second hybrid deadline for the whole batch; a batch that cannot\nbe is `504 validation_timeout` and nothing is queued, so send fewer\nPDFs at once. Each job then runs, is charged and is retained on its\nown.\n\n**Idempotency.** An `Idempotency-Key` names the whole batch: the\nsame key and envelope return the original batch (`200`), a\ndifferent envelope `409 idempotency_conflict`. Keys are V2's own,\napart from V1 batches and from synchronous validation.\n", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "application/json" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "batches" ], "query": [], "raw": "{{base_url}}/v2/einvoices/batches" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/batch/v2\",\n \"id\": \"019c1a2b-3c4d-7e5f-8a6b-0000000000b1\",\n \"api_version\": \"v2\",\n \"status\": \"queued\",\n \"created_at\": \"2026-09-25T11:05:00Z\",\n \"counts\": { \"queued\": 2, \"running\": 0, \"completed\": 0, \"failed\": 0, \"cancelled\": 0 },\n \"jobs\": [\n {\n \"schema\": \"ironfang/finance/einvoice/job/v2\",\n \"id\": \"019c1a2b-3c4d-7e5f-8a6b-0000000000a2\",\n \"operation_id\": \"019c1a2b-3c4d-7e5f-8a6b-000000000012\",\n \"batch_id\": \"019c1a2b-3c4d-7e5f-8a6b-0000000000b1\",\n \"position\": 0,\n \"api_version\": \"v2\",\n \"operation\": \"validate\",\n \"status\": \"queued\",\n \"attempts\": 0,\n \"ruleset_id\": \"fwrs_example_zugferd_en16931_invoice_pdf\",\n \"engine_image_digest\": \"sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\",\n \"usage_charged\": false,\n \"result_available\": false,\n \"created_at\": \"2026-09-25T11:05:00Z\",\n \"expires_at\": \"2026-09-26T11:05:00Z\"\n },\n {\n \"schema\": \"ironfang/finance/einvoice/job/v2\",\n \"id\": \"019c1a2b-3c4d-7e5f-8a6b-0000000000a3\",\n \"operation_id\": \"019c1a2b-3c4d-7e5f-8a6b-000000000013\",\n \"batch_id\": \"019c1a2b-3c4d-7e5f-8a6b-0000000000b1\",\n \"position\": 1,\n \"api_version\": \"v2\",\n \"operation\": \"validate\",\n \"status\": \"queued\",\n \"attempts\": 0,\n \"ruleset_id\": \"fwrs_example_xrechnung_ubl_invoice\",\n \"engine_image_digest\": \"sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\",\n \"usage_charged\": false,\n \"result_available\": false,\n \"created_at\": \"2026-09-25T11:05:00Z\",\n \"expires_at\": \"2026-09-26T11:05:00Z\"\n }\n ]\n}", "code": 202, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "202 A ZUGFeRD PDF and an XRechnung XML, queued together", "originalRequest": { "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\"jobs\":[{\"document_base64\":\"{{document_base64}}\",\"media_type\":\"{{media_type}}\",\"options\":{\"ruleset\":\"{{ruleset}}\"}}]}" }, "description": "Accepts 1 to 100 jobs together, all or none: a job that would be\nrefused refuses the batch, and the Problem's `detail` names it by\nposition (`Job 3: ...`), as `errors[].field` does (`jobs[3].options`).\nThe documents together are at most 25 MiB (26,214,400 bytes) and the\nenvelope at most 36 MiB. PDFs are inspected on acceptance, within the\n30-second hybrid deadline for the whole batch; a batch that cannot\nbe is `504 validation_timeout` and nothing is queued, so send fewer\nPDFs at once. Each job then runs, is charged and is retained on its\nown.\n\n**Idempotency.** An `Idempotency-Key` names the whole batch: the\nsame key and envelope return the original batch (`200`), a\ndifferent envelope `409 idempotency_conflict`. Keys are V2's own,\napart from V1 batches and from synchronous validation.\n", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "application/json" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "batches" ], "query": [], "raw": "{{base_url}}/v2/einvoices/batches" } }, "status": "Accepted" } ] }, { "name": "One batch", "request": { "description": "One batch, V1's or V2's, with every job in position order and the\ncounts by status. `partial` means every job finished, not all the\nsame way.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "batches", "{{id}}" ], "query": [], "raw": "{{base_url}}/v2/einvoices/batches/{{id}}" } }, "response": [] }, { "name": "Cancel a batch", "request": { "description": "Cancels every unfinished job in the batch, as cancelling each\nwould; finished jobs keep their results. The body is empty.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "batches", "{{id}}", "cancel" ], "query": [], "raw": "{{base_url}}/v2/einvoices/batches/{{id}}/cancel" } }, "response": [] }, { "name": "List jobs, V1 and V2 together", "request": { "description": "A page of the organisation's jobs, newest first, made through V1\nor V2 (`api_version`). Pass `next_cursor` as `cursor` for the next\npage. V1's own list shows V1 jobs only.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "jobs" ], "query": [ { "disabled": true, "key": "cursor", "value": "{{cursor}}" }, { "disabled": true, "key": "limit", "value": "{{limit}}" }, { "disabled": true, "key": "status", "value": "{{status}}" }, { "disabled": true, "key": "api_version", "value": "{{api_version}}" } ], "raw": "{{base_url}}/v2/einvoices/jobs" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/job-list/v2\",\n \"jobs\": [\n {\n \"schema\": \"ironfang/finance/einvoice/job/v2\",\n \"id\": \"019c1a2b-3c4d-7e5f-8a6b-0000000000a1\",\n \"operation_id\": \"019c1a2b-3c4d-7e5f-8a6b-000000000011\",\n \"position\": 0,\n \"api_version\": \"v2\",\n \"operation\": \"validate\",\n \"status\": \"completed\",\n \"outcome\": \"invalid\",\n \"attempts\": 1,\n \"ruleset_id\": \"fwrs_example_zugferd_en16931_invoice_pdf\",\n \"engine_image_digest\": \"sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\",\n \"usage_charged\": true,\n \"result_available\": true,\n \"result_url\": \"/finance/v2/einvoices/results/019c1a2b-3c4d-7e5f-8a6b-000000000011\",\n \"created_at\": \"2026-09-25T11:00:00Z\",\n \"expires_at\": \"2026-09-26T11:00:00Z\",\n \"finished_at\": \"2026-09-25T11:00:04Z\"\n },\n {\n \"schema\": \"ironfang/finance/einvoice/job/v2\",\n \"id\": \"019c1a2b-3c4d-7e5f-8a6b-0000000000a0\",\n \"operation_id\": \"019c1a2b-3c4d-7e5f-8a6b-000000000010\",\n \"position\": 0,\n \"api_version\": \"v1\",\n \"operation\": \"validate\",\n \"status\": \"cancelled\",\n \"outcome\": \"indeterminate\",\n \"failure_code\": \"job_cancelled\",\n \"attempts\": 0,\n \"ruleset_id\": \"fwrs_example_bis3_billing_invoice\",\n \"engine_image_digest\": \"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\n \"usage_charged\": false,\n \"result_available\": false,\n \"created_at\": \"2026-09-25T10:58:00Z\",\n \"expires_at\": \"2026-09-26T10:58:00Z\",\n \"finished_at\": \"2026-09-25T10:58:30Z\"\n }\n ],\n \"next_cursor\": \"MjAyNi0wOS0yNVQxMDo1ODowMFp8MDE5YzFhMmItM2M0ZC03ZTVmLThhNmItMDAwMDAwMDAwMGEw\"\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "200 A V2 job beside a V1 one", "originalRequest": { "description": "A page of the organisation's jobs, newest first, made through V1\nor V2 (`api_version`). Pass `next_cursor` as `cursor` for the next\npage. V1's own list shows V1 jobs only.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "jobs" ], "query": [ { "disabled": true, "key": "cursor", "value": "{{cursor}}" }, { "disabled": true, "key": "limit", "value": "{{limit}}" }, { "disabled": true, "key": "status", "value": "{{status}}" }, { "disabled": true, "key": "api_version", "value": "{{api_version}}" } ], "raw": "{{base_url}}/v2/einvoices/jobs" } }, "status": "OK" } ] }, { "name": "Queue one validation", "request": { "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\"document_base64\":\"{{document_base64}}\",\"media_type\":\"{{media_type}}\",\"options\":{\"ruleset\":\"{{ruleset}}\"}}" }, "description": "Queues one validation: `document_base64` holds the document's\nbytes, `media_type` says what they are (the content must agree, as\nin synchronous validation) and `options` are the synchronous\noptions. XML at most 5 MiB, a PDF at most 20 MiB; the envelope at\nmost 28 MiB.\n\n**Acceptance.** Every decision synchronous validation makes before\nit validates is made now: the document's content and size, the\nscope, a PDF's inspection and its embedded invoice, and the release\n`latest` or the ruleset id resolves to. A document it would refuse is\nrefused here with the same Problem, and nothing is queued or\ncharged. An accepted job is pinned to that release and its engines,\nand one validation is reserved on the billing account until the job\nfinishes: charged if it reaches a verdict, returned otherwise. A\nbatch is admitted whole or not at all.\n\n**Running.** The job runs through the same validation as\n`POST /v2/einvoices/validate`. Its result is a V2 validation result,\nread at `result_url` once the job is `completed`; its usage and its\nwebhook or S3 event (`ironfang/finance/einvoice/event/v2`, naming\n`job_id`) are a synchronous validation's. An unavailable engine or a\ntimeout is retried, up to 3 attempts; then the job is `failed`,\nindeterminate and uncharged. The document is held encrypted until\nthe job finishes, at most 24 hours (`expires_at`), then erased.\n\n**Queue.** An organisation holds at most 100 unfinished jobs and\n25 MiB of their documents; more is `429 quota_exhausted`.\n\n**Idempotency.** As synchronous validation, with the request\nidentified by the document's bytes, the options and the scope. Keys\nare V2's own, apart from V1 jobs and from synchronous validation.\n", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "application/json" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "jobs" ], "query": [], "raw": "{{base_url}}/v2/einvoices/jobs" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/job/v2\",\n \"id\": \"019c1a2b-3c4d-7e5f-8a6b-0000000000a1\",\n \"operation_id\": \"019c1a2b-3c4d-7e5f-8a6b-000000000011\",\n \"position\": 0,\n \"api_version\": \"v2\",\n \"operation\": \"validate\",\n \"status\": \"queued\",\n \"attempts\": 0,\n \"ruleset_id\": \"fwrs_example_zugferd_en16931_invoice_pdf\",\n \"engine_image_digest\": \"sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\",\n \"usage_charged\": false,\n \"result_available\": false,\n \"created_at\": \"2026-09-25T11:00:00Z\",\n \"expires_at\": \"2026-09-26T11:00:00Z\"\n}", "code": 202, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "202 A ZUGFeRD PDF queued", "originalRequest": { "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\"document_base64\":\"{{document_base64}}\",\"media_type\":\"{{media_type}}\",\"options\":{\"ruleset\":\"{{ruleset}}\"}}" }, "description": "Queues one validation: `document_base64` holds the document's\nbytes, `media_type` says what they are (the content must agree, as\nin synchronous validation) and `options` are the synchronous\noptions. XML at most 5 MiB, a PDF at most 20 MiB; the envelope at\nmost 28 MiB.\n\n**Acceptance.** Every decision synchronous validation makes before\nit validates is made now: the document's content and size, the\nscope, a PDF's inspection and its embedded invoice, and the release\n`latest` or the ruleset id resolves to. A document it would refuse is\nrefused here with the same Problem, and nothing is queued or\ncharged. An accepted job is pinned to that release and its engines,\nand one validation is reserved on the billing account until the job\nfinishes: charged if it reaches a verdict, returned otherwise. A\nbatch is admitted whole or not at all.\n\n**Running.** The job runs through the same validation as\n`POST /v2/einvoices/validate`. Its result is a V2 validation result,\nread at `result_url` once the job is `completed`; its usage and its\nwebhook or S3 event (`ironfang/finance/einvoice/event/v2`, naming\n`job_id`) are a synchronous validation's. An unavailable engine or a\ntimeout is retried, up to 3 attempts; then the job is `failed`,\nindeterminate and uncharged. The document is held encrypted until\nthe job finishes, at most 24 hours (`expires_at`), then erased.\n\n**Queue.** An organisation holds at most 100 unfinished jobs and\n25 MiB of their documents; more is `429 quota_exhausted`.\n\n**Idempotency.** As synchronous validation, with the request\nidentified by the document's bytes, the options and the scope. Keys\nare V2's own, apart from V1 jobs and from synchronous validation.\n", "header": [ { "key": "Accept", "value": "application/json" }, { "disabled": true, "key": "Idempotency-Key", "value": "{{Idempotency-Key}}" }, { "key": "Content-Type", "value": "application/json" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "jobs" ], "query": [], "raw": "{{base_url}}/v2/einvoices/jobs" } }, "status": "Accepted" } ] }, { "name": "One job", "request": { "description": "One job, V1's or V2's: its status, attempts, pinned release and\nengine, and once it has finished its outcome, usage and result.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "jobs", "{{id}}" ], "query": [], "raw": "{{base_url}}/v2/einvoices/jobs/{{id}}" } }, "response": [] }, { "name": "Cancel a job", "request": { "description": "Cancels an unfinished job: its operation ends indeterminate and\nuncharged, and its document is erased. A job that has finished is\nreturned unchanged. The body is empty.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "jobs", "{{id}}", "cancel" ], "query": [], "raw": "{{base_url}}/v2/einvoices/jobs/{{id}}/cancel" } }, "response": [] } ], "name": "Jobs" }, { "description": "Webhook and S3 deliveries of V1 and V2 events together.", "item": [ { "name": "List webhook and S3 deliveries, V1 and V2 events together", "request": { "description": "A page of the organisation's deliveries, newest first. A finished\noperation queues one event, and the event one delivery per enabled\ndestination (webhook or S3). An operation made through V1 carries\nthe `financewolf/einvoice/event/v1` event; one made through V2 the\n`ironfang/finance/einvoice/event/v2` event, whose `result_url` is\nunder `/finance/v2`. Each delivery says which (`api_version`); branch\non the event's `schema`. Pass `next_cursor` as `cursor` for the next\npage. Deliveries and events are kept for 30 days.\n\nV1's own delivery list shows deliveries of V1 events only.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "deliveries" ], "query": [ { "disabled": true, "key": "cursor", "value": "{{cursor}}" }, { "disabled": true, "key": "limit", "value": "{{limit}}" }, { "disabled": true, "key": "destination", "value": "{{destination}}" }, { "disabled": true, "key": "operation_id", "value": "{{operation_id}}" }, { "disabled": true, "key": "status", "value": "{{status}}" }, { "disabled": true, "key": "api_version", "value": "{{api_version}}" } ], "raw": "{{base_url}}/v2/einvoices/deliveries" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/delivery-list/v2\",\n \"deliveries\": [\n {\n \"id\": \"019c1a2b-3c4d-7e5f-8a6b-0000000000d2\",\n \"event_id\": \"019c1a2b-3c4d-7e5f-8a6b-7c8d9e0f1a2b\",\n \"operation_id\": \"019c1a2b-3c4d-7e5f-8a6b-000000000001\",\n \"destination_id\": \"019c0f00-0000-7000-8000-00000000d001\",\n \"api_version\": \"v2\",\n \"status\": \"delivered\",\n \"attempts\": 1,\n \"max_attempts\": 8,\n \"http_status\": 204,\n \"created_at\": \"2026-09-25T10:30:01Z\",\n \"expires_at\": \"2026-10-25T10:30:01Z\",\n \"finished_at\": \"2026-09-25T10:30:02Z\",\n \"next_attempt_at\": \"2026-09-25T10:30:01Z\",\n \"event\": {\n \"schema\": \"ironfang/finance/einvoice/event/v2\",\n \"id\": \"019c1a2b-3c4d-7e5f-8a6b-7c8d9e0f1a2b\",\n \"type\": \"einvoice.validation.completed\",\n \"created_at\": \"2026-09-25T10:30:01Z\",\n \"state_version\": 1,\n \"data\": {\n \"operation_id\": \"019c1a2b-3c4d-7e5f-8a6b-000000000001\",\n \"operation\": \"validate\",\n \"status\": \"completed\",\n \"outcome\": \"valid\",\n \"ruleset_id\": \"fwrs_xrechnung_3_0_2_ubl_invoice_2026_08_31\",\n \"family\": \"xrechnung\",\n \"variant\": \"core\",\n \"scope\": \"xml\",\n \"input_sha256\": \"4f9a1c1e8a2b6d7e3f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e\",\n \"usage_charged\": true,\n \"result_url\": \"/finance/v2/einvoices/results/019c1a2b-3c4d-7e5f-8a6b-000000000001\",\n \"artifacts\": [\n {\n \"name\": \"result.json\",\n \"content_type\": \"application/json\",\n \"sha256\": \"9b1d4e6a2c8f0e3b5d7a9c1e3f5b7d9a1c3e5f7b9d1a3c5e7f9b1d3a5c7e9f1b\",\n \"bytes\": 6120\n }\n ]\n }\n }\n },\n {\n \"id\": \"019c1a2a-0000-7000-8000-0000000000d1\",\n \"event_id\": \"019c1a2a-0000-7000-8000-00000000e001\",\n \"operation_id\": \"019c1a2a-0000-7000-8000-000000000002\",\n \"destination_id\": \"019c0f00-0000-7000-8000-00000000d001\",\n \"api_version\": \"v1\",\n \"status\": \"failed\",\n \"attempts\": 8,\n \"max_attempts\": 8,\n \"failure_code\": \"http_rejected\",\n \"http_status\": 500,\n \"created_at\": \"2026-09-25T09:12:04Z\",\n \"expires_at\": \"2026-10-25T09:12:04Z\",\n \"finished_at\": \"2026-09-25T10:02:11Z\",\n \"next_attempt_at\": \"2026-09-25T10:02:11Z\",\n \"event\": {\n \"schema\": \"financewolf/einvoice/event/v1\",\n \"id\": \"019c1a2a-0000-7000-8000-00000000e001\",\n \"type\": \"einvoice.validation.completed\",\n \"created_at\": \"2026-09-25T09:12:04Z\",\n \"state_version\": 1,\n \"data\": {\n \"operation_id\": \"019c1a2a-0000-7000-8000-000000000002\",\n \"operation\": \"validate\",\n \"status\": \"completed\",\n \"outcome\": \"invalid\",\n \"ruleset_id\": \"fwrs_bis3_billing_invoice_2026_5_r5\",\n \"input_sha256\": \"1c2b3a4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809\",\n \"usage_charged\": true,\n \"result_url\": \"/finance/v1/einvoices/results/019c1a2a-0000-7000-8000-000000000002\",\n \"artifacts\": [\n {\n \"name\": \"result.json\",\n \"content_type\": \"application/json\",\n \"sha256\": \"5e7f9b1d3a5c7e9f1b9b1d4e6a2c8f0e3b5d7a9c1e3f5b7d9a1c3e5f7b9d1a3c\",\n \"bytes\": 4410\n }\n ]\n }\n }\n }\n ]\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "200 A V2 validation's delivery beside a V1 one", "originalRequest": { "description": "A page of the organisation's deliveries, newest first. A finished\noperation queues one event, and the event one delivery per enabled\ndestination (webhook or S3). An operation made through V1 carries\nthe `financewolf/einvoice/event/v1` event; one made through V2 the\n`ironfang/finance/einvoice/event/v2` event, whose `result_url` is\nunder `/finance/v2`. Each delivery says which (`api_version`); branch\non the event's `schema`. Pass `next_cursor` as `cursor` for the next\npage. Deliveries and events are kept for 30 days.\n\nV1's own delivery list shows deliveries of V1 events only.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "deliveries" ], "query": [ { "disabled": true, "key": "cursor", "value": "{{cursor}}" }, { "disabled": true, "key": "limit", "value": "{{limit}}" }, { "disabled": true, "key": "destination", "value": "{{destination}}" }, { "disabled": true, "key": "operation_id", "value": "{{operation_id}}" }, { "disabled": true, "key": "status", "value": "{{status}}" }, { "disabled": true, "key": "api_version", "value": "{{api_version}}" } ], "raw": "{{base_url}}/v2/einvoices/deliveries" } }, "status": "OK" } ] }, { "name": "One delivery and every attempt made", "request": { "description": "One delivery of a V1 or a V2 event, with its event as queued and\nthe history of every attempt: when it started and finished, the\nHTTP status the destination answered and why it failed, if it did.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "deliveries", "{{id}}" ], "query": [], "raw": "{{base_url}}/v2/einvoices/deliveries/{{id}}" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/delivery/v2\",\n \"delivery\": {\n \"id\": \"019c1a2b-3c4d-7e5f-8a6b-0000000000d2\",\n \"event_id\": \"019c1a2b-3c4d-7e5f-8a6b-7c8d9e0f1a2b\",\n \"operation_id\": \"019c1a2b-3c4d-7e5f-8a6b-000000000001\",\n \"destination_id\": \"019c0f00-0000-7000-8000-00000000d001\",\n \"api_version\": \"v2\",\n \"status\": \"delivered\",\n \"attempts\": 1,\n \"max_attempts\": 8,\n \"http_status\": 204,\n \"created_at\": \"2026-09-25T10:30:01Z\",\n \"expires_at\": \"2026-10-25T10:30:01Z\",\n \"finished_at\": \"2026-09-25T10:30:02Z\",\n \"next_attempt_at\": \"2026-09-25T10:30:01Z\",\n \"event\": {\n \"schema\": \"ironfang/finance/einvoice/event/v2\",\n \"id\": \"019c1a2b-3c4d-7e5f-8a6b-7c8d9e0f1a2b\",\n \"type\": \"einvoice.validation.completed\",\n \"created_at\": \"2026-09-25T10:30:01Z\",\n \"state_version\": 1,\n \"data\": {\n \"operation_id\": \"019c1a2b-3c4d-7e5f-8a6b-000000000001\",\n \"operation\": \"validate\",\n \"status\": \"completed\",\n \"outcome\": \"valid\",\n \"ruleset_id\": \"fwrs_xrechnung_3_0_2_ubl_invoice_2026_08_31\",\n \"family\": \"xrechnung\",\n \"variant\": \"core\",\n \"scope\": \"xml\",\n \"input_sha256\": \"4f9a1c1e8a2b6d7e3f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e\",\n \"usage_charged\": true,\n \"result_url\": \"/finance/v2/einvoices/results/019c1a2b-3c4d-7e5f-8a6b-000000000001\",\n \"artifacts\": [\n {\n \"name\": \"result.json\",\n \"content_type\": \"application/json\",\n \"sha256\": \"9b1d4e6a2c8f0e3b5d7a9c1e3f5b7d9a1c3e5f7b9d1a3c5e7f9b1d3a5c7e9f1b\",\n \"bytes\": 6120\n }\n ]\n }\n }\n },\n \"history\": [\n {\n \"attempt\": 1,\n \"started_at\": \"2026-09-25T10:30:01Z\",\n \"finished_at\": \"2026-09-25T10:30:02Z\",\n \"http_status\": 204\n }\n ]\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "200 A delivered V2 event", "originalRequest": { "description": "One delivery of a V1 or a V2 event, with its event as queued and\nthe history of every attempt: when it started and finished, the\nHTTP status the destination answered and why it failed, if it did.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "deliveries", "{{id}}" ], "query": [], "raw": "{{base_url}}/v2/einvoices/deliveries/{{id}}" } }, "status": "OK" } ] }, { "name": "Retry a failed delivery", "request": { "description": "Grants a failed delivery a fresh ladder of up to eight attempts\n(32 in all), keeping every earlier attempt in its history. Only a\nfailed delivery to an enabled destination, whose event has not\nexpired, can be retried; anything else is `400 malformed_request`.\nThe body is empty.\n", "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "deliveries", "{{id}}", "retry" ], "query": [], "raw": "{{base_url}}/v2/einvoices/deliveries/{{id}}/retry" } }, "response": [] } ], "name": "Deliveries" }, { "description": "Signed reports of retained results, and their verification.", "item": [ { "name": "Download a signed report of a retained result", "request": { "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\"operation_id\":\"{{operation_id}}\"}" }, "description": "A ZIP binding the exact retained result, its complete findings and\nthe facts it records to an Ed25519 signature by Ironfang Finance.\nThe report is in its result's version. A V2 validation, XML or\nhybrid PDF, gets the V2 manifest\n(`ironfang/finance/einvoice/report-manifest/v2`): the input and, for\na PDF, its embedded XML by hash; the ruleset release with its\nfamily, variant, syntax, scope and manifest checksum (see the\nruleset's `manifest_sha256`); for\na hybrid release the PDF engine, PDF/A profiles and binding table it\npins; both engines by image digest; every check group and layer;\nwhat was not checked; and the release's rule artefacts by hash. A\nresult made through V1 gets exactly the bundle\n`POST /finance/v1/einvoices/reports` issues, V1 manifest and all.\n\nThe ZIP holds `manifest.json` (canonical), `signature.json`,\n`result.json` (the retained bytes), `findings.json` and a readable\n`report.html` derived from the manifest; with RFC 3161 timestamps\nconfigured, `timestamp.tsq` and `timestamp.tsr` too. V2 reports\nsign under their own domain and envelope schema, so a V1 signature\ncan never be read as V2 or the reverse. Both are signed by the keys\nat `GET /finance/v1/einvoices/reports/keys`.\n\nSend `operation_id` (and, for a V1 generation only, `include_pdf`)\nin a JSON body of at most 1024 bytes. A V2 result has no readable\nPDF: `include_pdf` on one is `503 report_unavailable`. Truncated\nfindings are `422 report_incomplete`. Nothing is validated or\ncharged again and nothing is stored; issuance time and signature may\ndiffer between downloads of one result, its facts never do. Expiry\nand deletion are checked again before the bundle is released.\nA signature does not certify compliance.\n", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "reports" ], "query": [], "raw": "{{base_url}}/v2/einvoices/reports" } }, "response": [] }, { "name": "Verify a signed report of either version, without an account", "request": { "auth": { "type": "noauth" }, "body": { "file": { "src": "" }, "mode": "file" }, "description": "Send the ZIP as `application/zip`. Ironfang Finance reads which\nmanifest it carries (V1's or V2's) and checks the canonical\nmanifest, the domain-separated signature against its own published\nkeys, every bound member's hash and length, the readable page and,\nwhere the report requires one, its RFC 3161 timestamp. It performs\nno network access, no validation and no retention. HTTP 200 answers\n`verified` true or false; verified means the report is intact and\nissued by a trusted key, not that the invoice is valid: read\n`invoice_outcome`. `report_schema` names the manifest; `family` and\n`scope` are the release's (a V1 report is Peppol BIS Billing 3 at\nXML scope). Unknown or revoked keys, tampering and unknown schemas\nfail. For a completely local check, `ironfang finance verify` does\nthe same with keys you obtain independently.\n\nBounded to 48 MiB compressed and expanded, nine members, two checks\nat a time per API process and 15 seconds. No query, compression or\nIdempotency-Key. Per-address anonymous limits apply.\n\nSelect the report ZIP in Body. It needs no credential.", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/zip" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "reports", "verify" ], "query": [], "raw": "{{base_url}}/v2/einvoices/reports/verify" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/report-verification/v2\",\n \"verified\": false,\n \"report_schema\": \"ironfang/finance/einvoice/report-manifest/v2\",\n \"signature\": \"verified\",\n \"artifact_hashes\": \"invalid\",\n \"timestamp\": \"not_present\",\n \"manifest_sha256\": \"b68af979fe12c70716d076935d37cac7d672048efcff5859b6fe789cd9a44f5f\",\n \"errors\": [\n \"report artifact hash or length mismatch\"\n ],\n \"claim\": \"This signature binds an Ironfang Finance validation observation to the listed bytes, ruleset release and engines. It does not revalidate the invoice, compare a PDF's visible content with its embedded XML, check digital signatures, prove delivery, certify legal or tax compliance, or guarantee recipient acceptance. The issuance time is a service assertion unless an independently trusted RFC 3161 timestamp is verified.\"\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "200 A report whose findings were changed after signing", "originalRequest": { "auth": { "type": "noauth" }, "body": { "file": { "src": "" }, "mode": "file" }, "description": "Send the ZIP as `application/zip`. Ironfang Finance reads which\nmanifest it carries (V1's or V2's) and checks the canonical\nmanifest, the domain-separated signature against its own published\nkeys, every bound member's hash and length, the readable page and,\nwhere the report requires one, its RFC 3161 timestamp. It performs\nno network access, no validation and no retention. HTTP 200 answers\n`verified` true or false; verified means the report is intact and\nissued by a trusted key, not that the invoice is valid: read\n`invoice_outcome`. `report_schema` names the manifest; `family` and\n`scope` are the release's (a V1 report is Peppol BIS Billing 3 at\nXML scope). Unknown or revoked keys, tampering and unknown schemas\nfail. For a completely local check, `ironfang finance verify` does\nthe same with keys you obtain independently.\n\nBounded to 48 MiB compressed and expanded, nine members, two checks\nat a time per API process and 15 seconds. No query, compression or\nIdempotency-Key. Per-address anonymous limits apply.\n\nSelect the report ZIP in Body. It needs no credential.", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/zip" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "reports", "verify" ], "query": [], "raw": "{{base_url}}/v2/einvoices/reports/verify" } }, "status": "OK" }, { "_postman_previewlanguage": "json", "body": "{\n \"schema\": \"ironfang/finance/einvoice/report-verification/v2\",\n \"verified\": true,\n \"report_schema\": \"ironfang/finance/einvoice/report-manifest/v2\",\n \"signature\": \"verified\",\n \"artifact_hashes\": \"verified\",\n \"timestamp\": \"not_present\",\n \"manifest_sha256\": \"b68af979fe12c70716d076935d37cac7d672048efcff5859b6fe789cd9a44f5f\",\n \"operation_id\": \"22222222-2222-4222-8222-222222222222\",\n \"invoice_outcome\": \"invalid\",\n \"ruleset_id\": \"fwrs_zugferd_2_5_2_en16931_invoice_pdf\",\n \"family\": \"zugferd-facturx\",\n \"scope\": \"hybrid_pdf\",\n \"key_id\": \"fw_ed25519_21fe31dfa154a261626bf854046fd2271b7bed4b6abe45aa58877ef47f9721b9\",\n \"errors\": [],\n \"claim\": \"This signature binds an Ironfang Finance validation observation to the listed bytes, ruleset release and engines. It does not revalidate the invoice, compare a PDF's visible content with its embedded XML, check digital signatures, prove delivery, certify legal or tax compliance, or guarantee recipient acceptance. The issuance time is a service assertion unless an independently trusted RFC 3161 timestamp is verified.\"\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "name": "200 A verified V2 report of a hybrid ZUGFeRD PDF", "originalRequest": { "auth": { "type": "noauth" }, "body": { "file": { "src": "" }, "mode": "file" }, "description": "Send the ZIP as `application/zip`. Ironfang Finance reads which\nmanifest it carries (V1's or V2's) and checks the canonical\nmanifest, the domain-separated signature against its own published\nkeys, every bound member's hash and length, the readable page and,\nwhere the report requires one, its RFC 3161 timestamp. It performs\nno network access, no validation and no retention. HTTP 200 answers\n`verified` true or false; verified means the report is intact and\nissued by a trusted key, not that the invoice is valid: read\n`invoice_outcome`. `report_schema` names the manifest; `family` and\n`scope` are the release's (a V1 report is Peppol BIS Billing 3 at\nXML scope). Unknown or revoked keys, tampering and unknown schemas\nfail. For a completely local check, `ironfang finance verify` does\nthe same with keys you obtain independently.\n\nBounded to 48 MiB compressed and expanded, nine members, two checks\nat a time per API process and 15 seconds. No query, compression or\nIdempotency-Key. Per-address anonymous limits apply.\n\nSelect the report ZIP in Body. It needs no credential.", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/zip" } ], "method": "POST", "url": { "host": [ "{{base_url}}" ], "path": [ "v2", "einvoices", "reports", "verify" ], "query": [], "raw": "{{base_url}}/v2/einvoices/reports/verify" } }, "status": "OK" } ] } ], "name": "Reports" } ], "variable": [ { "key": "Idempotency-Key", "type": "string", "value": "" }, { "key": "api_version", "type": "string", "value": "" }, { "key": "base_url", "type": "string", "value": "https://api.ironfang.com/finance" }, { "key": "cursor", "type": "string", "value": "" }, { "key": "destination", "type": "string", "value": "" }, { "key": "document_base64", "type": "string", "value": "" }, { "key": "document_type", "type": "string", "value": "" }, { "key": "family", "type": "string", "value": "" }, { "key": "id", "type": "string", "value": "" }, { "key": "kind", "type": "string", "value": "" }, { "key": "limit", "type": "string", "value": "" }, { "key": "media_type", "type": "string", "value": "application/xml" }, { "key": "operation", "type": "string", "value": "" }, { "key": "operation_id", "type": "string", "value": "" }, { "key": "outcome", "type": "string", "value": "" }, { "key": "q", "type": "string", "value": "" }, { "key": "ruleset", "type": "string", "value": "latest" }, { "key": "scope", "type": "string", "value": "" }, { "key": "state", "type": "string", "value": "" }, { "key": "status", "type": "string", "value": "" }, { "key": "variant", "type": "string", "value": "" } ] }