invoicepdfs-com Batches API

openapi: 3.2.0
info:
  title: Invoicepdfs Com Batches API
  version: 0.3.0
  contact:
    name: InvoicePDFs
    url: https://invoicepdfs.com/
  license:
    name: MIT
  description: 'Operations tagged batches 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: Batches
paths:
  /api/v1/batches:
    get:
      tags:
      - Batches
      summary: List Batches
      description: Batch jobs on this account, newest first.
      operationId: list_batches
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchesListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
    post:
      tags:
      - Batches
      summary: Create Batch
      description: 'Queue many documents to be rendered at once.


        Returns `202` — the batch is recorded and a worker renders it; nothing is

        rendered inside this request. Poll `get_batch` for progress, then

        `download_batch` for the results.


        The whole batch is refused if it would exceed the monthly quota, rather than

        rendering part of it.'
      operationId: create_batch
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
  /api/v1/batches/{batch_id}:
    get:
      tags:
      - Batches
      summary: Get Batch
      description: 'A batch''s status and its per-item counts.


        The poll surface: `total_items`, `completed_items` and `failed_items` say how

        far it has got without listing every item.'
      operationId: get_batch
      security:
      - HTTPBearer: []
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
          title: Batch Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
  /api/v1/batches/{batch_id}/items:
    get:
      tags:
      - Batches
      summary: List Batch Items
      description: 'Every item in a batch with its own status, newest first.


        Where to look when `failed_items` is not zero: each row carries its error and,

        once rendered, its `render_id`.'
      operationId: list_batch_items
      security:
      - HTTPBearer: []
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
          title: Batch Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchItemsListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
  /api/v1/batches/{batch_id}/cancel:
    post:
      tags:
      - Batches
      summary: Cancel Batch
      description: 'Stop a batch that has not finished.


        Items not yet started are cancelled. An item already rendering completes —

        the work is done and cancelling it would waste it.'
      operationId: cancel_batch
      security:
      - HTTPBearer: []
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
          title: Batch Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
  /api/v1/batches/{batch_id}/download:
    get:
      tags:
      - Batches
      summary: Download Batch
      description: 'Every completed render in the batch, as a ZIP.


        `409` until the batch is `completed`. Items that failed are simply absent, so

        check `failed_items` rather than counting files.'
      operationId: download_batch
      security:
      - HTTPBearer: []
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
          title: Batch Id
      responses:
        '200':
          description: ZIP archive of every completed render in the batch
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-visibility: public
components:
  schemas:
    BatchesListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/BatchOut'
          type: array
          title: Data
        pagination:
          $ref: '#/components/schemas/CursorPagination'
      type: object
      required:
      - data
      title: BatchesListResponse
    BatchResponse:
      properties:
        data:
          $ref: '#/components/schemas/BatchOut'
      type: object
      required:
      - data
      title: BatchResponse
    BatchOut:
      properties:
        id:
          type: string
          title: Id
        status:
          $ref: '#/components/schemas/BatchStatus'
        operation:
          type: string
          title: Operation
        template_id:
          type: string
          title: Template Id
        template_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Template Version
        total_items:
          type: integer
          title: Total Items
        completed_items:
          type: integer
          title: Completed Items
        failed_items:
          type: integer
          title: Failed Items
        created_at:
          type: string
          title: Created At
        updated_at:
          type: string
          title: Updated At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
      type: object
      required:
      - id
      - status
      - operation
      - template_id
      - total_items
      - completed_items
      - failed_items
      - created_at
      - updated_at
      title: BatchOut
    CursorPagination:
      properties:
        has_more:
          type: boolean
          title: Has More
          default: false
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      title: CursorPagination
    BatchStatus:
      type: string
      enum:
      - queued
      - processing
      - completed
      - failed
      - cancelled
      title: BatchStatus
    BatchItemStatus:
      type: string
      enum:
      - pending
      - completed
      - failed
      title: BatchItemStatus
    BatchItemInput:
      properties:
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
          examples:
          - order_1001
        document_type:
          type: string
          const: invoice
          title: Document Type
          default: invoice
        data:
          additionalProperties: true
          type: object
          title: Data
          description: Document data payload
      type: object
      required:
      - data
      title: BatchItemInput
    BatchOutputOptions:
      properties:
        format:
          type: string
          const: pdf
          title: Format
          default: pdf
        combine:
          type: boolean
          title: Combine
          default: false
        archive_format:
          type: string
          const: zip
          title: Archive Format
          default: zip
      type: object
      title: BatchOutputOptions
    BatchItemsListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/BatchItemOut'
          type: array
          title: Data
        pagination:
          $ref: '#/components/schemas/CursorPagination'
      type: object
      required:
      - data
      title: BatchItemsListResponse
    BatchItemOut:
      properties:
        id:
          type: string
          title: Id
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
        document_type:
          type: string
          title: Document Type
        status:
          $ref: '#/components/schemas/BatchItemStatus'
        render_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Render Id
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        created_at:
          type: string
          title: Created At
      type: object
      required:
      - id
      - document_type
      - status
      - created_at
      title: BatchItemOut
    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
    BatchCreateRequest:
      properties:
        operation:
          type: string
          const: render
          title: Operation
          default: render
        items:
          items:
            $ref: '#/components/schemas/BatchItemInput'
          type: array
          maxItems: 500
          minItems: 1
          title: Items
        template_id:
          type: string
          title: Template Id
          default: tpl_modern
        template_version:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Template Version
          description: Render the config this version of the template recorded, instead of the config it holds now. Only a custom (`ctpl_`) template has versions.
          examples:
          - 2
        output:
          $ref: '#/components/schemas/BatchOutputOptions'
      type: object
      required:
      - items
      title: BatchCreateRequest
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- openapi.json
- invoicepdfs-com-openapi.json
x-internal-tags:
- auth
- jobs
- logs