# GENERATED by scripts/fetch-mustang-spec.mjs — do not edit by hand.
# Source: Mustang's own /api-docs, then re-pointed at the public gateway URL
# and annotated with the auth scheme and gateway error responses it cannot know about.
# Refresh with: pnpm --filter @gw/docs spec:refresh
openapi: 3.0.1
info:
  title: Mustangserver
  description: >-
    Mustangproject e-invoice REST server API


    **Contacts:**

    - **Jochen Stärk:** General inquiries - [jstaerk@usegroup.de](mailto:jstaerk@usegroup.de)

    - **Martin Wachtveitl:** Technical support -
    [martin.wachtveitl@itewa.com](mailto:martin.wachtveitl@itewa.com)
  contact:
    name: Jochen Staerk
    url: http://mustangproject.org/
    email: jstaerk@usegroup.de
  license:
    name: proprietary
    url: http://mustangserver.com/
  version: v1.8.2
externalDocs:
  description: Mustangserver Documentation
  url: https://mustangserver.com/doc/manual-1.8.2.en.pdf
servers:
  - url: https://staging-api-e-invoice.officefreund.de/api/v1.8.2
    description: Staging — live and sandbox, selected by your API key prefix
paths:
  /e-invoice/xmltopdf:
    post:
      tags:
        - Mustang
      summary: Returns a PDF/A-3 visualisation from a XML string.
      operationId: xmltopdf
      parameters:
        - name: returnJSON
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Returns a PDF/A-3 visualisation from a XML string.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/xmltohtml:
    post:
      tags:
        - Mustang
      summary: Visualisation from XML to HTML.
      operationId: xmltohtml
      parameters:
        - name: language
          in: query
          required: true
          schema:
            type: string
            enum:
              - EN
              - FR
              - DE
          example: DE
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Visualisation from XML to HTML.
          content:
            application/octet-stream:
              schema:
                type: string
        "400":
          description: Bad Request
          content:
            application/octet-stream:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/validationReportToPDF:
    post:
      tags:
        - Validation
      summary: Returns a PDF visualization for a Mustang validation XML validation result output
      operationId: validationReportToPDF
      parameters:
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - XMLValidationResult
              type: object
              properties:
                XMLValidationResult:
                  type: string
      responses:
        "200":
          description: Returns a minimal PDF visualization for a XML validation result report
          content:
            application/octet-stream:
              schema:
                type: array
                items:
                  type: string
                  format: byte
        "400":
          description: Bad Request
          content:
            application/octet-stream:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/validate:
    post:
      tags:
        - Validation
      summary: Checks a PDF or XML file for syntactical and mathematical correctness. Input file must be a
        PDF/A file (Factur-X, ZUGFeRD, Order-X) or a XML file (Factur-X, Order-X, ZUGFeRD,
        XRechnung(CII)), output will be a XML report
      operationId: validateFile
      parameters:
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
        - name: ignoreNotices
          in: query
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Checks a PDF or XML file for syntactical and mathematical correctness. Input file must
            be a PDF/A file (Factur-X, Order-X, ZUGFeRD) or a XML file (Factur-X, Order-X, ZUGFeRD,
            XRechnung(CII)), output will be a XML report
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/styledinvoicetofx:
    post:
      tags:
        - Mustang
      summary: Converts a mustache string and a calculatedinvoice to factur-x
      operationId: styledinvoicetofx
      parameters:
        - name: writeS3
          in: header
          required: false
          schema:
            type: boolean
        - name: language
          in: query
          required: true
          schema:
            type: string
            enum:
              - EN
              - FR
              - DE
          example: DE
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: string
        required: true
      responses:
        "200":
          description: Converts a mustache string and a calculatedinvoice to factur-x
          content:
            "*/*":
              schema:
                type: array
                items:
                  type: string
                  format: byte
        "400":
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/phive:
    post:
      tags:
        - Validation
      summary: Validates a XML file
      operationId: phive
      parameters:
        - name: VESID
          in: query
          required: false
          schema:
            type: string
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - inputFile
              type: object
              properties:
                inputFile:
                  type: string
                  format: binary
      responses:
        "200":
          description: Returns a JSON validation result
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/pdf2pdfa:
    post:
      tags:
        - Mustang
      summary: Converts an ordinary PDF to PDF/A, quick and dirty
      operationId: pdf2pdfa
      parameters:
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: PDF to PDF/A quick conversion
          content:
            application/octet-stream:
              schema:
                type: array
                items:
                  type: string
                  format: byte
        "400":
          description: Bad Request
          content:
            application/octet-stream:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/parse:
    post:
      tags:
        - Mustang
      summary: Reads a Factur-X file into an invoice object. Requires a PDF or CII or UBL XML file.
      operationId: parse
      parameters:
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Reads a Factur-X file into an invoice object
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/invoice2XML:
    post:
      tags:
        - Mustang
      summary: Invoice class to XML. Input must be JSON.
      operationId: invoice2xml
      parameters:
        - name: format
          in: query
          required: true
          schema:
            type: string
          example: fx
        - name: profile
          in: query
          required: true
          schema:
            type: string
          example: EN16931
        - name: version
          in: query
          required: true
          schema:
            type: integer
            format: int32
          example: 2
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CalculatedInvoice"
        required: true
      responses:
        "200":
          description: Invoice class to XML. Input must be JSON, output will be XML (CII).
          content:
            application/xml:
              schema:
                type: string
        "400":
          description: Bad Request
          content:
            application/xml:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/extract:
    post:
      tags:
        - Mustang
      summary: Extracts XML from a zf/fx PDF or XML. Input PDF must be ZUGFeRD or Factur-X, XML must be
        xr,zf,fx or ox
      operationId: extractFile
      parameters:
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Extracts XML from a PDF or XML
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/detach:
    post:
      tags:
        - Mustang
      summary: Extract invoice file attachments from XML and PDF files
      operationId: detach
      parameters:
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/combine:
    post:
      tags:
        - Mustang
      summary: Combine PDF/A file and JSON invoice object. Output PDF will be a ZUGFeRD/Factur-X PDF/A-3
        file called invoice.pdf.
      operationId: combine
      parameters:
        - name: format
          in: query
          required: true
          schema:
            type: string
          example: fx
        - name: profile
          in: query
          required: true
          schema:
            type: string
          example: EN16931
        - name: version
          in: query
          required: true
          schema:
            type: integer
            format: int32
          example: 2
        - name: ignorePDFAErrors
          in: header
          required: false
          schema:
            type: boolean
        - name: returnJSON
          in: header
          required: false
          schema:
            type: boolean
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
                - json
              type: object
              properties:
                file:
                  type: string
                  format: binary
                json:
                  type: string
      responses:
        "200":
          description: Combine PDF/A file and JSON to zf/fx PDF. Input PDF must be PDF/A-1 or PDF/A-3, output
            PDF will be a ZUGFeRD/Factur-X PDF/A-3 file called invoice.pdf.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/combineXML:
    post:
      tags:
        - Mustang
      summary: Combine PDF/A file and custom XML to zf/fx PDF. Input PDF must be PDF/A-1 or A-3, output
        PDF will be a ZUGFeRD/Factur-X PDF/A-3 file called invoice.pdf.
      operationId: combineXML
      parameters:
        - name: format
          in: query
          required: true
          schema:
            type: string
          example: fx
        - name: version
          in: query
          required: true
          schema:
            type: integer
            format: int32
          example: 2
        - name: profile
          in: query
          required: true
          schema:
            type: string
          example: EN16931
        - name: ignorePDFAErrors
          in: header
          required: false
          schema:
            type: boolean
        - name: returnJSON
          in: header
          required: false
          schema:
            type: boolean
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - XML
                - file
              type: object
              properties:
                file:
                  type: string
                  format: binary
                XML:
                  type: string
      responses:
        "200":
          description: Combine PDF/A file and custom XML to zf/fx PDF. Input PDF must be PDF/A-1 or PDF/A-3,
            output PDF will be a ZUGFeRD/Factur-X PDF/A-3 file called invoice.pdf.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/ciitoubl:
    post:
      tags:
        - Mustang
      summary: Converts a UN/CEFACT CII XML file to UBL, preferred endpoint name
      operationId: ciitoubl
      parameters:
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/xml:
            schema:
              type: string
        required: true
      responses:
        "200":
          description: Converts a UN/CEFACT CII XML file to UBL
          content:
            application/xml:
              schema:
                type: string
        "400":
          description: Bad Request
          content:
            application/xml:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/cii2ubl:
    post:
      tags:
        - Mustang
      summary: Converts a UN/CEFACT CII XML file to UBL, deprecated endpoint name
      operationId: cii2ubl
      parameters:
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/xml:
            schema:
              type: string
        required: true
      responses:
        "200":
          description: Converts a UN/CEFACT CII XML file to UBL
          content:
            application/xml:
              schema:
                type: string
        "400":
          description: Bad Request
          content:
            application/xml:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/calculate:
    post:
      tags:
        - Mustang
      summary: "Returns a calculated invoice with totals from a invoice without totals "
      operationId: calculate
      parameters:
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Invoice"
        required: true
      responses:
        "200":
          description: Invoice class to XML. Input must be JSON, output will be XML (CII).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CalculatedInvoice"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/ping:
    get:
      tags:
        - Mustang
      summary: Healthcheck. Just request a ping, will respond with a 'pong'
      operationId: ping
      parameters:
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Healthcheck. Just request a ping, will respond with a 'pong'
          content:
            "*/*":
              schema:
                type: string
        "400":
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /e-invoice/notice:
    get:
      tags:
        - Service
      summary: Returns legal related information
      operationId: notice
      parameters:
        - name: USERNAME
          in: header
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Returns legal related information
          content:
            "*/*":
              schema:
                type: string
        "400":
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
components:
  schemas:
    ApiErrorResponse:
      required:
        - errorCode
        - httpCode
        - requestUrl
      type: object
      properties:
        requestUrl:
          type: string
          description: URL
        httpCode:
          type: integer
          description: HTTP code
          format: int32
        errorCode:
          type: string
          description: Internal error code
        message:
          type: string
          description: Message
        details:
          type: object
          additionalProperties:
            type: string
            description: Detail description
          description: Detail description
      description: Response holding information for client errors.
    BankDetails:
      type: object
      properties:
        accountName:
          type: string
        paymentMeansCode:
          type: string
        paymentMeansInformation:
          type: string
        bic:
          type: string
        iban:
          type: string
    CalculatedInvoice:
      type: object
      properties:
        documentName:
          type: string
        documentCode:
          type: string
        number:
          type: string
        ownOrganisationFullPlaintextInfo:
          type: string
        referenceNumber:
          type: string
        shipToOrganisationID:
          type: string
        shipToOrganisationName:
          type: string
        shipToStreet:
          type: string
        shipToZIP:
          type: string
        shipToLocation:
          type: string
        shipToCountry:
          type: string
        buyerOrderReferencedDocumentID:
          type: string
        buyerOrderReferencedDocumentIssueDateTime:
          type: string
        ownForeignOrganisationID:
          type: string
          deprecated: true
        ownOrganisationName:
          type: string
          deprecated: true
        currency:
          type: string
        paymentTermDescription:
          type: string
        deliveryTypeCode:
          type: string
        issueDate:
          type: string
          format: date-time
        dueDate:
          type: string
          format: date-time
        deliveryDate:
          type: string
          format: date-time
        sender:
          $ref: "#/components/schemas/TradeParty"
        recipient:
          $ref: "#/components/schemas/TradeParty"
        deliveryAddress:
          $ref: "#/components/schemas/TradeParty"
        endCustomerDeliveryAddress:
          $ref: "#/components/schemas/TradeParty"
        payee:
          $ref: "#/components/schemas/TradeParty"
        invoicer:
          $ref: "#/components/schemas/TradeParty"
        invoicee:
          $ref: "#/components/schemas/TradeParty"
        cashDiscounts:
          type: array
          items:
            $ref: "#/components/schemas/CashDiscount"
        notes:
          type: array
          items:
            type: string
        sellerOrderReferencedDocumentID:
          type: string
        contractReferencedDocument:
          type: string
        totalPrepaidAmount:
          type: number
        paymentTerms:
          $ref: "#/components/schemas/IZUGFeRDPaymentTerms"
        invoiceReferencedDocumentID:
          type: string
          deprecated: true
        invoiceReferencedIssueDate:
          type: string
          format: date-time
          deprecated: true
        invoiceReferencedDocuments:
          type: array
          items:
            $ref: "#/components/schemas/ReferencedDocument"
        specifiedProcuringProjectID:
          type: string
        specifiedProcuringProjectName:
          type: string
        despatchAdviceReferencedDocumentID:
          type: string
        deliveryNoteReferencedDocumentID:
          type: string
        deliveryNoteReferencedDocumentDate:
          type: string
          format: date-time
        creditorReferenceID:
          type: string
        roundingAmount:
          type: number
        paymentReference:
          type: string
        businessProcessId:
          type: string
        lineTotalAmount:
          type: number
        duePayable:
          type: number
        grandTotal:
          type: number
        taxBasis:
          type: number
        calculation:
          $ref: "#/components/schemas/TransactionCalculator"
        vattotal:
          type: number
        objectIdentifierReferencedDocument:
          $ref: "#/components/schemas/IReferencedDocument"
        extendedPaymentTerms:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDPaymentTerms"
        detailedDeliveryPeriodFrom:
          type: string
          format: date-time
        detailedDeliveryPeriodTo:
          type: string
          format: date-time
        additionalReferencedDocuments:
          type: array
          items:
            $ref: "#/components/schemas/FileAttachment"
        notesWithSubjectCode:
          type: array
          items:
            $ref: "#/components/schemas/IncludedNote"
        vatdueDateTypeCode:
          type: string
        tenderReferencedDocument:
          $ref: "#/components/schemas/IReferencedDocument"
        correction:
          $ref: "#/components/schemas/Invoice"
        creditNote:
          $ref: "#/components/schemas/Invoice"
        ownContact:
          $ref: "#/components/schemas/Invoice"
        zfallowances:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDAllowanceCharge"
        zfcharges:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDAllowanceCharge"
        zfitems:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDExportableItem"
        tradeSettlement:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDTradeSettlement"
        zflogisticsServiceCharges:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDAllowanceCharge"
        tradeSettlementPayment:
          type: array
          deprecated: true
          items:
            $ref: "#/components/schemas/IZUGFeRDTradeSettlementPayment"
        subjectNote:
          type: string
    CashDiscount:
      type: object
      properties:
        percent:
          type: number
        days:
          type: integer
          format: int32
        basisAmount:
          type: number
    ClassCode:
      type: object
      properties:
        listID:
          type: string
        code:
          type: string
        listVersionID:
          type: string
    DirectDebit:
      type: object
      properties:
        mandate:
          type: string
        paymentMeansCode:
          type: string
        paymentMeansInformation:
          type: string
        iban:
          type: string
    FileAttachment:
      type: object
      properties:
        filename:
          type: string
        mimetype:
          type: string
        relation:
          type: string
        description:
          type: string
        data:
          type: array
          items:
            type: string
            format: byte
    IDesignatedProductClassification:
      type: object
      properties:
        classCode:
          $ref: "#/components/schemas/ClassCode"
        className:
          type: string
    IReferencedDocument:
      type: object
      properties:
        issuerAssignedID:
          type: string
        formattedIssueDateTime:
          type: string
          format: date-time
        referenceTypeCode:
          type: string
        typeCode:
          type: string
    IZUGFeRDAllowanceCharge:
      type: object
      properties:
        basisAmount:
          type: number
        reasonCode:
          type: string
        taxPercent:
          type: number
        categoryCode:
          type: string
        charge:
          type: boolean
        percent:
          type: number
        reason:
          type: string
    IZUGFeRDExportableContact:
      type: object
      properties:
        additionalAddress:
          type: string
        phone:
          type: string
        email:
          type: string
        fax:
          type: string
        name:
          type: string
        location:
          type: string
        country:
          type: string
        id:
          type: string
        vatid:
          type: string
        street:
          type: string
        zip:
          type: string
    IZUGFeRDExportableItem:
      type: object
      properties:
        lineStatusReasonCode:
          type: string
        parentLineID:
          type: string
        itemAllowances:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDAllowanceCharge"
        itemCharges:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDAllowanceCharge"
        allowances:
          type: array
          deprecated: true
          items:
            $ref: "#/components/schemas/IZUGFeRDAllowanceCharge"
        charges:
          type: array
          deprecated: true
          items:
            $ref: "#/components/schemas/IZUGFeRDAllowanceCharge"
        buyerOrderReferencedDocumentLineID:
          type: string
        price:
          type: number
        quantity:
          type: number
        basisQuantity:
          type: number
        additionalReferencedDocumentID:
          type: string
          deprecated: true
        additionalReferences:
          type: array
          items:
            $ref: "#/components/schemas/IReferencedDocument"
        referencedDocuments:
          type: array
          items:
            $ref: "#/components/schemas/IReferencedDocument"
        itemTotalAllowances:
          type: array
          deprecated: true
          items:
            $ref: "#/components/schemas/IZUGFeRDAllowanceCharge"
        accountingReference:
          type: string
        lineSeller:
          $ref: "#/components/schemas/TradeParty"
        deliveryNoteReferencedDocumentLineID:
          type: string
        product:
          $ref: "#/components/schemas/IZUGFeRDExportableProduct"
        value:
          type: number
          deprecated: true
        id:
          type: string
        buyerOrderReferencedDocumentID:
          type: string
        detailedDeliveryPeriodFrom:
          type: string
          format: date-time
        detailedDeliveryPeriodTo:
          type: string
          format: date-time
        deliveryNoteReferencedDocumentID:
          type: string
        deliveryNoteReferencedDocumentDate:
          type: string
          format: date-time
        notes:
          type: array
          items:
            type: string
        notesWithSubjectCode:
          type: array
          items:
            $ref: "#/components/schemas/IncludedNote"
        calculation:
          $ref: "#/components/schemas/LineCalculator"
        lineTotalAmount:
          type: number
    IZUGFeRDExportableProduct:
      type: object
      properties:
        allowances:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDAllowanceCharge"
        charges:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDAllowanceCharge"
        globalID:
          type: string
        globalIDScheme:
          type: string
        sellerAssignedID:
          type: string
        buyerAssignedID:
          type: string
        vatpercent:
          type: number
        intraCommunitySupply:
          type: boolean
        reverseCharge:
          type: boolean
        taxCategoryCode:
          type: string
        taxExemptionReason:
          type: string
        taxExemptionReasonCode:
          type: string
        countryOfOrigin:
          type: string
        classifications:
          type: array
          items:
            $ref: "#/components/schemas/IDesignatedProductClassification"
        name:
          type: string
        attributes:
          type: object
          additionalProperties:
            type: string
        description:
          type: string
        unit:
          type: string
    IZUGFeRDLegalOrganisation:
      type: object
      properties:
        schemedID:
          $ref: "#/components/schemas/SchemedID"
        tradingBusinessName:
          type: string
    IZUGFeRDPaymentDiscountTerms:
      type: object
      properties:
        baseDate:
          type: string
          format: date-time
        basePeriodMeasure:
          type: integer
          format: int32
        basePeriodUnitCode:
          type: string
        calculationPercentage:
          type: number
    IZUGFeRDPaymentTerms:
      type: object
      properties:
        description:
          type: string
        dueDate:
          type: string
          format: date-time
        discountTerms:
          $ref: "#/components/schemas/IZUGFeRDPaymentDiscountTerms"
    IZUGFeRDTradeSettlement:
      type: object
    IZUGFeRDTradeSettlementPayment:
      type: object
      properties:
        ownIBAN:
          type: string
        accountName:
          type: string
        ownBIC:
          type: string
        paymentMeansCode:
          type: string
        paymentMeansInformation:
          type: string
    IncludedNote:
      type: object
      properties:
        content:
          type: string
        subjectCode:
          type: string
          enum:
            - AAI
            - SUR
            - REG
            - ABL
            - TXD
            - CUS
            - ACY
            - AAK
            - ABZ
            - PMT
            - PMD
            - AAB
            - ACB
            - INV
    Invoice:
      type: object
      properties:
        documentName:
          type: string
        documentCode:
          type: string
        number:
          type: string
        ownOrganisationFullPlaintextInfo:
          type: string
        referenceNumber:
          type: string
        shipToOrganisationID:
          type: string
        shipToOrganisationName:
          type: string
        shipToStreet:
          type: string
        shipToZIP:
          type: string
        shipToLocation:
          type: string
        shipToCountry:
          type: string
        buyerOrderReferencedDocumentID:
          type: string
        buyerOrderReferencedDocumentIssueDateTime:
          type: string
        ownForeignOrganisationID:
          type: string
          deprecated: true
        ownOrganisationName:
          type: string
          deprecated: true
        currency:
          type: string
        paymentTermDescription:
          type: string
        deliveryTypeCode:
          type: string
        issueDate:
          type: string
          format: date-time
        dueDate:
          type: string
          format: date-time
        deliveryDate:
          type: string
          format: date-time
        sender:
          $ref: "#/components/schemas/TradeParty"
        recipient:
          $ref: "#/components/schemas/TradeParty"
        deliveryAddress:
          $ref: "#/components/schemas/TradeParty"
        endCustomerDeliveryAddress:
          $ref: "#/components/schemas/TradeParty"
        payee:
          $ref: "#/components/schemas/TradeParty"
        invoicer:
          $ref: "#/components/schemas/TradeParty"
        invoicee:
          $ref: "#/components/schemas/TradeParty"
        cashDiscounts:
          type: array
          items:
            $ref: "#/components/schemas/CashDiscount"
        notes:
          type: array
          items:
            type: string
        sellerOrderReferencedDocumentID:
          type: string
        contractReferencedDocument:
          type: string
        totalPrepaidAmount:
          type: number
        paymentTerms:
          $ref: "#/components/schemas/IZUGFeRDPaymentTerms"
        invoiceReferencedDocumentID:
          type: string
          deprecated: true
        invoiceReferencedIssueDate:
          type: string
          format: date-time
          deprecated: true
        invoiceReferencedDocuments:
          type: array
          items:
            $ref: "#/components/schemas/ReferencedDocument"
        specifiedProcuringProjectID:
          type: string
        specifiedProcuringProjectName:
          type: string
        despatchAdviceReferencedDocumentID:
          type: string
        deliveryNoteReferencedDocumentID:
          type: string
        deliveryNoteReferencedDocumentDate:
          type: string
          format: date-time
        creditorReferenceID:
          type: string
        roundingAmount:
          type: number
        paymentReference:
          type: string
        businessProcessId:
          type: string
        objectIdentifierReferencedDocument:
          $ref: "#/components/schemas/IReferencedDocument"
        extendedPaymentTerms:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDPaymentTerms"
        detailedDeliveryPeriodFrom:
          type: string
          format: date-time
        detailedDeliveryPeriodTo:
          type: string
          format: date-time
        additionalReferencedDocuments:
          type: array
          items:
            $ref: "#/components/schemas/FileAttachment"
        notesWithSubjectCode:
          type: array
          items:
            $ref: "#/components/schemas/IncludedNote"
        vatdueDateTypeCode:
          type: string
        tenderReferencedDocument:
          $ref: "#/components/schemas/IReferencedDocument"
        correction:
          $ref: "#/components/schemas/Invoice"
        creditNote:
          $ref: "#/components/schemas/Invoice"
        ownContact:
          $ref: "#/components/schemas/Invoice"
        zfallowances:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDAllowanceCharge"
        zfcharges:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDAllowanceCharge"
        zfitems:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDExportableItem"
        tradeSettlement:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDTradeSettlement"
        zflogisticsServiceCharges:
          type: array
          items:
            $ref: "#/components/schemas/IZUGFeRDAllowanceCharge"
        tradeSettlementPayment:
          type: array
          deprecated: true
          items:
            $ref: "#/components/schemas/IZUGFeRDTradeSettlementPayment"
        subjectNote:
          type: string
    LineCalculator:
      type: object
      properties:
        price:
          type: number
        priceGross:
          type: number
        itemTotalNetAmount:
          type: number
        itemTotalVATAmount:
          type: number
        itemTotalGrossAmount:
          type: number
    ReferencedDocument:
      type: object
      properties:
        issuerAssignedID:
          type: string
        typeCode:
          type: string
        referenceTypeCode:
          type: string
        formattedIssueDateTime:
          type: string
          format: date-time
    SchemedID:
      type: object
      properties:
        scheme:
          type: string
        id:
          type: string
    TradeParty:
      type: object
      properties:
        name:
          type: string
        zip:
          type: string
        street:
          type: string
        location:
          type: string
        country:
          type: string
        taxID:
          type: string
        vatID:
          type: string
        description:
          type: string
        additionalAddress:
          type: string
        additionalAddressExtension:
          type: string
        bankDetails:
          type: array
          items:
            $ref: "#/components/schemas/BankDetails"
        debitDetails:
          type: array
          items:
            $ref: "#/components/schemas/DirectDebit"
        contact:
          $ref: "#/components/schemas/IZUGFeRDExportableContact"
        legalOrganisation:
          $ref: "#/components/schemas/IZUGFeRDLegalOrganisation"
        globalID:
          type: string
        globalIDScheme:
          type: string
        vatid:
          type: string
        id:
          type: string
        email:
          type: string
    TransactionCalculator:
      type: object
      properties:
        chargeTotal:
          type: number
        allowanceTotal:
          type: number
        value:
          type: number
        grandTotal:
          type: number
        taxDetails:
          uniqueItems: true
          type: array
          items:
            $ref: "#/components/schemas/VATAmount"
        taxBasis:
          type: number
        duePayable:
          type: number
        quantity:
          type: number
    VATAmount:
      type: object
      properties:
        basis:
          type: number
        calculated:
          type: number
        applicablePercent:
          type: number
        categoryCode:
          type: string
        vatExemptionReasonText:
          type: string
        vatExemptionReasonCode:
          type: string
        dueDateTypeCode:
          type: string
        documentCode:
          type: string
          deprecated: true
    GatewayError:
      type: object
      description: Error shape returned by the API gateway before the request reaches Mustang.
      properties:
        statusCode:
          type: integer
          example: 401
        message:
          type: string
          example: API key not valid for this environment
        errorCode:
          type: string
          example: ENV_MISMATCH
          enum:
            - FORBIDDEN
            - MISSING_KEY
            - INVALID_KEY
            - UNKNOWN_KEY
            - ENV_MISSING
            - ENV_MISMATCH
            - KEY_REVOKED
            - KEY_EXPIRED
            - RATE_LIMITED
            - QUOTA_EXHAUSTED
      required:
        - statusCode
        - message
        - errorCode
  securitySchemes:
    BearerApiKey:
      type: http
      scheme: bearer
      description: "Your API key as a bearer token: `Authorization: Bearer of_live_…`. An `of_test_` key
        reaches the sandbox instead of the live service — same URL, no other change."
    ApiKeyHeader:
      type: apiKey
      in: header
      name: apikey
      description: Alternative to the Authorization header. Same key, same behaviour.
  responses:
    Unauthorized:
      description: The API key is missing, malformed, revoked, or not valid for the environment this
        endpoint routes to.
      headers: &a1
        X-Error-Code:
          description: Machine-readable reason, e.g. `ENV_MISMATCH`, `KEY_REVOKED`.
          schema:
            type: string
      content:
        application/json:
          schema: &a2
            $ref: "#/components/schemas/GatewayError"
    TooManyRequests:
      description: Per-minute rate limit or monthly quota exhausted.
      headers: *a1
      content:
        application/json:
          schema: *a2
security:
  - BearerApiKey: []
  - ApiKeyHeader: []
tags:
  - name: Mustang
    description: Conversion, extraction and calculation over e-invoice documents.
  - name: Service
    description: Health and version information about the service itself.
  - name: Validation
    description: Syntactic and mathematical validation of invoices and their reports.