openapi: 3.0.0
info:
  contact:
    email: dev@invopop.com
    name: Invopop Developers
  description: >-
    The Invopop Transform Service API offers end points to be able 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 and provide a response, 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 and provide a response, 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 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: WorkflowID description
                  title: Workflow ID
                  type: string
              required:
                - workflow_id
              type: object
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformJob'
          description: Accepted
    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 and provide a response, 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 and provide a response, 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 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: WorkflowID description
                  title: Workflow ID
                  type: string
              required:
                - workflow_id
              type: object
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformJob'
          description: Accepted
  /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 en 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 en 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