invoicepdfs-com Compliance API

openapi: 3.2.0
info:
  title: Invoicepdfs Com Compliance API
  version: 0.3.0
  contact:
    name: InvoicePDFs
    url: https://invoicepdfs.com/
  license:
    name: MIT
  description: 'Operations tagged compliance across 2 of this provider''s published API definitions: openapi.json, invoicepdfs-com-openapi.json. Each path carries the servers of the definition it was published in.'
tags:
- name: Compliance
paths:
  /api/v1/documents/validate-compliance:
    post:
      tags:
      - Compliance
      summary: Validate Compliance
      description: 'Check a document against an e-invoicing ruleset without rendering it.


        Costs no renders: nothing is stored and no PDF is produced, so a caller can

        check every invoice they are about to send rather than discovering the

        problem from a rejection weeks later.


        Two tiers run, and both are reported. The mandatory-field check names a

        field of the request you can go and change. Schematron then serializes the

        document and runs the **published rules at a pinned version** over the

        result — the same artefacts an access point runs — so a finding here quotes

        the rule id a rejection notice would quote.


        Read `valid` together with `fully_checked`: `valid` says nothing fatal was

        found, and `rulesets` says what actually ran to find it.'
      operationId: validate_compliance
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentComplianceRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentComplianceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      security:
      - HTTPBearer: []
      x-visibility: public
  /api/v1/documents/xml:
    post:
      tags:
      - Compliance
      summary: Render Document Xml
      description: 'The e-invoicing XML for a document, without storing anything.


        Takes the same body as `/validate-compliance`, and the pairing is the point:

        check first, then take the XML once it passes. Nothing here validates

        against the ruleset — a document missing mandatory fields serialises to XML

        missing those elements, which is a more useful artefact to look at than a

        refusal, and `/validate-compliance` is where the refusal belongs.


        The syntax is not a parameter. It follows from the profile, because a

        profile already is a syntax plus a ruleset, and asking a caller for both is

        asking them to know that Peppol means UBL.'
      operationId: render_document_xml
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentComplianceRequest'
        required: true
      responses:
        '200':
          description: The document as XML, in the syntax the chosen profile is expressed in — UBL for Peppol BIS, CII for Factur-X.
          content:
            application/xml:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      security:
      - HTTPBearer: []
      x-visibility: public
  /api/v1/documents/{document_id}/xml:
    get:
      tags:
      - Compliance
      summary: Download Document Xml
      description: 'The e-invoicing XML for a document already stored here.


        Reads `data_json` directly rather than going through the render path''s

        reconstruction: the status, the logo and the source document''s number are

        all attached there for the *PDF*, and none of them belong in the XML. The

        credit note''s BG-3 reference is already in the stored payload, resolved when

        the document was written.'
      operationId: download_document_xml
      security:
      - HTTPBearer: []
      parameters:
      - name: document_id
        in: path
        required: true
        schema:
          type: string
          title: Document Id
      - name: profile
        in: query
        required: true
        schema:
          type: string
          description: 'Which ruleset to write this against. No default: a document valid under one can be rejected by another, so the choice is the request.'
          examples:
          - peppol_bis_billing_3
          title: Profile
        description: 'Which ruleset to write this against. No default: a document valid under one can be rejected by another, so the choice is the request.'
      responses:
        '200':
          description: The stored document as XML, in the syntax the chosen profile is expressed in — UBL for Peppol BIS, CII for Factur-X.
          content:
            application/xml:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
components:
  schemas:
    DocumentBrandingInput:
      properties:
        logo_file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo File Id
        primary_color:
          type: string
          title: Primary Color
          default: '#111827'
        accent_color:
          type: string
          title: Accent Color
          default: '#111827'
        font_family:
          anyOf:
          - type: string
          - type: 'null'
          title: Font Family
        footer_text:
          type: string
          title: Footer Text
          default: Generated by InvoicePDFs
        hide_invoicepdfs_branding:
          type: boolean
          title: Hide Invoicepdfs Branding
          default: false
      type: object
      title: DocumentBrandingInput
    PostalAddress:
      properties:
        line1:
          type: string
          title: Line1
          examples:
          - 1 Main St
        line2:
          anyOf:
          - type: string
          - type: 'null'
          title: Line2
          examples:
          - Suite 200
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
          examples:
          - San Francisco
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
          examples:
          - CA
        postal_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Postal Code
          examples:
          - '94105'
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
          examples:
          - US
      type: object
      required:
      - line1
      title: PostalAddress
    DocumentDiscountInput:
      properties:
        type:
          type: string
          enum:
          - percentage
          - fixed
          title: Type
          default: percentage
        value:
          type: string
          title: Value
          examples:
          - '10'
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          examples:
          - Loyalty discount
      type: object
      required:
      - value
      title: DocumentDiscountInput
    DocumentShippingInput:
      properties:
        description:
          type: string
          title: Description
          default: Shipping
        amount:
          type: string
          title: Amount
          examples:
          - '9.99'
        taxable:
          type: boolean
          title: Taxable
          default: false
      type: object
      required:
      - amount
      title: DocumentShippingInput
    DocumentInvoiceDataInput:
      properties:
        invoice_number:
          type: string
          title: Invoice Number
          examples:
          - INV-2026-001
        issue_date:
          type: string
          format: date
          title: Issue Date
          examples:
          - '2026-07-20'
        due_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Due Date
          examples:
          - '2026-08-19'
        currency:
          type: string
          title: Currency
          examples:
          - USD
        seller:
          $ref: '#/components/schemas/DocumentPartyInput'
        buyer:
          $ref: '#/components/schemas/DocumentPartyInput'
        ship_to:
          anyOf:
          - $ref: '#/components/schemas/DocumentPartyInput'
          - type: 'null'
        tax_scheme:
          anyOf:
          - type: string
          - type: 'null'
          title: Tax Scheme
          description: 'UNCL5153 — what kind of tax this invoice states. One document, one answer: an invoice is issued under a tax regime, not a different one per line. Optional, and deliberately not defaulted, because a PDF does not need it and assuming `VAT` would put a claim in a tax document that you did not make. Required to produce or check an e-invoice, where it must be `VAT` — every ruleset built on EN 16931 describes VAT and tests for that string literally, so a document stating anything else is refused rather than relabelled.'
          examples:
          - VAT
        delivery_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Delivery Date
          description: When the goods or services were actually supplied (BT-72). Not the issue date, and it is what decides the VAT period. XRechnung requires this, an invoicing period, or a period on every line.
          examples:
          - '2026-09-30'
        buyer_reference:
          anyOf:
          - type: string
          - type: 'null'
          title: Buyer Reference
          description: BT-10. Mandatory in Peppol BIS unless an order reference is present — often the buyer's own PO or cost-centre string.
          examples:
          - PO-4711
        preceding_invoice_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Preceding Invoice Number
          description: BT-25. The number of the invoice a credit note corrects. Supplied directly here because this path stores nothing to look it up in.
          examples:
          - INV-2026-001
        line_items:
          items:
            $ref: '#/components/schemas/DocumentLineItemInput'
          type: array
          title: Line Items
        discounts:
          items:
            $ref: '#/components/schemas/DocumentDiscountInput'
          type: array
          title: Discounts
        shipping:
          anyOf:
          - $ref: '#/components/schemas/DocumentShippingInput'
          - type: 'null'
        custom_fields:
          items:
            $ref: '#/components/schemas/DocumentCustomFieldInput'
          type: array
          title: Custom Fields
        payment:
          anyOf:
          - $ref: '#/components/schemas/DocumentPaymentInput'
          - type: 'null'
        branding:
          anyOf:
          - $ref: '#/components/schemas/DocumentBrandingInput'
          - type: 'null'
      type: object
      required:
      - invoice_number
      - issue_date
      - currency
      - seller
      - buyer
      - line_items
      title: DocumentInvoiceDataInput
    DocumentComplianceResponse:
      properties:
        data:
          $ref: '#/components/schemas/ComplianceCheckOut'
      type: object
      required:
      - data
      title: DocumentComplianceResponse
    ComplianceRulesetOut:
      properties:
        id:
          type: string
          title: Id
          examples:
          - peppol-en16931-ubl
        label:
          type: string
          title: Label
          examples:
          - Peppol BIS Billing 3.0
        version:
          type: string
          title: Version
          description: The upstream release of the rules. Empty for checks with no version of their own.
          default: ''
          examples:
          - 3.0.20
        ran:
          type: boolean
          title: Ran
          description: False when this ruleset could not be run at all. A ruleset that did not run is not a pass — `valid` only reports what was checked.
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          description: Why it did not run, when it did not.
      type: object
      required:
      - id
      - label
      - ran
      title: ComplianceRulesetOut
      description: One ruleset the document was held to, and whether it actually ran.
    DocumentLineItemInput:
      properties:
        name:
          type: string
          title: Name
          examples:
          - Web Development
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          examples:
          - Frontend redesign project
        quantity:
          type: string
          title: Quantity
          examples:
          - '2'
        unit_price:
          type: string
          title: Unit Price
          description: Decimal string in major units
          examples:
          - '150.00'
        unit:
          anyOf:
          - type: string
          - type: 'null'
          title: Unit
          examples:
          - hours
        unit_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Unit Code
          description: BT-130. UN/ECE Rec 20 code for the unit — HUR for hours, C62 for each. Separate from `unit`, which is the label printed on the PDF.
          examples:
          - HUR
        sku:
          anyOf:
          - type: string
          - type: 'null'
          title: Sku
          examples:
          - SVC-WEB-001
        discount:
          anyOf:
          - $ref: '#/components/schemas/DocumentDiscountInput'
          - type: 'null'
        taxes:
          items:
            $ref: '#/components/schemas/DocumentLineItemTaxInput'
          type: array
          title: Taxes
      type: object
      required:
      - name
      - quantity
      - unit_price
      title: DocumentLineItemInput
    DocumentLineItemTaxInput:
      properties:
        name:
          type: string
          title: Name
          examples:
          - Sales Tax
        rate:
          type: string
          title: Rate
          examples:
          - '8.875'
        inclusive:
          type: boolean
          title: Inclusive
          default: false
        category:
          anyOf:
          - $ref: '#/components/schemas/TaxCategory'
          - type: 'null'
          description: How this tax is treated — required for e-invoicing formats, which keep zero-rated, exempt and reverse-charge in separate VAT groups.
      type: object
      required:
      - name
      - rate
      title: DocumentLineItemTaxInput
    InvoiceBankAccountInput:
      properties:
        bank_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Bank Name
          examples:
          - First National Bank
        account_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Name
          examples:
          - Acme Corp
        account_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Number
          examples:
          - '1234567890'
        routing_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Routing Number
          examples:
          - '021000021'
        swift:
          anyOf:
          - type: string
          - type: 'null'
          title: Swift
          examples:
          - FNBKUS33
        iban:
          anyOf:
          - type: string
          - type: 'null'
          title: Iban
          examples:
          - US82FNBK0000001234567890
      type: object
      title: InvoiceBankAccountInput
    ComplianceCheckOut:
      properties:
        profile:
          type: string
          title: Profile
          examples:
          - peppol_bis_billing_3
        ruleset_version:
          type: string
          title: Ruleset Version
          description: The version these rules came from. Worth recording alongside any document you file — rulesets revise, and 'which rules did this pass?' is what an audit asks years later. `rulesets` breaks the same answer down per ruleset.
          examples:
          - EN16931-UBL 1.3.16 + Peppol BIS Billing 3.0.20
        valid:
          type: boolean
          title: Valid
          description: Nothing fatal was found. Read it with `fully_checked` — on its own it says what was checked came back clean, not that everything was checked.
        in_scope:
          type: boolean
          title: In Scope
          description: 'Whether any of these rulesets is likely to apply to this document at all. False when neither party is in a country that uses one — these are European e-invoicing rulesets, and for a wholly domestic US invoice, say, `valid` is answering a question nobody asked. Advisory: it never changes the verdict or withholds the check, because an open network means a US seller invoicing a Dutch buyer genuinely needs it.'
          default: true
        fully_checked:
          type: boolean
          title: Fully Checked
          description: Every ruleset that applies to this profile ran. False means at least one could not, and `rulesets` says which and why.
          default: true
        rulesets:
          items:
            $ref: '#/components/schemas/ComplianceRulesetOut'
          type: array
          title: Rulesets
          description: Every ruleset the document was held to, including the mandatory-field check, at the version that ran.
        violations:
          items:
            $ref: '#/components/schemas/ComplianceViolationOut'
          type: array
          title: Violations
          description: Every violation found, not the first — fixing one field per round trip is the experience this avoids. Ordered mandatory-field findings first, since those name a field you can go and change.
      type: object
      required:
      - profile
      - ruleset_version
      - valid
      title: ComplianceCheckOut
    DocumentCustomFieldInput:
      properties:
        label:
          type: string
          title: Label
          examples:
          - PO Number
        value:
          type: string
          title: Value
          examples:
          - PO-2026-001
      type: object
      required:
      - label
      - value
      title: DocumentCustomFieldInput
    DocumentComplianceRequest:
      properties:
        document_type:
          type: string
          enum:
          - invoice
          - credit_note
          - debit_note
          - quote
          - receipt
          - proforma
          - purchase_order
          - delivery_note
          title: Document Type
          default: invoice
        data:
          $ref: '#/components/schemas/DocumentInvoiceDataInput'
        profile:
          type: string
          title: Profile
          description: 'Which ruleset to hold the document to. Rulesets differ: a document valid under one can be rejected by another, so there is no default.'
          examples:
          - peppol_bis_billing_3
      type: object
      required:
      - data
      - profile
      title: DocumentComplianceRequest
    DocumentPartyInput:
      properties:
        name:
          type: string
          title: Name
          examples:
          - Acme Corp
        legal_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Legal Name
          examples:
          - Acme Corp Inc.
        contact_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Name
          description: Who to ask about an invoice — a person or a department, not the company. EN 16931 calls it the contact point (BT-41 for the seller, BT-56 for the buyer); some national rulesets require it.
          examples:
          - Accounts Receivable
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
          examples:
          - billing@acme.com
        phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
          examples:
          - +1-555-123-4567
        website:
          anyOf:
          - type: string
          - type: 'null'
          title: Website
          examples:
          - https://acme.com
        tax_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Tax Id
          examples:
          - US-EIN-12-3456789
        registration_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Registration Number
          examples:
          - REG-2024-00123
        address:
          anyOf:
          - $ref: '#/components/schemas/PostalAddress'
          - type: 'null'
        bank_account:
          anyOf:
          - $ref: '#/components/schemas/InvoiceBankAccountInput'
          - type: 'null'
        electronic_address:
          anyOf:
          - $ref: '#/components/schemas/ElectronicAddress'
          - type: 'null'
          description: Network address for e-invoicing. Required by Peppol; not the tax id.
      type: object
      required:
      - name
      title: DocumentPartyInput
    DocumentPaymentInput:
      properties:
        bank_account:
          anyOf:
          - $ref: '#/components/schemas/InvoiceBankAccountInput'
          - type: 'null'
        payment_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Url
          examples:
          - https://pay.acme.com/inv-001
        accepted_methods:
          items:
            type: string
          type: array
          title: Accepted Methods
          examples:
          - - bank_transfer
            - credit_card
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
          examples:
          - Please pay within 30 days
      type: object
      title: DocumentPaymentInput
    ApiErrorResponse:
      type: object
      title: ApiErrorResponse
      properties:
        error:
          type: object
          properties:
            status:
              type: integer
              example: 422
              description: HTTP status, mirroring the response status line.
            code:
              type: string
              example: unprocessable_entity
            message:
              type: string
              example: Request validation failed
            request_id:
              type: string
              nullable: true
              description: Trace id for this request; also returned as X-Trace-Id.
            details:
              type: object
              nullable: true
              description: Error-specific context. Validation failures carry `fields`.
          required:
          - status
          - code
          - message
      required:
      - error
    TaxCategory:
      properties:
        code:
          type: string
          minLength: 1
          title: Code
          description: UNCL5305 tax category code — S standard, Z zero-rated, E exempt, AE reverse charge, K intra-community, G export, O outside scope
          examples:
          - S
        exemption_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Exemption Reason
          description: Required by EN 16931 whenever the category is not standard.
          examples:
          - Reverse charge
        exemption_reason_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Exemption Reason Code
          examples:
          - VATEX-EU-AE
      type: object
      required:
      - code
      title: TaxCategory
      description: 'How a tax is treated, as opposed to what it is called.


        `name` and `rate` do not say this: two taxes at 0% may be zero-rated,

        exempt, reverse-charge or outside scope, and EN 16931 keeps them in

        separate VAT breakdown groups with different mandatory fields. Optional,

        so an invoice that never mentions a category calculates exactly as before.'
    ComplianceViolationOut:
      properties:
        rule:
          type: string
          title: Rule
          description: The identifier the standard uses — a business term from the mandatory-field check, a rule id from Schematron. A rule id is what a rejection notice from an access point quotes.
          examples:
          - BT-130
          - PEPPOL-EN16931-R003
        path:
          type: string
          title: Path
          description: Where the problem is. The mandatory-field check names a field of the request; Schematron names the node in the generated XML.
          examples:
          - lines[1].unit_code
          - /Invoice[1]/TaxTotal[1]
        message:
          type: string
          title: Message
          examples:
          - A coded unit is required.
        severity:
          type: string
          title: Severity
          description: '`fatal` would get the document rejected. `warning` is a recommendation — both EN 16931 and Peppol grade a large share of their rules as advisory, and `valid` ignores those.'
          default: fatal
          examples:
          - fatal
          - warning
        ruleset:
          type: string
          title: Ruleset
          description: Which ruleset found it — matches an `id` in `rulesets`.
          default: semantic
          examples:
          - semantic
          - peppol-en16931-ubl
      type: object
      required:
      - rule
      - path
      - message
      title: ComplianceViolationOut
    ElectronicAddress:
      properties:
        value:
          type: string
          minLength: 1
          title: Value
          examples:
          - '9482348239'
        scheme_id:
          type: string
          minLength: 1
          title: Scheme Id
          description: EAS code list identifier — 0088 is GLN, 9930 a German VAT number.
          examples:
          - 0088
      type: object
      required:
      - value
      - scheme_id
      title: ElectronicAddress
      description: 'BT-34 / BT-49 — where a document is routed on Peppol or DBNA.


        Both halves are required: an identifier without its scheme cannot be

        resolved, because the same string means different things in different code

        lists. This is not the tax id, which identifies a company to a tax

        authority rather than a mailbox on a network.'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- openapi.json
- invoicepdfs-com-openapi.json
x-internal-tags:
- auth
- jobs
- logs