Validate, timestamp and archive an existing signed document

arazzo: 1.0.1
info:
  title: Validate, timestamp and archive an existing signed document
  summary: >-
    The three stateless trust services in sequence - validate a container, add qualified timestamps
    to untimestamped XAdES, upgrade PAdES B-T to B-LT, then download the output.
  version: 1.0.0
sourceDescriptions:
- name: ltvApi
  url: ../openapi/tvarka-atk-api-ltv-api-openapi.yml
  type: openapi
- name: validationApi
  url: ../openapi/tvarka-atk-api-validation-api-openapi.yml
  type: openapi
workflows:
- workflowId: validate-timestamp-archive
  summary: Run the long-term-validation chain over a signed document.
  description: >-
    Every step here requires an Idempotency-Key header, scoped to your provider plus that
    operation. Reuse the same key on retry - that is the documented recovery path for a 503, and an
    idempotent retry does not create a second usage event. A different payload under the same key
    returns 409 idempotency_conflict; a call still running under it returns 409 service_in_progress.
  inputs:
    type: object
    required: [document, format]
    properties:
      document:
        type: string
        description: Base64 container bytes, or use documentRef against an allow-listed host.
      format:
        type: string
        enum: [pades, asice, adoc, raw]
      idempotencyKeyValidate:
        type: string
        description: 1-255 visible characters. Stable per logical operation, NOT per attempt.
      idempotencyKeyTimestamp:
        type: string
      idempotencyKeyArchive:
        type: string
  steps:
  - stepId: validate
    description: Advisory validation - returns the qualification level, nothing to download.
    operationId: validateDocument
    parameters:
    - name: Idempotency-Key
      in: header
      value: $inputs.idempotencyKeyValidate
    requestBody:
      contentType: application/json
      payload:
        format: $inputs.format
        document: $inputs.document
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      requestId: $response.body#/requestId
      validationStatus: $response.body#/validation/status
      validationLevel: $response.body#/validation/level
  - stepId: timestamp
    description: Add qualified timestamps to untimestamped XAdES signatures.
    operationId: timestampDocument
    parameters:
    - name: Idempotency-Key
      in: header
      value: $inputs.idempotencyKeyTimestamp
    requestBody:
      contentType: application/json
      payload:
        format: $inputs.format
        document: $inputs.document
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      requestId: $response.body#/requestId
      timestampedSignatures: $response.body#/timestampedSignatures
      downloadToken: $response.body#/downloadToken
  - stepId: archive
    description: Upgrade a PAdES B-T signature to PAdES B-LT for long-term validation.
    operationId: archiveDocument
    parameters:
    - name: Idempotency-Key
      in: header
      value: $inputs.idempotencyKeyArchive
    requestBody:
      contentType: application/json
      payload:
        format: pades
        document: $inputs.document
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      requestId: $response.body#/requestId
      level: $response.body#/level
      archived: $response.body#/archived
      downloadToken: $response.body#/downloadToken
  - stepId: download-archived
    description: Retrieve the upgraded container with the one-off download token.
    operationId: downloadServiceDocument
    parameters:
    - name: requestId
      in: path
      value: $steps.archive.outputs.requestId
    - name: downloadToken
      in: query
      value: $steps.archive.outputs.downloadToken
    successCriteria:
    - condition: $statusCode == 200
  outputs:
    validationLevel: $steps.validate.outputs.validationLevel
    timestampedSignatures: $steps.timestamp.outputs.timestampedSignatures
    archivedLevel: $steps.archive.outputs.level
x-provenance:
  generated: '2026-08-09'
  method: generated
  source: openapi/tvarka-atk-api-openapi-original.json
  operationIds_verified: true