Tvarka ATK API Tvarka ATK QES Signing API (paid Tier Addendum) API

openapi: 3.2.0
info:
  title: Tvarka ATK - QES Signing API (paid-tier addendum) Tvarka ATK QES Signing API (paid Tier Addendum) Tvarka ATK QES Signing API (paid Tier Addendum) API
  version: 1.3.0
  summary: LT ATK qualified signing, with optional Smart-ID and Mobile-ID PAdES methods.
  description: "The QES half of the ATK API - `/v1/sign/*`. This is the **paid-tier addendum** to\n`tvarka_atk_auth_api.openapi.yaml`: same providers, same credential model, same card stack and\ntwo-phase ceremony; QES adds document assembly, an async validation axis, and metering. The shared\nprimitive schemas + security schemes are mirrored here so this file validates standalone; they are\nidentical to the auth contract.\n\n## Flow (same shape as auth, over a document)\n  1. `POST /v1/sign/requests` (HTTP Basic) - the provider supplies the document (bytes or an\n     allow-listed `documentRef`, or a bare `hash` for `format:\"raw\"`), and receives `clientToken`.\n  2. `POST /v1/sign/{requestId}/certificate` (Bearer clientToken) - the client submits the card's\n     **signing** certificate; the API prepares the format-specific DTBS and returns it +\n     `operationToken`.\n  3. The client drives the card to sign the DTBS with the QES key (after PIN).\n  4. `POST /v1/sign/{requestId}/complete` (Bearer clientToken) - the API verifies the signature,\n     assembles + timestamps the AdES container, and returns `status:\"done\"` with\n     `validation:{status:\"pending\"}`.\n\n## Smart-ID and Mobile-ID flow\n  For `method:\"smart_id\"` or `method:\"mobile_id\"`, create a PAdES request with `personalCode`\n  and, for Mobile-ID, `phoneNumber`. The response has a user verification code and no\n  `clientToken`; poll GET with Basic credentials or consume the terminal webhook. The\n  `/certificate` and `/complete` calls are not used. Remote methods are PAdES-only in v1.3;\n  physical/NFC remain available for raw, ASiC-E, and ADOC.\n\n## Two axes: `done` vs `validation`\n  * `status:\"done\"` = the container is assembled AND the signer signature is verified. This is the\n    deliverable and the **billable** event.\n  * `validation.status` transitions `pending -> passed | failed` **asynchronously** (SiVa runs after\n    completion). The validator is **advisory, not authoritative** (LT/EU trusted-list snapshots have\n    wrongly flagged the primary QTSA); a sub-qualified result raises an alarm for review - it does\n    NOT change `status`, invalidate the container, or reverse billing.\n\n## Billing\n  One usage event **at completion**, never gated on an advisory validator: `atk.sign` for a signing\n  ceremony, and `atk.validate` / `atk.timestamp` / `atk.archive` for the v1.1 synchronous services.\n  Auth (`atk.auth`) is a separate, also-invoiceable event; whether a provider/tier is actually\n  charged is a pricing decision (ePaslaugos = zero-rated free tier; third parties = metered).\n\n## Timestamp + revocation\n  Qualified timestamp uses **APED** as the primary QTSA (BalTstamp fallback; ACCV opt-in for a\n  personal tier). The embedded revocation (OCSP) is fetched fresh at signing time and **never cached\n  or prefetched** - a cached OCSP response invalidates the signature.\n\n## Get access\n  Request a zero-rated sandbox key at <https://atk.tvarka.pro/docs/access/> (issued after a short\n  review). Full docs, rendered reference, and Postman collections at <https://atk.tvarka.pro/docs/>.\n"
  termsOfService: https://tvarka.pro
  contact:
    name: Tvarka
    url: https://atk.tvarka.pro/docs/
    email: info@tvarka.pro
  license:
    name: Proprietary
    url: https://tvarka.pro
  x-status: 'IMPLEMENTED through 2026-08-02 (tvarka/atk/ Django app): /sign/* physical and NFC ceremony for pades/raw/asice/adoc with inline or allow-listed documentRef input; TSA + B-LT/XAdES-T; async advisory SiVa; atk.sign metering at done; HMAC-signed `signStatus` webhooks (terminal + validation); per-provider rate limiting; finalizing-reaper crash recovery; retention purge + deletion (POST /v1/sign/{id}/delete, POST /v1/erasure). Sandbox IMPLEMENTED: environment=sandbox requests sign with Tvarka-issued test cards and produce deliberately non-qualified B-level artifacts (ATK_SANDBOX_TSA_URL instead of the production TSA, no B-LT upgrade, no SiVa — validation is `notApplicable`). Bare XAdES is intentionally outside v1; XAdES-T is delivered inside ASiC-E and ADOC. v1.1 accepts already-signed PAdES/ASiC-E/ADOC inputs for an additional signature, plus configuration-gated server-side Smart-ID/Mobile-ID PAdES, and exposes Basic-authenticated standalone validation, XAdES timestamping, and PAdES B-LT archive upgrade services with replay-safe metering. Android is the current production NFC client boundary; iOS client source is pre-release pending the Apple Developer account plus CoreNFC real-card release gates.'
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: Tvarka ATK QES Signing API (paid Tier Addendum)
paths: {}
webhooks:
  signStatus:
    post:
      operationId: receiveSignStatus
      summary: Terminal status + validation-change callback (per-tenant HMAC-signed)
      description: 'Sent to the provider''s `webhookUrl` on terminal `status` and on every `validation.status` change.

        Headers - `X-Atk-Signature: sha256=<HMAC-SHA256(secret, raw-body)>`, `X-Atk-Idempotency-Key`, and

        a timestamp. At-least-once; verify the MAC, reject stale timestamps, dedupe by idempotency key.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignRequestState'
      responses:
        2XX:
          description: Acknowledged.
      tags:
      - Tvarka ATK QES Signing API (paid Tier Addendum)
components:
  schemas:
    SignRequestState:
      type: object
      required:
      - requestId
      - method
      - status
      properties:
        requestId:
          type: string
          format: uuid
        method:
          $ref: '#/components/schemas/Method'
        status:
          $ref: '#/components/schemas/Status'
        verificationCode:
          type: string
          description: Present while a Smart-ID/Mobile-ID request is non-terminal.
        validation:
          $ref: '#/components/schemas/Validation'
        cert:
          type: object
          properties:
            subject:
              $ref: '#/components/schemas/CertSubject'
        sig:
          type: string
          format: byte
        sigAlgOid:
          type: string
        downloadToken:
          type: string
        error:
          $ref: '#/components/schemas/ErrorBody'
    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
    Validation:
      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.
    Method:
      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.
    CertSubject:
      type: object
      properties:
        serialNumber:
          type: string
          example: PNOLT-39001010000
        givenName:
          type: string
        sn:
          type: string
        cn:
          type: string
        c:
          type: string
          example: LT
    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
    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
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Provider server-to-server credentials `keyId:keySecret` (+ IP allow-list). Mirrors the auth contract.
    clientToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Short-lived per-request JWT with origin binding for browser clients. Mirrors the auth contract.
    downloadToken:
      type: apiKey
      in: query
      name: downloadToken
      description: One-off token returned with a completed sign result, for fetching the signed document.