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: tvarkaAtk
    url: ../openapi/tvarka-atk-api-openapi-original.json
    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