{"openapi":"3.1.0","info":{"title":"formkorrekt E-Invoice API","version":"1.0.0","description":"REST API for German e-invoices. POST /v1/invoices/validate checks XRechnung (UBL/CII) XML and ZUGFeRD PDF files against XRechnung and EN 16931 and returns each finding with its rule code and a fix hint. POST /v1/invoices/repair applies only deterministic corrections to XRechnung XML, and POST /v1/invoices/generate builds an XRechnung or ZUGFeRD file from JSON and checks it again before delivery. Authentication is a Bearer API key from the dashboard. AI agents can use the same API as tools through the MCP server at https://formkorrekt.com/mcp (setup: https://formkorrekt.com/docs/mcp).","termsOfService":"https://formkorrekt.com/agb","contact":{"name":"formkorrekt","url":"https://formkorrekt.com/impressum"},"x-logo":{"url":"https://formkorrekt.com/static/favicon/formkorrekt-512.png","altText":"formkorrekt logo"}},"paths":{"/v1/ping":{"get":{"tags":["Utility"],"summary":"Ping","description":"Authenticated no-op endpoint: verifies key + rate limit wiring.\nNot metered (no usage event) - products start metering in M2+.","operationId":"ping_v1_ping_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Ping V1 Ping Get"}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Utility"],"summary":"Ping Post","description":"POST variant so idempotency behaviour is testable end-to-end.","operationId":"ping_post_v1_ping_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Ping Post V1 Ping Post"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/invoices/validate":{"post":{"tags":["E-Invoices"],"summary":"Validate","operationId":"validate_v1_invoices_validate_post","requestBody":{"description":"The invoice as raw request body (XRechnung UBL/CII XML or ZUGFeRD PDF, max. 10 MB) or as multipart field `file`. Any other Content-Type is read as raw bytes as well.","content":{"application/xml":{"schema":{"type":"string","format":"binary"}},"text/xml":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"multipart/form-data":{"schema":{"properties":{"file":{"type":"string","format":"binary","description":"The invoice file."}},"type":"object","required":["file"]}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Free allowance used up and not enough credit (CREDIT_EXHAUSTED).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Payload Too Large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Unprocessable Entity","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/invoices/repair":{"post":{"tags":["E-Invoices"],"summary":"Repair","description":"Deterministic XML repair: 3 documents if something was repaired\n(check + repair + re-check), 1 if the document came back untouched.\n3 are debited up front; an untouched document gives 2 back.","operationId":"repair_v1_invoices_repair_post","requestBody":{"description":"XRechnung XML (UBL or CII, max. 10 MB) as raw request body or as multipart field `file`. PDF is not supported and returns 422 REPAIR_FORMAT.","content":{"application/xml":{"schema":{"type":"string","format":"binary"}},"text/xml":{"schema":{"type":"string","format":"binary"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"multipart/form-data":{"schema":{"properties":{"file":{"type":"string","format":"binary","description":"The invoice file."}},"type":"object","required":["file"]}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Free allowance used up and not enough credit (CREDIT_EXHAUSTED).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Payload Too Large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Unprocessable Entity","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/invoices/generate":{"post":{"tags":["E-Invoices"],"summary":"Generate","operationId":"generate_v1_invoices_generate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"}}},"required":true},"responses":{"200":{"description":"The generated file: XML for the xrechnung-* targets, PDF (ZUGFeRD) for zugferd-en16931.","headers":{"X-Validation-Status":{"description":"Always `valid`: the file passed the re-check.","schema":{"type":"string"}}},"content":{"application/xml":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Free allowance used up and not enough credit (CREDIT_EXHAUSTED).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Payload Too Large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Unprocessable Entity","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/credit":{"get":{"tags":["credit"],"summary":"Credit","operationId":"credit_v1_credit_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Credit V1 Credit Get"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"schemas":{"GenerateRequest":{"properties":{"target":{"type":"string","enum":["xrechnung-ubl","xrechnung-cii","zugferd-en16931"],"title":"Target"},"invoice":{"additionalProperties":true,"type":"object","title":"Invoice"}},"type":"object","required":["target","invoice"],"title":"GenerateRequest","description":"Nothing is invented for a legal document. Required:\n`invoice.seller.contact` (name, phone, email), `invoice.buyer.email`,\n`address.country` for seller and buyer, and `quantity`, `unit_price`,\n`vat_rate` on every line. A missing field is answered with 422\n`VALIDATION` naming it (e.g. \"seller.contact.phone is required for\nXRechnung (BR-DE-6)\", \"invoice.lines[1].vat_rate is required\").\nOptional: `invoice.seller.email` (BT-34, defaults to the contact\ne-mail), `invoice.delivery_date` (ISO date, BT-72; omitted if absent),\n`payment.terms_days` (due date BT-9; none if absent),\n`payment.terms_text` (own payment terms, BT-20). Defaults: `currency`\nEUR, line `unit` C62.","examples":[{"invoice":{"buyer":{"address":{"city":"München","country":"DE","street":"Kundenweg 2","zip":"80331"},"buyer_reference":"K-1001","email":"einkauf@kunde.example","name":"Kunde AG"},"currency":"EUR","delivery_date":"2026-09-24","issue_date":"2026-09-25","lines":[{"name":"Beratung","quantity":10,"unit":"HUR","unit_price":120.0,"vat_rate":19.0}],"number":"RE-2026-0042","payment":{"iban":"DE02120300000000202051","terms_days":14},"seller":{"address":{"city":"Berlin","country":"DE","street":"Musterstr. 1","zip":"10115"},"contact":{"email":"erika.muster@muster.example","name":"Erika Muster","phone":"+49 30 1234567"},"email":"rechnung@muster.example","name":"Muster GmbH","vat_id":"DE123456789"}},"target":"xrechnung-ubl"}]},"Problem":{"type":"object","title":"Problem","required":["type","title","status","detail","instance","request_id","error_code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"request_id":{"type":"string"},"error_code":{"type":"string","description":"Stable machine-readable code, e.g. UNAUTHORIZED, RATE_LIMITED"}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"servers":[{"url":"https://formkorrekt.com"}],"externalDocs":{"description":"Quickstart","url":"https://formkorrekt.com/quickstart"},"tags":[{"name":"E-Invoices","description":"Validate, repair and generate XRechnung/ZUGFeRD."},{"name":"credit","description":"Prepaid credit balance, free allowance left and current prices."},{"name":"Utility","description":"Check that an API key works."}]}