{
 "openapi": "3.1.0",
 "info": {
  "title": "einvoice.asapeca.com API",
  "version": "1",
  "description": "Check e-invoices (XRechnung, ZUGFeRD, Factur-X, EN 16931 in CII or UBL) with the official KoSIT validator, veraPDF and the ZUGFeRD rules, plus a recalculation of all amounts that names the field and the expected value; and create an XRechnung from JSON. Open: no key, no sign-up, limited per IP address. Files are checked in memory and not stored. Every answer carries version 1; within v1 fields are only added.",
  "contact": {
   "url": "https://einvoice.asapeca.com/impressum"
  }
 },
 "servers": [
  {
   "url": "https://einvoice.asapeca.com"
  }
 ],
 "paths": {
  "/api/v1/check": {
   "post": {
    "operationId": "checkInvoice",
    "summary": "Check an e-invoice",
    "description": "Send the file (XML or PDF, at most 10 MB) as the raw body, or as the field file of multipart/form-data. To fix an invoice: work through problems with level error; for source recalc write expected into field; help links explain each rule.",
    "requestBody": {
     "required": true,
     "content": {
      "application/xml": {
       "schema": {
        "type": "string"
       }
      },
      "application/pdf": {
       "schema": {
        "type": "string",
        "format": "binary"
       }
      },
      "application/octet-stream": {
       "schema": {
        "type": "string",
        "format": "binary"
       }
      },
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "properties": {
         "file": {
          "type": "string",
          "format": "binary"
         }
        },
        "required": [
         "file"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Checked: see verdict.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Check"
        }
       }
      }
     },
     "400": {
      "description": "No file (code no-file).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Failure"
        }
       }
      }
     },
     "413": {
      "description": "Larger than 10 MB (code too-large).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Failure"
        }
       }
      }
     },
     "422": {
      "description": "Not a file we can check: verdict error, error.code one of not-xml-or-pdf, plain-pdf, no-invoice-xml, xml-too-large, pdf-unreadable, not-an-invoice, zugferd-1.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Check"
        }
       }
      }
     },
     "429": {
      "description": "Over the limit per IP (10 per minute, bursts of 20). Code rate-limit.",
      "headers": {
       "Retry-After": {
        "description": "Seconds to wait.",
        "schema": {
         "type": "integer"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Failure"
        }
       }
      }
     },
     "503": {
      "description": "Busy (code busy) or the official validator did not answer (code kosit-unavailable; Retry-After 5 on a timeout, else 60).",
      "headers": {
       "Retry-After": {
        "description": "Seconds to wait.",
        "schema": {
         "type": "integer"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Failure"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/create": {
   "post": {
    "operationId": "createInvoice",
    "summary": "Create an XRechnung or EN 16931 invoice (CII, UBL or ZUGFeRD PDF) from JSON",
    "description": "The amounts (line nets, VAT breakdown, totals) are computed by EN 16931; the file is then checked like /api/v1/check. format zugferd: a PDF/A-3 with the visible invoice (in lang) and the CII inside (ZUGFeRD 2 profile EN16931 or XRECHNUNG, after profile), file.type application/pdf. Problems that block issuing come back with status 422.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Issued: file and its check.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CreateResponse"
        }
       }
      }
     },
     "400": {
      "description": "Not the contract: codes bad-json, unknown-format, unknown-profile, unknown-lang.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CreateResponse"
        }
       }
      }
     },
     "413": {
      "description": "Request larger than 1 MB (code too-large).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CreateResponse"
        }
       }
      }
     },
     "422": {
      "description": "Not issued: problems with level error.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CreateResponse"
        }
       }
      }
     },
     "429": {
      "description": "Over the limit per IP (code rate-limit).",
      "headers": {
       "Retry-After": {
        "description": "Seconds to wait.",
        "schema": {
         "type": "integer"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CreateResponse"
        }
       }
      }
     },
     "500": {
      "description": "Our error (code failed).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CreateResponse"
        }
       }
      }
     },
     "503": {
      "description": "Busy (code busy) or the ZUGFeRD PDF could not be made (code zugferd-unavailable; XML formats still work).",
      "headers": {
       "Retry-After": {
        "description": "Seconds to wait.",
        "schema": {
         "type": "integer"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CreateResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/openapi.json": {
   "get": {
    "operationId": "openapi",
    "summary": "This description",
    "responses": {
     "200": {
      "description": "OpenAPI 3.1",
      "content": {
       "application/json": {}
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Text": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "de": {
      "type": "string"
     },
     "en": {
      "type": "string"
     }
    },
    "required": [
     "de",
     "en"
    ],
    "description": "A text in German and English."
   },
   "Field": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "id": {
      "type": "string",
      "description": "BT-n or BG-n of EN 16931."
     },
     "name": {
      "$ref": "#/components/schemas/Text"
     },
     "xpath": {
      "type": "string",
      "description": "Where the field is in the file's syntax (CII or UBL), e.g. to add a missing element; UBL line fields relative to the invoice line. If known."
     }
    },
    "required": [
     "id",
     "name"
    ],
    "description": "A business term or group of EN 16931 with its name."
   },
   "Error": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "description": "Stable code: see the operation's responses."
     },
     "text": {
      "$ref": "#/components/schemas/Text"
     }
    },
    "required": [
     "code",
     "text"
    ]
   },
   "Failure": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "version": {
      "const": 1
     },
     "error": {
      "$ref": "#/components/schemas/Error"
     }
    },
    "required": [
     "version",
     "error"
    ],
    "description": "A request that was not taken."
   },
   "File": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "size": {
      "type": "integer",
      "description": "Bytes."
     },
     "sha256": {
      "type": "string",
      "description": "SHA-256 of the uploaded bytes, hex."
     },
     "container": {
      "type": "string",
      "description": "xml or pdf.",
      "enum": [
       "xml",
       "pdf"
      ]
     },
     "attachment": {
      "type": "string",
      "description": "The name of the invoice XML inside the PDF."
     },
     "syntax": {
      "type": "string",
      "enum": [
       "CII",
       "UBL-Invoice",
       "UBL-CreditNote",
       "ZUGFeRD-1",
       "unknown"
      ]
     },
     "profile": {
      "type": "string",
      "description": "The specification identifier BT-24 as written in the file."
     },
     "profileKey": {
      "type": "string",
      "enum": [
       "xrechnung-3",
       "xrechnung-old",
       "en16931",
       "peppol-bis",
       "zugferd-extended",
       "zugferd-basic",
       "zugferd-basicwl",
       "zugferd-minimum",
       "unknown"
      ]
     },
     "number": {
      "type": "string",
      "description": "BT-1 invoice number."
     },
     "currency": {
      "type": "string",
      "description": "BT-5 currency."
     }
    },
    "required": [
     "size",
     "sha256"
    ]
   },
   "Official": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "engine": {
      "type": "string",
      "description": "The KoSIT validator and version."
     },
     "config": {
      "type": "string",
      "description": "The configuration and its date, e.g. Validator Configuration XRechnung 3.0.2 (2026-09-02)."
     },
     "scenario": {
      "type": "string",
      "description": "The scenario KoSIT chose by BT-24."
     },
     "verdict": {
      "type": "string",
      "enum": [
       "accept",
       "reject",
       "no-scenario"
      ]
     }
    },
    "required": [
     "engine",
     "scenario",
     "verdict"
    ],
    "description": "The verdict of the official KoSIT validator (XRechnung and EN 16931). Its messages are in problems with source kosit."
   },
   "PDFA": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "status": {
      "type": "string",
      "enum": [
       "valid",
       "invalid"
      ]
     },
     "flavour": {
      "type": "string",
      "description": "PDF/A part and level, e.g. 3b, 4f."
     },
     "compliant": {
      "type": "boolean"
     }
    },
    "required": [
     "status",
     "compliant"
    ]
   },
   "ZUGFeRD": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "engine": {
      "type": "string"
     },
     "status": {
      "type": "string",
      "description": "unavailable: our side failed, error says so; the verdict then covers the XML only.",
      "enum": [
       "valid",
       "invalid",
       "unavailable"
      ]
     },
     "pdfa": {
      "$ref": "#/components/schemas/PDFA"
     },
     "error": {
      "$ref": "#/components/schemas/Text"
     }
    },
    "required": [
     "status"
    ],
    "description": "PDF/A (veraPDF) and the ZUGFeRD / Factur-X rules (Mustang): for PDFs and for profiles KoSIT has no scenario for (BASIC, EXTENDED). Messages are in problems with source pdfa or zugferd."
   },
   "Problem": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "source": {
      "type": "string",
      "description": "kosit: official validator; zugferd: ZUGFeRD rules or Mustang; pdfa: the PDF/A check; recalc: our recalculation of the amounts.",
      "enum": [
       "kosit",
       "zugferd",
       "pdfa",
       "recalc"
      ]
     },
     "code": {
      "type": "string",
      "description": "kosit, zugferd: the rule, e.g. BR-DE-15, BR-CO-10; pdfa: the rule or MUSTANG-<type>; recalc: line, net-price, ac-percent, total, missing, vat-basis, vat-tax, vat-row-missing, vat-row-extra."
     },
     "level": {
      "type": "string",
      "description": "error makes the invoice invalid (verdict rejected); warning and info do not.",
      "enum": [
       "error",
       "warning",
       "info"
      ]
     },
     "field": {
      "$ref": "#/components/schemas/Field"
     },
     "line": {
      "type": "integer",
      "description": "kosit, zugferd: 1-based position of the invoice line in the file."
     },
     "lineId": {
      "type": "string",
      "description": "recalc: the line's id BT-126."
     },
     "path": {
      "type": "string",
      "description": "kosit, zugferd: the XPath of the element."
     },
     "text": {
      "$ref": "#/components/schemas/Text"
     },
     "help": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
       "de": {
        "type": "string",
        "format": "uri"
       },
       "en": {
        "type": "string",
        "format": "uri"
       }
      },
      "description": "The knowledge base page on this rule: what it checks, typical causes, how to fix. Present when there is one."
     },
     "fix": {
      "type": "string",
      "description": "recalc: what to do. expected: write expected into field (for a line: the line lineId). lines: this sum is right, line amounts BT-131 are wrong — fix their problems (code line) and keep this sum. vat: the same for the VAT amounts BT-117 (code vat-tax). Absent for vat-row-missing / vat-row-extra (add or drop a row of the VAT breakdown).",
      "enum": [
       "expected",
       "lines",
       "vat"
      ]
     },
     "rule": {
      "type": "string",
      "description": "recalc: the official rule on the same sum, if any."
     },
     "declared": {
      "type": "string",
      "description": "recalc: the value in the invoice."
     },
     "expected": {
      "type": "string",
      "description": "recalc: the value by EN 16931 from the invoice's own amounts; see fix."
     },
     "diff": {
      "type": "string",
      "description": "recalc: declared − expected."
     },
     "cause": {
      "type": "string",
      "description": "recalc: the likely cause.",
      "enum": [
       "price-with-vat",
       "ac-left-out",
       "price-rounded",
       "rounding",
       "vat-per-line",
       "ac-no-category",
       "from-lines",
       "from-vat",
       "sum-unrounded"
      ]
     }
    },
    "required": [
     "source",
     "code",
     "level",
     "text"
    ],
    "description": "One finding. Problems come errors first, then warnings, then info. A recalc problem of level error on a line or VAT amount is the wrong value behind an error of a sum."
   },
   "Total": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "field": {
      "$ref": "#/components/schemas/Field"
     },
     "declared": {
      "type": "string"
     },
     "expected": {
      "type": "string"
     },
     "ok": {
      "type": "boolean"
     }
    },
    "required": [
     "field",
     "declared",
     "expected",
     "ok"
    ]
   },
   "VAT": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "category": {
      "type": "string",
      "description": "BT-118."
     },
     "rate": {
      "type": "string",
      "description": "BT-119."
     },
     "basis": {
      "type": "string",
      "description": "BT-116 declared."
     },
     "basisExpected": {
      "type": "string"
     },
     "tax": {
      "type": "string",
      "description": "BT-117 declared."
     },
     "taxExpected": {
      "type": "string"
     },
     "ok": {
      "type": "boolean"
     }
    },
    "required": [
     "category",
     "rate",
     "basis",
     "basisExpected",
     "tax",
     "taxExpected",
     "ok"
    ]
   },
   "Recalc": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "totals": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Total"
      },
      "description": "The document totals BG-22."
     },
     "vat": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/VAT"
      },
      "description": "The VAT breakdown BG-23."
     }
    },
    "required": [
     "totals",
     "vat"
    ],
    "description": "Our recalculation of the amounts by the rules of EN 16931 (exact decimals, commercial rounding). Its findings are in problems with source recalc."
   },
   "Missing": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "field": {
      "$ref": "#/components/schemas/Field"
     },
     "value": {
      "type": "string"
     }
    },
    "required": [
     "field",
     "value"
    ]
   },
   "PDFText": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "noText": {
      "type": "boolean",
      "description": "The PDF has no text (a scan)."
     },
     "missing": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Missing"
      },
      "description": "Key values of the XML (BT-1, 2, 109, 110, 112, 115, 31, 84) the visible text does not show."
     },
     "error": {
      "$ref": "#/components/schemas/Text"
     }
    },
    "required": [
     "missing"
    ],
    "description": "A PDF: its visible text against the XML. A hint only; the XML decides, the verdict does not change."
   },
   "Check": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "version": {
      "const": 1
     },
     "verdict": {
      "type": "string",
      "description": "ok: valid, nothing to fix. warnings: valid, but warnings (KoSIT, ZUGFeRD) or our recalculation found a difference. rejected: invalid, at least one problem of level error. unchecked: no official scenario for this profile and no ZUGFeRD rules either. error: the file could not be checked, see error.",
      "enum": [
       "ok",
       "warnings",
       "rejected",
       "unchecked",
       "error"
      ]
     },
     "file": {
      "$ref": "#/components/schemas/File"
     },
     "official": {
      "$ref": "#/components/schemas/Official"
     },
     "zugferd": {
      "$ref": "#/components/schemas/ZUGFeRD"
     },
     "problems": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Problem"
      }
     },
     "recalc": {
      "$ref": "#/components/schemas/Recalc"
     },
     "pdfText": {
      "$ref": "#/components/schemas/PDFText"
     },
     "error": {
      "$ref": "#/components/schemas/Error"
     },
     "ms": {
      "type": "integer",
      "description": "Milliseconds the check took."
     }
    },
    "required": [
     "version",
     "verdict",
     "problems",
     "ms"
    ],
    "description": "The result of one check. Within v1 fields are only added: ignore fields you do not know."
   },
   "Party": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "name": {
      "type": "string",
      "description": "BT-27 / BT-44."
     },
     "tradeName": {
      "type": "string",
      "description": "BT-28 / BT-45."
     },
     "id": {
      "type": "string",
      "description": "BT-29 / BT-46, without a scheme."
     },
     "legalId": {
      "type": "string",
      "description": "BT-30 / BT-47, e.g. HRB 12345."
     },
     "vatId": {
      "type": "string",
      "description": "BT-31 / BT-48."
     },
     "taxNo": {
      "type": "string",
      "description": "BT-32, seller only: the German Steuernummer."
     },
     "legal": {
      "type": "string",
      "description": "BT-33, seller only: further legal information."
     },
     "eaddr": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
       "scheme": {
        "type": "string",
        "description": "EAS code, e.g. EM (e-mail), 0204 (Leitweg-ID), 9930 (German VAT ID)."
       },
       "value": {
        "type": "string"
       }
      },
      "description": "BT-34 / BT-49 electronic address; XRechnung requires it for both parties."
     },
     "address": {
      "$ref": "#/components/schemas/Address"
     },
     "contact": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
       "name": {
        "type": "string",
        "description": "BT-41 / BT-56."
       },
       "phone": {
        "type": "string",
        "description": "BT-42 / BT-57."
       },
       "email": {
        "type": "string",
        "description": "BT-43 / BT-58."
       }
      }
     }
    },
    "required": [
     "name",
     "eaddr",
     "address",
     "contact"
    ]
   },
   "Address": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "street": {
      "type": "string"
     },
     "street2": {
      "type": "string"
     },
     "city": {
      "type": "string"
     },
     "zip": {
      "type": "string"
     },
     "subdivision": {
      "type": "string"
     },
     "country": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2."
     }
    },
    "required": [
     "country"
    ]
   },
   "AC": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "charge": {
      "type": "boolean",
      "description": "true: a charge (BG-21, BG-28), false: an allowance (BG-20, BG-27)."
     },
     "amount": {
      "description": "A decimal as a JSON number or a string: up to 15 digits before the point and 10 after, no exponent (12.5, \"-3.00\").",
      "oneOf": [
       {
        "type": "number"
       },
       {
        "type": "string",
        "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,10})?$"
       }
      ]
     },
     "base": {
      "description": "A decimal as a JSON number or a string: up to 15 digits before the point and 10 after, no exponent (12.5, \"-3.00\").",
      "oneOf": [
       {
        "type": "number"
       },
       {
        "type": "string",
        "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,10})?$"
       }
      ]
     },
     "percent": {
      "description": "A decimal as a JSON number or a string: up to 15 digits before the point and 10 after, no exponent (12.5, \"-3.00\").",
      "oneOf": [
       {
        "type": "number"
       },
       {
        "type": "string",
        "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,10})?$"
       }
      ]
     },
     "category": {
      "type": "string",
      "description": "Document level only: VAT category of the allowance or charge."
     },
     "rate": {
      "description": "A decimal as a JSON number or a string: up to 15 digits before the point and 10 after, no exponent (12.5, \"-3.00\").",
      "oneOf": [
       {
        "type": "number"
       },
       {
        "type": "string",
        "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,10})?$"
       }
      ]
     },
     "reason": {
      "type": "string"
     },
     "reasonCode": {
      "type": "string",
      "description": "UNTDID 5189 (allowance) or 7161 (charge, e.g. FC freight)."
     }
    },
    "required": [
     "charge"
    ],
    "description": "Either amount, or percent and base."
   },
   "Line": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "id": {
      "type": "string",
      "description": "BT-126."
     },
     "note": {
      "type": "string",
      "description": "BT-127."
     },
     "orderRef": {
      "type": "string",
      "description": "BT-132."
     },
     "qty": {
      "description": "A decimal as a JSON number or a string: up to 15 digits before the point and 10 after, no exponent (12.5, \"-3.00\").",
      "oneOf": [
       {
        "type": "number"
       },
       {
        "type": "string",
        "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,10})?$"
       }
      ]
     },
     "unit": {
      "type": "string",
      "description": "BT-130, UN/ECE Rec. 20: H87 piece, C62 one, HUR hour …"
     },
     "price": {
      "description": "A decimal as a JSON number or a string: up to 15 digits before the point and 10 after, no exponent (12.5, \"-3.00\").",
      "oneOf": [
       {
        "type": "number"
       },
       {
        "type": "string",
        "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,10})?$"
       }
      ]
     },
     "gross": {
      "description": "A decimal as a JSON number or a string: up to 15 digits before the point and 10 after, no exponent (12.5, \"-3.00\").",
      "oneOf": [
       {
        "type": "number"
       },
       {
        "type": "string",
        "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,10})?$"
       }
      ]
     },
     "baseQty": {
      "description": "A decimal as a JSON number or a string: up to 15 digits before the point and 10 after, no exponent (12.5, \"-3.00\").",
      "oneOf": [
       {
        "type": "number"
       },
       {
        "type": "string",
        "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,10})?$"
       }
      ]
     },
     "acs": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AC"
      }
     },
     "category": {
      "type": "string",
      "description": "BT-151 VAT category: S standard, Z zero, E exempt, AE reverse charge, K intra-EU, G export, O not subject."
     },
     "rate": {
      "description": "A decimal as a JSON number or a string: up to 15 digits before the point and 10 after, no exponent (12.5, \"-3.00\").",
      "oneOf": [
       {
        "type": "number"
       },
       {
        "type": "string",
        "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,10})?$"
       }
      ]
     },
     "name": {
      "type": "string",
      "description": "BT-153."
     },
     "descr": {
      "type": "string",
      "description": "BT-154."
     },
     "sellerId": {
      "type": "string",
      "description": "BT-155, the SKU."
     },
     "gtin": {
      "type": "string",
      "description": "BT-157 (scheme 0160)."
     },
     "origin": {
      "type": "string",
      "description": "BT-159."
     },
     "periodFrom": {
      "type": "string",
      "description": "ISO date YYYY-MM-DD.",
      "format": "date"
     },
     "periodTo": {
      "type": "string",
      "description": "ISO date YYYY-MM-DD.",
      "format": "date"
     }
    },
    "required": [
     "id",
     "qty",
     "unit",
     "price",
     "category",
     "name"
    ],
    "description": "An invoice line. Its net amount BT-131 is computed: do not send it."
   },
   "Invoice": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "number": {
      "type": "string",
      "description": "BT-1."
     },
     "issueDate": {
      "type": "string",
      "description": "ISO date YYYY-MM-DD.",
      "format": "date"
     },
     "type": {
      "type": "string",
      "description": "BT-3, UNTDID 1001: 380 invoice, 381 credit note, 384 corrected invoice, 389 self-billed."
     },
     "currency": {
      "type": "string",
      "description": "BT-5, ISO 4217."
     },
     "dueDate": {
      "type": "string",
      "description": "ISO date YYYY-MM-DD.",
      "format": "date"
     },
     "buyerRef": {
      "type": "string",
      "description": "BT-10; a Leitweg-ID for German public buyers."
     },
     "orderRef": {
      "type": "string",
      "description": "BT-13."
     },
     "preceding": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
        "number": {
         "type": "string",
         "description": "BT-25."
        },
        "date": {
         "type": "string",
         "description": "ISO date YYYY-MM-DD.",
         "format": "date"
        }
       },
       "required": [
        "number"
       ]
      },
      "description": "BG-3 preceding invoices (credit notes, corrections)."
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
        "subject": {
         "type": "string",
         "description": "BT-21, UNTDID 4451."
        },
        "text": {
         "type": "string",
         "description": "BT-22."
        }
       },
       "required": [
        "text"
       ]
      }
     },
     "seller": {
      "$ref": "#/components/schemas/Party"
     },
     "buyer": {
      "$ref": "#/components/schemas/Party"
     },
     "delivery": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
       "date": {
        "type": "string",
        "description": "ISO date YYYY-MM-DD.",
        "format": "date"
       },
       "periodFrom": {
        "type": "string",
        "description": "ISO date YYYY-MM-DD.",
        "format": "date"
       },
       "periodTo": {
        "type": "string",
        "description": "ISO date YYYY-MM-DD.",
        "format": "date"
       },
       "name": {
        "type": "string",
        "description": "BT-70."
       },
       "address": {
        "$ref": "#/components/schemas/Address"
       }
      },
      "description": "BT-72 or the period BT-73/74; BG-15 if not the buyer's address."
     },
     "payment": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
       "means": {
        "type": "string",
        "description": "BT-81, UNTDID 4461: 58 SEPA transfer, 30 transfer, 68 online, 10 cash, ZZZ other."
       },
       "meansText": {
        "type": "string",
        "description": "BT-82, e.g. PayPal."
       },
       "reference": {
        "type": "string",
        "description": "BT-83."
       },
       "accounts": {
        "type": "array",
        "items": {
         "type": "object",
         "additionalProperties": false,
         "properties": {
          "iban": {
           "type": "string",
           "description": "BT-84."
          },
          "name": {
           "type": "string",
           "description": "BT-85."
          },
          "bic": {
           "type": "string",
           "description": "BT-86."
          }
         },
         "required": [
          "iban"
         ]
        }
       },
       "terms": {
        "type": "string",
        "description": "BT-20."
       }
      },
      "required": [
       "means"
      ]
     },
     "lines": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Line"
      }
     },
     "acs": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AC"
      },
      "description": "Document-level allowances and charges."
     },
     "prepaid": {
      "description": "A decimal as a JSON number or a string: up to 15 digits before the point and 10 after, no exponent (12.5, \"-3.00\").",
      "oneOf": [
       {
        "type": "number"
       },
       {
        "type": "string",
        "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,10})?$"
       }
      ]
     },
     "rounding": {
      "description": "A decimal as a JSON number or a string: up to 15 digits before the point and 10 after, no exponent (12.5, \"-3.00\").",
      "oneOf": [
       {
        "type": "number"
       },
       {
        "type": "string",
        "pattern": "^-?[0-9]{1,15}(\\.[0-9]{1,10})?$"
       }
      ]
     },
     "exemptions": {
      "type": "object",
      "description": "Per VAT category without VAT (E, AE, K, G, O): BT-120 text and BT-121 VATEX code.",
      "additionalProperties": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
        "text": {
         "type": "string"
        },
        "code": {
         "type": "string"
        }
       }
      }
     }
    },
    "required": [
     "number",
     "issueDate",
     "type",
     "currency",
     "seller",
     "buyer",
     "delivery",
     "payment",
     "lines"
    ],
    "description": "The invoice as you fill it. Not sent, because computed: line nets, price discounts, the VAT breakdown, the totals. Unknown fields are an error (bad-json)."
   },
   "CreateRequest": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "format": {
      "type": "string",
      "description": "Default cii. zugferd: ZUGFeRD 2 PDF/A-3 with the CII inside.",
      "enum": [
       "cii",
       "ubl",
       "zugferd"
      ]
     },
     "profile": {
      "type": "string",
      "description": "Default xrechnung for cii and ubl, en16931 for zugferd (its XML is then factur-x.xml, which every ZUGFeRD reader finds; xrechnung gives ZUGFeRD in the profile XRECHNUNG with xrechnung.xml).",
      "enum": [
       "xrechnung",
       "en16931"
      ]
     },
     "lang": {
      "type": "string",
      "description": "The language of the visible invoice of format zugferd. Default de.",
      "enum": [
       "de",
       "en"
      ]
     },
     "invoice": {
      "$ref": "#/components/schemas/Invoice"
     }
    },
    "required": [
     "invoice"
    ]
   },
   "CreateProblem": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "code": {
      "type": "string",
      "description": "The official rule (BR-*, PEPPOL-*) or ours (CORE-*)."
     },
     "level": {
      "type": "string",
      "enum": [
       "error",
       "warning"
      ]
     },
     "field": {
      "$ref": "#/components/schemas/Field"
     },
     "line": {
      "type": "integer",
      "description": "1-based invoice line."
     },
     "text": {
      "$ref": "#/components/schemas/Text"
     }
    },
    "required": [
     "code",
     "level",
     "field",
     "text"
    ]
   },
   "CreateResponse": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
     "version": {
      "const": 1
     },
     "issued": {
      "type": "boolean"
     },
     "format": {
      "type": "string"
     },
     "profile": {
      "type": "string"
     },
     "problems": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/CreateProblem"
      }
     },
     "file": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
       "name": {
        "type": "string"
       },
       "type": {
        "type": "string"
       },
       "size": {
        "type": "integer"
       },
       "content": {
        "type": "string",
        "description": "The invoice file, base64.",
        "contentEncoding": "base64"
       }
      },
      "required": [
       "name",
       "type",
       "size",
       "content"
      ]
     },
     "totals": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
       "lineNet": {
        "type": "string"
       },
       "allowances": {
        "type": "string"
       },
       "charges": {
        "type": "string"
       },
       "netTotal": {
        "type": "string"
       },
       "tax": {
        "type": "string"
       },
       "gross": {
        "type": "string"
       },
       "prepaid": {
        "type": "string"
       },
       "rounding": {
        "type": "string"
       },
       "due": {
        "type": "string"
       }
      },
      "required": [
       "lineNet",
       "allowances",
       "charges",
       "netTotal",
       "tax",
       "gross",
       "prepaid",
       "rounding",
       "due"
      ],
      "description": "BG-22 as written."
     },
     "vat": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
        "category": {
         "type": "string"
        },
        "rate": {
         "type": "string"
        },
        "basis": {
         "type": "string"
        },
        "tax": {
         "type": "string"
        }
       },
       "required": [
        "category",
        "rate",
        "basis",
        "tax"
       ]
      }
     },
     "check": {
      "$ref": "#/components/schemas/Check"
     },
     "error": {
      "$ref": "#/components/schemas/Error"
     }
    },
    "required": [
     "version",
     "issued",
     "problems"
    ],
    "description": "issued true: file holds the invoice and check its check by the same pipeline as /check. issued false: problems say what keeps it from being issued (no file)."
   }
  }
 }
}
