openapi: 3.2.0
info:
  title: Tvarka Atk Sign API
  version: 1.3.0
  description: 'Operations tagged Sign across 2 of this provider''s published API definitions: tvarka-atk-api-openapi-original.json, tvarka-atk-api-sign-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://atk.tvarka.pro/v1
  description: 'Production. Sandbox runs on the same host - provider credentials issued with

    environment=sandbox get the identical API against test-card material and are never billed.

    '
security:
- basicAuth: []
tags:
- name: Sign
  description: The QES signing ceremony (`/v1/sign/*`).
paths:
  /sign/requests:
    servers:
    - url: https://atk.tvarka.pro/v1
      description: 'Production. Sandbox runs on the same host - provider credentials issued with

        environment=sandbox get the identical API against test-card material and are never billed.

        '
    post:
      tags:
      - Sign
      operationId: createSignRequest
      summary: Create a signing request (server-to-server)
      description: 'HTTP Basic. Provide the document one of three ways - inline `document` (base64), an allow-listed

        `documentRef`, or a bare `hash` (only for `format:"raw"`). Container formats

        (pades/asice/adoc) require exactly one of `document` or `documentRef`. PAdES accepts an unsigned

        or already-signed PDF; ASiC-E/ADOC accept either a PDF (Tvarka constructs a new single-payload

        container) or an existing valid container, which is treated as an opaque whole and receives one

        additional signature without payload or attachment edits. Physical requests return a client

        token, NFC returns a pairing hint, and Smart-ID/Mobile-ID return a user verification code.

        Remote methods are PAdES-only and stay server-side.

        '
      x-codeSamples:
      - lang: curl
        label: Smart-ID PAdES
        source: "curl -u \"$ATK_KEY_ID:$ATK_KEY_SECRET\" https://atk.tvarka.pro/v1/sign/requests \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"format\":\"pades\",\"method\":\"smart_id\",\"personalCode\":\"39001010000\",\"document\":\"<base64-pdf>\"}'\n"
      - lang: curl
        label: Mobile-ID PAdES
        source: "curl -u \"$ATK_KEY_ID:$ATK_KEY_SECRET\" https://atk.tvarka.pro/v1/sign/requests \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"format\":\"pades\",\"method\":\"mobile_id\",\"personalCode\":\"39001010000\",\"phoneNumber\":\"+37061234567\",\"document\":\"<base64-pdf>\"}'\n"
      security:
      - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignSignRequestCreate'
            examples:
              physicalAtk:
                summary: Primary ATK PAdES method
                value:
                  format: pades
                  method: physical
                  document: JVBERi0xLjQK
              smartId:
                summary: Optional Smart-ID PAdES method
                value:
                  format: pades
                  method: smart_id
                  personalCode: '39001010000'
                  document: JVBERi0xLjQK
              mobileId:
                summary: Optional Mobile-ID PAdES method
                value:
                  format: pades
                  method: mobile_id
                  personalCode: '39001010000'
                  phoneNumber: '+37061234567'
                  document: JVBERi0xLjQK
      responses:
        '202':
          description: Request created; awaiting the ATK client or remote user authorization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignSignRequestCreated'
        '400':
          $ref: '#/components/responses/SignBadRequest'
        '401':
          $ref: '#/components/responses/SignUnauthorized'
        '403':
          $ref: '#/components/responses/SignForbidden'
        '413':
          $ref: '#/components/responses/SignTooLarge'
        '429':
          $ref: '#/components/responses/SignRateLimited'
        '503':
          $ref: '#/components/responses/SignServiceUnavailable'
  /sign/{requestId}/certificate:
    servers:
    - url: https://atk.tvarka.pro/v1
      description: 'Production. Sandbox runs on the same host - provider credentials issued with

        environment=sandbox get the identical API against test-card material and are never billed.

        '
    post:
      tags:
      - Sign
      operationId: submitSignCertificate
      summary: Submit the card's signing certificate; receive the DTBS
      description: 'Bearer clientToken. The API validates the certificate (chain, revocation, purpose =

        signing/content-commitment, qualified/QSCD evidence), prepares the format-specific DTBS (for

        PAdES - the SHA-256 CAdES SignedAttributes digest; SHA-256 for both key curves), and returns

        it + `operationToken`. Physical/NFC only.

        '
      security:
      - clientToken: []
      parameters:
      - $ref: '#/components/parameters/SignRequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignSignCertificateSubmit'
      responses:
        '200':
          description: DTBS + operation token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignSignCertificateChallenge'
        '401':
          $ref: '#/components/responses/SignUnauthorized'
        '403':
          $ref: '#/components/responses/SignForbidden'
        '404':
          $ref: '#/components/responses/SignNotFound'
        '409':
          $ref: '#/components/responses/SignConflict'
        '422':
          $ref: '#/components/responses/SignUnprocessable'
  /sign/{requestId}/complete:
    servers:
    - url: https://atk.tvarka.pro/v1
      description: 'Production. Sandbox runs on the same host - provider credentials issued with

        environment=sandbox get the identical API against test-card material and are never billed.

        '
    post:
      tags:
      - Sign
      operationId: completeSign
      summary: Submit the raw card signature; assemble the container
      description: 'Bearer clientToken + single-use `operationToken`. Synchronous: the API verifies the signature

        against the stored DTBS + cert, assembles + timestamps the AdES container inline, schedules

        async validation, and returns `200 done` with `validation:{status:"pending"}` (or

        `notApplicable` in sandbox/raw, or the internal ADOC verdict). `finalizing` is observable via

        GET only if a crash wedges the request until the reaper releases it. Retry-safe; a transient

        assembly failure returns a retryable 5xx with the operation released; one `atk.sign` charge

        at `done`. Physical/NFC only; remote methods complete asynchronously.

        '
      security:
      - clientToken: []
      parameters:
      - $ref: '#/components/parameters/SignRequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignSignCompleteSubmit'
      responses:
        '200':
          description: Done - container assembled + signature verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignSignResult'
        '401':
          $ref: '#/components/responses/SignUnauthorized'
        '404':
          $ref: '#/components/responses/SignNotFound'
        '409':
          $ref: '#/components/responses/SignConflict'
        '422':
          $ref: '#/components/responses/SignUnprocessable'
  /sign/{requestId}:
    servers:
    - url: https://atk.tvarka.pro/v1
      description: 'Production. Sandbox runs on the same host - provider credentials issued with

        environment=sandbox get the identical API against test-card material and are never billed.

        '
    get:
      tags:
      - Sign
      operationId: getSignRequest
      summary: Poll status + validation axis; fetch the result
      security:
      - basicAuth: []
      - clientToken: []
      parameters:
      - $ref: '#/components/parameters/SignRequestId'
      responses:
        '200':
          description: Current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignSignRequestState'
        '401':
          $ref: '#/components/responses/SignUnauthorized'
        '404':
          $ref: '#/components/responses/SignNotFound'
  /sign/{requestId}/document:
    servers:
    - url: https://atk.tvarka.pro/v1
      description: 'Production. Sandbox runs on the same host - provider credentials issued with

        environment=sandbox get the identical API against test-card material and are never billed.

        '
    get:
      tags:
      - Sign
      operationId: downloadSignedDocument
      summary: Download the signed container
      description: Authorized by the provider's Basic credentials or a `downloadToken` query param.
      security:
      - basicAuth: []
      - downloadToken: []
      parameters:
      - $ref: '#/components/parameters/SignRequestId'
      responses:
        '200':
          description: The signed container bytes.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/SignUnauthorized'
        '404':
          $ref: '#/components/responses/SignNotFound'
  /sign/{requestId}/cancel:
    servers:
    - url: https://atk.tvarka.pro/v1
      description: 'Production. Sandbox runs on the same host - provider credentials issued with

        environment=sandbox get the identical API against test-card material and are never billed.

        '
    post:
      tags:
      - Sign
      operationId: cancelSignRequest
      summary: Cancel a non-terminal request
      security:
      - basicAuth: []
      - clientToken: []
      parameters:
      - $ref: '#/components/parameters/SignRequestId'
      responses:
        '200':
          description: Cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignSignRequestState'
        '404':
          $ref: '#/components/responses/SignNotFound'
        '409':
          $ref: '#/components/responses/SignConflict'
  /sign/{requestId}/pairing:
    servers:
    - url: https://atk.tvarka.pro/v1
      description: 'Production. Sandbox runs on the same host - provider credentials issued with

        environment=sandbox get the identical API against test-card material and are never billed.

        '
    get:
      tags:
      - Sign
      operationId: getSignPairing
      summary: Rotate and return the NFC pairing token for a sign request
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/SignRequestId'
      responses:
        '200':
          description: Newly rotated pairing token and links.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignPairingInfo'
        '404':
          $ref: '#/components/responses/SignNotFound'
        '409':
          $ref: '#/components/responses/SignConflict'
  /pairing/claim:
    servers:
    - url: https://atk.tvarka.pro/v1
      description: 'Production. Sandbox runs on the same host - provider credentials issued with

        environment=sandbox get the identical API against test-card material and are never billed.

        '
    post:
      tags:
      - Sign
      operationId: claimPairing
      summary: Atomically claim an auth or sign NFC pairing
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PairingClaimRequest'
      responses:
        '200':
          description: Request-scoped client token for the phone.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PairingClaimResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    SignErrorCode:
      type: string
      description: 'The full stable error-code catalog of the ATK API family (auth + sign + services);

        each endpoint returns the subset that applies to it. By HTTP status:

        400 invalid_json, missing_field, invalid_field, invalid_webhook_url, invalid_document_ref.

        401 invalid_basic_credentials, invalid_client_token, client_token_expired,

        operation_token_expired, invalid_download_token.

        403 origin_not_allowed, ip_not_allowed, format_not_allowed, document_ref_host_not_allowed,

        method_not_allowed, tenant_suspended, tier_forbidden.

        404 request_not_found, pairing_not_found, document_not_ready.

        409 request_terminal, operation_token_spent, identity_swap, idempotency_conflict,

        service_in_progress, pairing_not_available, pairing_already_claimed.

        410 pairing_expired. 413 document_too_large.

        422 cert_invalid, untrusted_chain, cert_revoked, cert_expired, not_qualified,

        cert_purpose_mismatch, signature_invalid, document_hash_mismatch, document_size_mismatch.

        429 rate_limited. 500 assembly_failed. 502 document_ref_fetch_failed.

        503 erasure_failed, pairing_service_unavailable, service_unavailable.

        The catalog can grow in minor versions - fall back to HTTP status semantics

        for codes you do not recognize.

        '
      enum:
      - invalid_json
      - missing_field
      - invalid_field
      - invalid_webhook_url
      - invalid_document_ref
      - invalid_basic_credentials
      - invalid_client_token
      - client_token_expired
      - operation_token_expired
      - invalid_download_token
      - origin_not_allowed
      - ip_not_allowed
      - format_not_allowed
      - document_ref_host_not_allowed
      - method_not_allowed
      - tenant_suspended
      - tier_forbidden
      - request_not_found
      - pairing_not_found
      - document_not_ready
      - request_terminal
      - operation_token_spent
      - identity_swap
      - idempotency_conflict
      - service_in_progress
      - pairing_not_available
      - pairing_already_claimed
      - pairing_expired
      - document_too_large
      - cert_invalid
      - untrusted_chain
      - cert_revoked
      - cert_expired
      - not_qualified
      - cert_purpose_mismatch
      - signature_invalid
      - document_hash_mismatch
      - document_size_mismatch
      - rate_limited
      - assembly_failed
      - document_ref_fetch_failed
      - erasure_failed
      - pairing_service_unavailable
      - service_unavailable
    SignCertSubject:
      type: object
      properties:
        serialNumber:
          type: string
          example: PNOLT-39001010000
        givenName:
          type: string
        sn:
          type: string
        cn:
          type: string
        c:
          type: string
          example: LT
    SignValidation:
      type: object
      description: The advisory validation axis. Independent of `status`. See the two-axes note.
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - pending
          - passed
          - failed
          - notApplicable
        level:
          type: string
          description: e.g. QUALIFIED_VALID, VALID_NOT_QUALIFIED, INDETERMINATE.
        report:
          type: string
          description: Optional pointer/id to the stored validation report.
    ErrorBody:
      type: object
      required:
      - code
      - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
          description: 'Stable machine code. documentRef failures use `invalid_document_ref`,

            `document_ref_host_not_allowed`, `document_ref_fetch_failed`,

            `document_size_mismatch`, `document_hash_mismatch`, or `document_too_large`.

            '
        message:
          type: string
        requestId:
          type: string
          format: uuid
        retryable:
          type: boolean
    SignPairingHint:
      type: object
      properties:
        pairingUrl:
          type: string
          format: uri
          example: https://sign.tvarka.pro/atk-login/#PAIRING_TOKEN
        deepLink:
          type: string
          example: tvarkasign://atk/pair/PAIRING_TOKEN
        qrPayload:
          type: string
          example: https://sign.tvarka.pro/atk-login/#PAIRING_TOKEN
    SignSignRequestCreated:
      type: object
      required:
      - requestId
      - method
      - verificationCode
      - status
      - expiresAt
      description: Physical requests return `clientToken`; NFC returns `pairing`; remote methods return neither.
      properties:
        requestId:
          type: string
          format: uuid
        method:
          $ref: '#/components/schemas/SignMethod'
        verificationCode:
          type: string
          description: NFC anti-relay code, or the user verification code for Smart-ID/Mobile-ID.
        clientToken:
          type: string
        status:
          $ref: '#/components/schemas/SignStatus'
        expiresAt:
          type: string
          format: date-time
        pairing:
          allOf:
          - $ref: '#/components/schemas/SignPairingHint'
          description: Present only when method == nfc.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
    SignSignCompleteSubmit:
      type: object
      required:
      - signature
      - signatureAlgorithm
      - operationToken
      properties:
        signature:
          type: string
          format: byte
          description: Base64 raw card signature over `dtbs` (QES key).
        signatureAlgorithm:
          $ref: '#/components/schemas/SignSignatureAlgorithm'
        signatureEncoding:
          $ref: '#/components/schemas/SignSignatureEncoding'
        operationToken:
          type: string
    SignSignatureAlgorithm:
      type: string
      enum:
      - ES256
      - ES384
    SignFormat:
      type: string
      enum:
      - pades
      - asice
      - adoc
      - raw
      description: 'pades = signed PDF; asice/adoc = XAdES-T containers; raw = a detached CAdES package from

        a bare hash (no container returned). Container formats require `document` or `documentRef`.

        '
    SignSignCertificateChallenge:
      type: object
      required:
      - requestId
      - dtbs
      - dtbsHashAlgOid
      - operationToken
      - cert
      - signing
      properties:
        requestId:
          type: string
          format: uuid
        dtbs:
          type: string
          format: byte
          description: Base64 of the exact digest the card signs (e.g. for PAdES, the curve-matched digest of the CAdES SignedAttributes).
        dtbsHashAlgOid:
          $ref: '#/components/schemas/SignHashAlgOid'
        operationToken:
          type: string
        verificationCode:
          type: string
        cert:
          type: object
          properties:
            subject:
              $ref: '#/components/schemas/SignCertSubject'
        signing:
          type: object
          properties:
            format:
              $ref: '#/components/schemas/SignFormat'
            signatureEncodingHints:
              type: string
              description: Optional hint for how the card signature should be encoded before submission (P1363 vs DER).
    SignSignResult:
      type: object
      required:
      - status
      - method
      - validation
      - cert
      properties:
        status:
          type: string
          const: done
        method:
          $ref: '#/components/schemas/SignMethod'
        validation:
          $ref: '#/components/schemas/SignValidation'
        sig:
          type: string
          format: byte
          description: For `format:"raw"`, the detached signature package. Absent for container formats (download the container instead).
        sigAlgOid:
          type: string
        cert:
          type: object
          properties:
            subject:
              $ref: '#/components/schemas/SignCertSubject'
        downloadToken:
          type: string
          description: One-off token for GET /sign/{id}/document.
    SignSignRequestState:
      type: object
      required:
      - requestId
      - method
      - status
      properties:
        requestId:
          type: string
          format: uuid
        method:
          $ref: '#/components/schemas/SignMethod'
        status:
          $ref: '#/components/schemas/SignStatus'
        verificationCode:
          type: string
          description: Present while a Smart-ID/Mobile-ID request is non-terminal.
        validation:
          $ref: '#/components/schemas/SignValidation'
        cert:
          type: object
          properties:
            subject:
              $ref: '#/components/schemas/SignCertSubject'
        sig:
          type: string
          format: byte
        sigAlgOid:
          type: string
        downloadToken:
          type: string
        error:
          $ref: '#/components/schemas/SignErrorBody'
    ErrorCode:
      type: string
      description: 'The full stable error-code catalog of the ATK API family (auth + sign + services);

        each endpoint returns the subset that applies to it. By HTTP status:

        400 invalid_json, missing_field, invalid_field, invalid_webhook_url, invalid_document_ref.

        401 invalid_basic_credentials, invalid_client_token, client_token_expired,

        operation_token_expired, invalid_download_token.

        403 origin_not_allowed, ip_not_allowed, format_not_allowed, document_ref_host_not_allowed,

        method_not_allowed, tenant_suspended, tier_forbidden.

        404 request_not_found, pairing_not_found, document_not_ready.

        409 request_terminal, operation_token_spent, identity_swap, idempotency_conflict,

        service_in_progress, pairing_not_available, pairing_already_claimed.

        410 pairing_expired. 413 document_too_large.

        422 cert_invalid, untrusted_chain, cert_revoked, cert_expired, not_qualified,

        cert_purpose_mismatch, signature_invalid, document_hash_mismatch, document_size_mismatch.

        429 rate_limited. 500 assembly_failed. 502 document_ref_fetch_failed.

        503 erasure_failed, pairing_service_unavailable, service_unavailable.

        The catalog can grow in minor versions - fall back to HTTP status semantics

        for codes you do not recognize.

        '
      enum:
      - invalid_json
      - missing_field
      - invalid_field
      - invalid_webhook_url
      - invalid_document_ref
      - invalid_basic_credentials
      - invalid_client_token
      - client_token_expired
      - operation_token_expired
      - invalid_download_token
      - origin_not_allowed
      - ip_not_allowed
      - format_not_allowed
      - document_ref_host_not_allowed
      - method_not_allowed
      - tenant_suspended
      - tier_forbidden
      - request_not_found
      - pairing_not_found
      - document_not_ready
      - request_terminal
      - operation_token_spent
      - identity_swap
      - idempotency_conflict
      - service_in_progress
      - pairing_not_available
      - pairing_already_claimed
      - pairing_expired
      - document_too_large
      - cert_invalid
      - untrusted_chain
      - cert_revoked
      - cert_expired
      - not_qualified
      - cert_purpose_mismatch
      - signature_invalid
      - document_hash_mismatch
      - document_size_mismatch
      - rate_limited
      - assembly_failed
      - document_ref_fetch_failed
      - erasure_failed
      - pairing_service_unavailable
      - service_unavailable
    SignStatus:
      type: string
      description: 'Non-terminal - pending/awaitingCard/awaitingCredentials/finalizing. Terminal success - done.

        Terminal failure - cancelled/timeout/deviceError/pinBlocked/cardRemoved/certInvalid.

        Validation failure is on the `validation` axis, NOT here.

        '
      enum:
      - pending
      - awaitingCard
      - awaitingCredentials
      - finalizing
      - done
      - cancelled
      - timeout
      - deviceError
      - pinBlocked
      - cardRemoved
      - certInvalid
    PairingClaimRequest:
      type: object
      required:
      - pairingToken
      properties:
        pairingToken:
          type: string
          minLength: 32
          maxLength: 200
        claimNonce:
          type: string
          maxLength: 120
        device:
          type: object
          additionalProperties: false
          properties:
            platform:
              type: string
              maxLength: 40
            appVersion:
              type: string
              maxLength: 40
            deviceName:
              type: string
              maxLength: 120
    SignErrorBody:
      type: object
      required:
      - code
      - message
      properties:
        code:
          $ref: '#/components/schemas/SignErrorCode'
          description: 'Stable machine code. documentRef failures use `invalid_document_ref`,

            `document_ref_host_not_allowed`, `document_ref_fetch_failed`,

            `document_size_mismatch`, `document_hash_mismatch`, or `document_too_large`.

            '
        message:
          type: string
        requestId:
          type: string
          format: uuid
        retryable:
          type: boolean
    SignHashAlgOid:
      type: string
      enum:
      - 2.16.840.1.101.3.4.2.1
      - 2.16.840.1.101.3.4.2.2
      description: SHA-256 / SHA-384 OID, curve-matched.
    SignPairingInfo:
      allOf:
      - $ref: '#/components/schemas/SignPairingHint'
      - type: object
        required:
        - pairingToken
        - expiresAt
        properties:
          pairingToken:
            type: string
          expiresAt:
            type: string
            format: date-time
    Status:
      type: string
      description: 'Non-terminal - pending/awaitingCard/awaitingCredentials/finalizing. Terminal success - done.

        Terminal failure - cancelled/timeout/deviceError/pinBlocked/cardRemoved/certInvalid.

        Validation failure is on the `validation` axis, NOT here.

        '
      enum:
      - pending
      - awaitingCard
      - awaitingCredentials
      - finalizing
      - done
      - cancelled
      - timeout
      - deviceError
      - pinBlocked
      - cardRemoved
      - certInvalid
    SignSignCertificateSubmit:
      type: object
      required:
      - certificate
      properties:
        certificate:
          type: string
          format: byte
          description: Base64 DER of the card's signing certificate.
    SignMethod:
      type: string
      enum:
      - physical
      - nfc
      - smart_id
      - mobile_id
      example: physical
      description: physical/NFC use card endpoints; smart_id/mobile_id complete server-side and support PAdES only.
    SignSignRequestCreate:
      description: ATK supports every listed format; Smart-ID/Mobile-ID support PAdES only.
      oneOf:
      - title: ATK raw detached CAdES
        type: object
        required:
        - format
        - method
        - hash
        - hashAlgOid
        additionalProperties: false
        properties:
          format:
            const: raw
          method:
            type: string
            enum:
            - physical
            - nfc
            example: physical
          hash:
            type: string
            format: byte
          hashAlgOid:
            $ref: '#/components/schemas/SignHashAlgOid'
          filename:
            type: string
          mimeType:
            type: string
          message:
            type: string
          externalId:
            type: string
          webhookUrl:
            type: string
            format: uri
      - title: ATK PDF or container
        type: object
        required:
        - format
        - method
        additionalProperties: false
        properties:
          format:
            enum:
            - pades
            - asice
            - adoc
          method:
            type: string
            enum:
            - physical
            - nfc
            example: physical
          document:
            type: string
            format: byte
          documentRef:
            $ref: '#/components/schemas/SignDocumentRef'
          filename:
            type: string
          mimeType:
            type: string
          message:
            type: string
          externalId:
            type: string
          webhookUrl:
            type: string
            format: uri
        oneOf:
        - required:
          - document
          properties:
            document: {}
        - required:
          - documentRef
          properties:
            documentRef: {}
      - title: Smart-ID PAdES
        type: object
        required:
        - format
        - method
        - personalCode
        additionalProperties: false
        properties:
          format:
            type: string
            const: pades
          method:
            type: string
            const: smart_id
          personalCode:
            type: string
            pattern: ^[0-9]{11}$
            example: '39001010000'
          document:
            type: string
            format: byte
          documentRef:
            $ref: '#/components/schemas/SignDocumentRef'
          filename:
            type: string
          mimeType:
            type: string
          message:
            type: string
          externalId:
            type: string
          webhookUrl:
            type: string
            format: uri
        oneOf:
        - required:
          - document
          properties:
            document: {}
        - required:
          - documentRef
          properties:
            documentRef: {}
      - title: Mobile-ID PAdES
        type: object
        required:
        - format
        - method
        - personalCode
        - phoneNumber
        additionalProperties: false
        properties:
          format:
            type: string
            const: pades
          method:
            type: string
            const: mobile_id
          personalCode:
            type: string
            pattern: ^[0-9]{11}$
            example: '39001010000'
          phoneNumber:
            type: string
            pattern: ^\+3706[0-9]{7}$
            example: '+37061234567'
          document:
            type: string
            format: byte
          documentRef:
            $ref: '#/components/schemas/SignDocumentRef'
          filename:
            type: string
          mimeType:
            type: string
          message:
            type: string
          externalId:
            type: string
          webhookUrl:
            type: string
            format: uri
        oneOf:
        - required:
          - document
          properties:
            document: {}
        - required:
          - documentRef
          properties:
            documentRef: {}
    SignSignatureEncoding:
      type: string
      enum:
      - P1363
      - DER
      default: P1363
      description: Informational - the server auto-detects and accepts either encoding regardless of this field.
    SignDocumentRef:
      type: object
      description: 'Backend-fetched document. Hard SSRF controls apply - HTTPS only, host allow-list, no

        private/loopback/link-local, DNS-rebind protection, size cap enforced pre + mid stream, and the

        fetched bytes are verified against `sha256`. `authorization` is used only for the fetch, never

        logged or persisted.

        '
      required:
      - url
      - sha256
      - sizeBytes
      additionalProperties: false
      properties:
        url:
          type: string
          format: uri
          pattern: ^https://
        sha256:
          type: string
          pattern: ^[0-9a-fA-F]{64}$
        sizeBytes:
          type: integer
          minimum: 1
        authorization:
          type: string
          maxLength: 2048
    PairingClaimResponse:
      type: object
      required:
      - requestId
      - purpose
      - clientToken
      - status
      - expiresAt
      - verificationCode
      - summary
      properties:
        requestId:
          type: string
          format: uuid
        purpose:
          type: string
          enum:
          - auth
          - sign
        clientToken:
          type: string
        status:
          $ref: '#/components/schemas/Status'
        expiresAt:
          type: string
          format: date-time
        verificationCode:
          type: string
        summary:
          type: object
          additionalProperties: true
    SignError:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/SignErrorBody'
  parameters:
    SignRequestId:
      name: requestId
      in: path
      required: true
      schema:
        type: string
        format: uuid
  responses:
    SignConflict:
      description: Spent operation token, identity swap, terminal request, or idempotency conflict/in-progress operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignError'
    SignUnprocessable:
      description: Cert purpose/chain/revocation/qualified reject, dtbs mismatch, bad signature, doc hash mismatch.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignError'
    SignServiceUnavailable:
      description: Validation/TSA/revocation dependency failed transiently; retry with the same Idempotency-Key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignError'
    Conflict:
      description: Spent operation token, identity swap, terminal request, or idempotency conflict/in-progress operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    SignTooLarge:
      description: Document exceeds the tenant's max size.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignError'
    SignNotFound:
      description: Unknown request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignError'
    NotFound:
      description: Unknown request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    SignBadRequest:
      description: Malformed input (e.g. container format without document, hash without raw).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignError'
    RateLimited:
      description: Too many requests.
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    SignRateLimited:
      description: Too many requests.
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignError'
    SignUnauthorized:
      description: Missing/invalid credentials or client token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignError'
    SignForbidden:
      description: Format not allowed / origin not allowed / tenant suspended.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignError'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Provider server-to-server credentials `keyId:keySecret`. Server-to-server only, also gated by the

        provider''s server IP allow-list. Never placed in a browser/mobile client.

        '
    clientToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Short-lived, per-request JWT (`ES256`) minted at request creation, scoped

        `{tenant, requestId, purpose, method, allowedOrigins}`. Safe to hand to a browser/mobile client:

        it cannot create requests, read tenant data, or touch other requests. For browser clients the API

        enforces `Origin` against `allowedOrigins` (rejects cross-origin replay).

        '
    downloadToken:
      type: apiKey
      in: query
      name: downloadToken
      description: One-off token returned with a completed sign result, for fetching the signed document.
externalDocs:
  description: Quickstart, SDKs, test data, pricing and lifecycle policy
  url: https://atk.tvarka.pro/docs/
x-refined-from:
- tvarka-atk-api-openapi-original.json
- tvarka-atk-api-sign-openapi.yaml