openapi: 3.0.0
info:
  contact:
    email: dev@invopop.com
    name: Invopop Developers
  description: The Invopop Transform Service API offers endpoints to manage
    tasks and workflows with the primary objective being to send requests for jobs.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Transform Service API
  version: 1.0.1
servers:
- description: production
  url: https://api.invopop.com
security:
- authToken: []
paths:
  /transform/v1/jobs:
    post:
      description: Create a new job without an explicit ID.
      parameters:
      - description: Only for testing. Maximum number of seconds to block the http
          request waiting for the job to complete. When the job finishes within this
          time the response is 200 OK with the complete job; otherwise 202 Accepted
          is returned with the job's initial state. Do not use this in production.
        in: query
        name: wait
        schema:
          description: Only for testing. Maximum number of seconds to block the http
            request waiting for the job to complete. When the job finishes within this
            time the response is 200 OK with the complete job; otherwise 202 Accepted
            is returned with the job's initial state. Do not use this in production.
          example: 60
          title: Wait
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              properties:
                args:
                  description: Additional arguments that may be used by workflow actions.
                    Binary data may be provided inside a Data URI, including the 'name'
                    parameter.
                  title: Args
                  type: object
                data:
                  description: Raw JSON data of the GOBL Envelope or Object when the
                    Silo Entry ID is empty.
                  title: Data
                  type: object
                key:
                  description: Key to associate with the job for idempotency.
                  title: Key
                  type: string
                silo_entry_id:
                  description: ID for the entry in the silo as an alternative for
                    the raw data object.
                  title: Silo Entry ID
                  type: string
                tags:
                  description: Tags to associate with the job.
                  items:
                    type: string
                  title: Tags
                  type: array
                workflow_id:
                  description: UUID of the workflow to execute for this job.
                  title: Workflow ID
                  type: string
              required:
              - workflow_id
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformJob'
          description: OK. Returned only when the wait parameter was provided and the
            job completed in time; the body is the finished job with its intents, faults
            and attachments.
        "202":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformJob'
          description: Accepted. The job has been queued; the body holds its initial
            state with status "NA" and no intents yet.
    get:
      description: Fetch all jobs in the current workspace.
      parameters:
      - description: The starting date and time for retrieving results in descending
          order, formatted as an ISO timestamp.
        in: query
        name: created_at
        schema:
          description: The starting date and time for retrieving results in descending
            order, formatted as an ISO timestamp.
          example: "2023-08-02T00:00:00.000Z"
          title: Created At
          type: string
      - description: The position marker from the previous result's next_cursor property,
          used for pagination.
        in: query
        name: cursor
        schema:
          description: The position marker from the previous result's next_cursor
            property, used for pagination.
          title: Cursor
          type: string
      - description: The maximum number of jobs to return in a single page of results.
          Defaults to 20, maximum 100.
        in: query
        name: limit
        schema:
          description: The maximum number of jobs to return in a single page of results.
            Defaults to 20, maximum 100.
          example: 20
          title: Limit
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformJobCollection'
          description: OK
  /transform/v1/jobs/{id}:
    get:
      description: Fetch an existing job by ID.
      parameters:
      - description: ID of the job to fetch.
        in: path
        name: id
        required: true
        schema:
          description: ID of the job to fetch.
          example: 5b45453c-cdd0-11ed-afa1-0242ac120002
          title: ID
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformJob'
          description: OK
    put:
      description: Create a new job with the given ID.
      parameters:
      - description: Only for testing. Maximum number of seconds to block the http
          request waiting for the job to complete. When the job finishes within this
          time the response is 200 OK with the complete job; otherwise 202 Accepted
          is returned with the job's initial state. Do not use this in production.
        in: query
        name: wait
        schema:
          description: Only for testing. Maximum number of seconds to block the http
            request waiting for the job to complete. When the job finishes within this
            time the response is 200 OK with the complete job; otherwise 202 Accepted
            is returned with the job's initial state. Do not use this in production.
          example: 60
          title: Wait
          type: integer
      - description: ID of the job to create.
        in: path
        name: id
        required: true
        schema:
          description: ID of the job to create.
          example: 5b45453c-cdd0-11ed-afa1-0242ac120002
          format: uuid
          title: ID
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                args:
                  description: Additional arguments that may be used by workflow actions.
                    Binary data may be provided inside a Data URI, including the 'name'
                    parameter.
                  title: Args
                  type: object
                data:
                  description: Raw JSON data of the GOBL Envelope or Object when the
                    Silo Entry ID is empty.
                  title: Data
                  type: object
                key:
                  description: Key to associate with the job for idempotency.
                  title: Key
                  type: string
                silo_entry_id:
                  description: ID for the entry in the silo as an alternative for
                    the raw data object.
                  title: Silo Entry ID
                  type: string
                tags:
                  description: Tags to associate with the job.
                  items:
                    type: string
                  title: Tags
                  type: array
                workflow_id:
                  description: UUID of the workflow to execute for this job.
                  title: Workflow ID
                  type: string
              required:
              - workflow_id
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformJob'
          description: OK. Returned only when the wait parameter was provided and the
            job completed in time; the body is the finished job with its intents, faults
            and attachments.
        "202":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformJob'
          description: Accepted. The job has been queued; the body holds its initial
            state with status "NA" and no intents yet.
  /transform/v1/jobs/key/{key}:
    get:
      description: Fetch an existing job by a recent key.
      parameters:
      - description: Key of the job to fetch.
        in: path
        name: key
        required: true
        schema:
          description: Key of the job to fetch.
          example: sample-key-00001
          title: Key
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformJob'
          description: OK
  /transform/v1/workflows:
    get:
      description: Fetch workflows in the current workspace.
      parameters:
      - description: Maximum number of workflows to return.
        in: query
        name: limit
        schema:
          description: Maximum number of workflows to return.
          example: 100
          title: Limit
          type: integer
      - description: Date from which results are provided.
        in: query
        name: created_at
        schema:
          description: Date from which results are provided.
          example: "2023-08-02T00:00:00.000Z"
          title: Created At
          type: string
      - description: Short schema name that the workflow will be allowed to process.
        in: query
        name: schema
        schema:
          description: Short schema name that the workflow will be allowed to process.
          example: bill/invoice
          title: Schema
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformWorkflowCollection'
          description: OK
  /transform/v1/workflows/{id}:
    get:
      description: Fetch an existing workflow given its UUID.
      parameters:
      - description: ID of the workflow to fetch.
        in: path
        name: id
        required: true
        schema:
          description: ID of the workflow to fetch.
          example: 5b45453c-cdd0-11ed-afa1-0242ac120002
          title: ID
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformWorkflow'
          description: OK
    patch:
      description: Update an existing workflow given its UUID.
      parameters:
      - description: UUID of the workflow to update.
        in: path
        name: id
        required: true
        schema:
          description: UUID of the workflow to update.
          example: 186522a6-e697-4e34-8498-eee961bcb845
          title: ID
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransformUpdateWorkflow'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformWorkflow'
          description: OK
    put:
      description: Create a new workflow with the given UUID.
      parameters:
      - description: UUID (any version) of the workflow to create.
        in: path
        name: id
        required: true
        schema:
          description: UUID (any version) of the workflow to create.
          example: 186522a6-e697-4e34-8498-eee961bcb845
          title: ID
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransformCreateWorkflow'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformWorkflow'
          description: OK
components:
  schemas:
    TransformCreateWorkflow:
      properties:
        country:
          description: ISO country code the workflow will be used in.
          example: ES
          title: Country Code
          type: string
        description:
          description: Description of the workflow.
          title: Description
          type: string
        draft:
          description: When true, the current version of the workflow will not be
            published.
          title: Draft
          type: boolean
        name:
          description: Name of the workflow.
          title: Name
          type: string
        rescue:
          description: Array of steps to execute in case of an unmanaged KO.
          items:
            $ref: '#/components/schemas/TransformStep'
          nullable: true
          title: Rescue
          type: array
        schema:
          description: Short schema name that the workflow will be allowed to process.
          example: bill/invoice
          title: Schema
          type: string
        steps:
          description: Array of Steps to use for this workflow.
          items:
            $ref: '#/components/schemas/TransformStep'
          nullable: true
          title: Steps
          type: array
      type: object
    TransformEvent:
      properties:
        args:
          additionalProperties:
            type: string
          description: Map of additional arguments that will be included in embedded
            actions.
          title: Arguments
          type: object
        at:
          description: When the event was created.
          example: "2021-09-15T15:04:05.999Z"
          title: At
          type: string
        code:
          description: Code assigned by the provider that may provide additional information
            about the event.
          title: Code
          type: string
        index:
          description: Index of the event in the intent.
          example: 0
          title: Index
          type: integer
        message:
          description: Message assigned by the provider that may provide additional
            information about the event, especially errors.
          title: Message
          type: string
        silo_entry_id:
          description: ID of the entry in the silo that was created by this event.
          title: Silo Entry ID
          type: string
        status:
          description: Status of the event.
          example: ERR
          title: Status
          type: string
      type: object
    TransformFault:
      properties:
        code:
          description: Code assigned by the provider that may provide additional information
            about the fault.
          title: Code
          type: string
        message:
          description: Message assigned by the provider that may provide additional
            information about the fault.
          title: Message
          type: string
        provider:
          description: ID of the provider that generated the fault.
          example: pdf
          title: Provider
          type: string
      type: object
    TransformFile:
      properties:
        category:
          description: Category of the file
          example: version
          title: Category
          type: string
        desc:
          description: Description of the file
          example: My file description.
          title: Description
          type: string
        hash:
          description: SHA256 hash of the file
          example: ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
          title: Hash
          type: string
        id:
          description: UUID for the file inside the entry
          example: b564ff94-7823-4f54-975e-280feb38df3f
          title: ID
          type: string
        key:
          description: Short identifier for the file.
          example: pdf
          title: Key
          type: string
        meta:
          additionalProperties:
            type: string
          description: Any additional data that might be relevant.
          title: Meta
          type: object
        mime:
          description: MIME type of the file
          example: application/pdf
          title: MIME
          type: string
        name:
          description: Name of the file
          example: my-file.pdf
          title: Name
          type: string
        size:
          description: Size of the file in bytes
          example: 12345
          title: Size
          type: integer
        url:
          description: Public URL where the file can be downloaded.
          title: URL
          type: string
      type: object
    TransformIntent:
      properties:
        completed:
          description: When true, this intent has completed.
          title: Completed
          type: boolean
        created_at:
          description: When the intent was created.
          title: Created At
          type: string
        events:
          description: Array of event objects tracking the execution of the intent.
          items:
            $ref: '#/components/schemas/TransformEvent'
          title: Events
          type: array
        id:
          description: UUIDv4 for the Intent
          example: b564ff94-7823-4f54-975e-280feb38df3f
          title: ID
          type: string
        name:
          description: Name of the executed workflow step
          example: PDF Generation
          title: Name
          type: string
        provider:
          description: ID of the provider to use
          example: pdf
          title: Provider
          type: string
        step_id:
          description: ID of the step to use
          example: 8d49556b-ff63-477b-9cd3-32c986c1c77b
          title: Step ID
          type: string
        updated_at:
          description: When the intent was last updated.
          title: Updated At
          type: string
      type: object
    TransformJob:
      properties:
        args:
          additionalProperties:
            type: string
          description: Any additional arguments that might be used by workflow actions.
          title: Args
          type: object
        attachments:
          description: Any files that have been generated while processing the job
            in the workflow will be here.
          items:
            $ref: '#/components/schemas/TransformFile'
          title: Attachments
          type: array
        completed_at:
          description: When this job was completed, will be nil if still ongoing.
          title: Completed At
          type: string
        created_at:
          description: When the job was created.
          title: Created At
          type: string
        envelope:
          description: Raw JSON data of the complete GOBL Envelope.
          title: GOBL Envelope
          type: object
        faults:
          description: Array of fault objects that represent errors that occurred
            during the processing of the job.
          items:
            $ref: '#/components/schemas/TransformFault'
          title: Faults
          type: array
        id:
          description: The UUID v7 or v1 of the job
          example: 5b45453c-cdd0-11ed-afa1-0242ac120002
          title: ID
          type: string
        intents:
          description: Array of intent objects following the execution of each of
            the steps of the associated workflow.
          items:
            $ref: '#/components/schemas/TransformIntent'
          title: Intents
          type: array
        key:
          description: Key assigned to the job, used to identify it in the system.
          title: Key
          type: string
        silo_entry_id:
          example: 75fa764a-cdd0-11ed-afa1-0242ac120002
          title: Silo Entry ID
          type: string
        status:
          description: Last known status text for this job.
          title: Status
          type: string
        tags:
          description: Any tags that may be useful to be associated with the job.
          items:
            type: string
          title: Tags
          type: array
        updated_at:
          description: When the job was last updated.
          title: Updated At
          type: string
        workflow_id:
          example: 186522a6-e697-4e34-8498-eee961bcb845
          title: Workflow ID
          type: string
      type: object
    TransformJobCollection:
      properties:
        list:
          description: Array of jobs sorted by creation time in descending order.
          items:
            $ref: '#/components/schemas/TransformJob'
          nullable: true
          title: List
          type: array
        created_at:
          description: Date from which results are provided in descending order.
          example: "2025-05-01T00:00:00.000Z"
          title: Created At
          type: string
        limit:
          description: Maximum number of jobs to show in a page of results, up to
            100.
          example: 20
          title: Limit
          type: integer
        cursor:
          description: Cursor used to identify the current page of results.
          title: Cursor
          type: string
        next_cursor:
          description: Cursor used to identify the next page of results.
          title: Next Cursor
          type: string
      type: object
    TransformNext:
      properties:
        code:
          description: Code to match against
          title: Code
          type: string
        status:
          description: Step status to match against, when empty this next step will
            always be executed.
          enum:
          - OK
          - SKIP
          - KO
          - TIMEOUT
          title: Status
          type: string
        step_id:
          description: ID of the step to execute next.
          example: 186522a6-e697-4e34-8498-eee961bcb845
          title: Step ID
          type: string
        steps:
          description: Array of steps to execute
          items:
            $ref: '#/components/schemas/TransformStep'
          title: Steps
          type: array
        stop:
          description: When true, the workflow will stop.
          title: Stop
          type: boolean
      type: object
    TransformStep:
      properties:
        action:
          description: ID of the action to execute
          example: email.send
          title: Action
          type: string
        config:
          description: JSON configuration sent to the provider
          title: Configuration
          type: object
        id:
          description: The UUID (any version) of the step.
          example: 186522a6-e697-4e34-8498-eee961bcb845
          title: ID
          type: string
        name:
          description: Name of the step
          title: Name
          type: string
        next:
          description: Optional array of next steps to execute after this one.
          items:
            $ref: '#/components/schemas/TransformNext'
          title: Next
          type: array
        notes:
          description: Additional internal details
          title: Notes
          type: string
        summary:
          description: Summary of the step's configuration.
          title: Summary
          type: string
      type: object
    TransformUpdateWorkflow:
      properties:
        description:
          description: Updated description.
          title: Description
          type: string
        draft:
          description: When true, the current version of the workflow will not be
            published.
          title: Draft
          type: boolean
        name:
          description: New name for the workflow.
          title: Name
          type: string
        rescue:
          description: Array of steps to execute in case of an unmanaged KO.
          items:
            $ref: '#/components/schemas/TransformStep'
          nullable: true
          title: Rescue
          type: array
        steps:
          description: Array of Steps to use for this workflow.
          items:
            $ref: '#/components/schemas/TransformStep'
          nullable: true
          title: Steps
          type: array
      type: object
    TransformWorkflow:
      properties:
        country:
          description: ISO country code the workflow will be used for.
          title: Country
          type: string
        created_at:
          description: When the workflow was created.
          title: Created At
          type: string
        description:
          description: Description of the workflow
          title: Description
          type: string
        disabled:
          description: When true, this workflow can no longer be used.
          title: Disabled
          type: boolean
        draft:
          description: When true, this workflow is still in draft mode and will not
            be used in jobs.
          title: Draft
          type: boolean
        hash:
          description: Partial SHA256 hash of the workflow's contents.
          title: Hash
          type: string
        id:
          description: The UUID (any version) of the workflow.
          example: 186522a6-e697-4e34-8498-eee961bcb845
          title: ID
          type: string
        name:
          description: Name of the workflow
          title: Name
          type: string
        rescue:
          description: List of steps to execute when a KO status is returned by a
            previous step and not explicitly managed.
          items:
            $ref: '#/components/schemas/TransformStep'
          nullable: true
          title: Rescue
          type: array
        schema:
          description: Short schema name that the workflow will be allowed to process.
          title: Schema
          type: string
        steps:
          description: List of steps to execute.
          items:
            $ref: '#/components/schemas/TransformStep'
          nullable: true
          title: Steps
          type: array
        updated_at:
          description: When the workflow was last updated.
          title: Updated At
          type: string
        version:
          description: Version of the workflow's contents currently defined.
          title: Version
          type: string
        versions:
          description: List of previously published versions of this workflow, only
            provided when requesting the primary workflow.
          items:
            $ref: '#/components/schemas/TransformWorkflowVersion'
          title: Versions
          type: array
      type: object
    TransformWorkflowCollection:
      properties:
        created_at:
          description: First or queried timestamp when the first entry in the page
            was created.
          title: Created At
          type: string
        limit:
          description: Maximum number of objects returned in a page.
          title: Limit
          type: integer
        list:
          description: List of workflows.
          items:
            $ref: '#/components/schemas/TransformWorkflow'
          nullable: true
          title: List
          type: array
        next_created_at:
          description: Timestamp that indicates the start of the next page of results,
            if any.
          title: Next Created At
          type: string
        schema:
          description: Short schema name that the workflows have been filtered by.
          example: bill/invoice
          title: Schema
          type: string
      type: object
    TransformWorkflowVersion:
      properties:
        created_at:
          description: Timestamp of when the version was created.
          title: Created At
          type: string
        hash:
          description: Partial hash to identify the workflow definition.
          title: Hash
          type: string
        name:
          description: Name of the previous version.
          title: Name
          type: string
        src:
          description: Key for the source of the version when created, like 'user'.
          title: Src
          type: string
        src_id:
          description: ID of the source object that published the version.
          title: Src ID
          type: string
        version:
          description: Version number of the workflow.
          title: Version
          type: string
      type: object
  securitySchemes:
    authToken:
      bearerFormat: JWT
      description: 'Use the `Bearer` scheme with a valid JWT token to authenticate
        requests. Example: `Authorization: Bearer <token>`'
      scheme: bearer
      type: http