invoicepdfs-com Renders API

openapi: 3.2.0
info:
  title: Invoicepdfs Com Renders API
  version: 0.3.0
  contact:
    name: InvoicePDFs
    url: https://invoicepdfs.com/
  license:
    name: MIT
  description: 'Operations tagged renders 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: renders
paths:
  /api/v1/renders/{render_id}:
    get:
      tags:
      - renders
      summary: Get Render
      description: 'One render: its status, its totals, and how to download it.


        `download_url` and `expires_at` are `null` until the render is `completed`,

        and a `failed` render carries a `failure` explaining why. Poll this after an

        asynchronous render.'
      operationId: get_render
      security:
      - HTTPBearer: []
      parameters:
      - name: render_id
        in: path
        required: true
        schema:
          type: string
          title: Render Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
  /api/v1/renders/{render_id}/download:
    get:
      tags:
      - renders
      summary: Download Render
      description: 'Fetch the PDF, by signature or by API key.


        Two ways in, and the signature is checked *first* — before the row is looked

        up — so a forged token cannot be used to tell a real render id from an

        invented one. It also means the token path costs no auth work at all, which

        matters because this is the one endpoint a browser hits directly.'
      operationId: download_render
      security:
      - HTTPBearer: []
      parameters:
      - name: render_id
        in: path
        required: true
        schema:
          type: string
          title: Render Id
      - name: token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The signature from this render's `download_url`. Present it and no API key is needed — that is what makes the URL a link. Omit it and the request authenticates normally.
          title: Token
        description: The signature from this render's `download_url`. Present it and no API key is needed — that is what makes the URL a link. Omit it and the request authenticates normally.
      responses:
        '200':
          description: PDF file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
components:
  schemas:
    Money:
      properties:
        amount:
          type: string
          title: Amount
        currency:
          type: string
          title: Currency
      type: object
      required:
      - amount
      - currency
      title: Money
    RenderComplianceOut:
      properties:
        profile:
          type: string
          title: Profile
          description: The ruleset this document was built and validated against.
          examples:
          - factur_x_en16931
        ruleset_version:
          type: string
          title: Ruleset Version
          description: The artefact versions the check actually ran. A profile is held to more than one ruleset, and they are regenerated over time, so this is what makes 'which rules did this pass?' answerable later.
          examples:
          - en16931-1.3.16
        fully_checked:
          type: boolean
          title: Fully Checked
          description: False when a ruleset could not run. The document still satisfied everything that did, but the authoritative Schematron tier being absent is a materially weaker statement than it passing.
        advisories:
          items:
            $ref: '#/components/schemas/ComplianceViolationOut'
          type: array
          title: Advisories
          description: Non-fatal findings the render proceeded past. Both rulesets grade a large share of their rules as advisory, so these are worth reading and are not a rejection.
      type: object
      required:
      - profile
      - ruleset_version
      - fully_checked
      title: RenderComplianceOut
      description: 'What this PDF was held to, for a render that carries embedded XML.


        Absent on a plain `pdf`: no ruleset was applied, so there is no claim to

        report. A render that was produced at all satisfied every fatal rule that

        ran — the render is refused otherwise — so the useful questions are which

        rules those were, and whether all of them ran.'
    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
    RenderFailureOut:
      properties:
        code:
          type: string
          title: Code
          description: '`compliance_failed` for a document that is well-formed and would be rejected by the ruleset it asked for; `unprocessable_entity` for one the renderer could not make sense of. The same codes the synchronous path returns.'
          examples:
          - compliance_failed
        message:
          type: string
          title: Message
        details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Details
          description: 'For `compliance_failed`: the profile, the ruleset version, and every violation with its rule, path, message and severity.'
      type: object
      required:
      - code
      - message
      title: RenderFailureOut
      description: 'Why a render failed, in the same shape the synchronous path returns.


        A synchronous render of a document EN 16931 would reject answers `422

        compliance_failed` with every violation at once — a list of fields to go and

        fill in. A queued render has to be able to say the same thing: the caller

        who chose `async` did not choose a worse answer.'
    CalculationBreakdown:
      properties:
        subtotal:
          $ref: '#/components/schemas/Money'
        discount_total:
          $ref: '#/components/schemas/Money'
        document_discount_total:
          $ref: '#/components/schemas/Money'
          default:
            amount: '0.00'
            currency: USD
        tax_total:
          $ref: '#/components/schemas/Money'
        shipping_total:
          $ref: '#/components/schemas/Money'
        total:
          $ref: '#/components/schemas/Money'
      type: object
      required:
      - subtotal
      - discount_total
      - tax_total
      - shipping_total
      - total
      title: CalculationBreakdown
    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
    RenderOut:
      properties:
        id:
          type: string
          title: Id
        status:
          $ref: '#/components/schemas/RenderStatus'
        document_type:
          type: string
          enum:
          - invoice
          - credit_note
          - debit_note
          - quote
          - receipt
          - proforma
          - purchase_order
          - delivery_note
          title: Document Type
        template_id:
          type: string
          title: Template Id
        template_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Template Version
        format:
          type: string
          const: pdf
          title: Format
        download_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Download Url
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
        calculation:
          $ref: '#/components/schemas/CalculationBreakdown'
        created_at:
          type: string
          title: Created At
        compliance:
          anyOf:
          - $ref: '#/components/schemas/RenderComplianceOut'
          - type: 'null'
        failure:
          anyOf:
          - $ref: '#/components/schemas/RenderFailureOut'
          - type: 'null'
      type: object
      required:
      - id
      - status
      - document_type
      - template_id
      - format
      - calculation
      - created_at
      title: RenderOut
    RenderResponse:
      properties:
        data:
          $ref: '#/components/schemas/RenderOut'
      type: object
      required:
      - data
      title: RenderResponse
    RenderStatus:
      type: string
      enum:
      - queued
      - processing
      - completed
      - failed
      title: RenderStatus
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- openapi.json
- invoicepdfs-com-openapi.json
x-internal-tags:
- auth
- jobs
- logs