Certifaction Signing API

openapi: 3.2.0
info:
  title: '{{ .ProductName }} Local Signing API'
  description: 'A proxy server for integrating with the {{ .ProductName }} platform.


    ## Setup requirements


    1. Authentication is required to perform some operations. Please refer to the [Authentication](https://developers.certifaction.com/en/references/authentication) section to obtain an API Key or token.

    2. Start the local server on the CLI using the command `{{ .CommandName }} server`


    Refer to [our setup guide](https://developers.certifaction.com/en/guides/getting-started-api) to get started.

    '
  version: ''
servers:
- url: http://localhost:{port}
  variables:
    port:
      default: '8081'
security:
- api_key: []
tags:
- name: Signing
  description: Sign files and request signatures
paths:
  /prepare:
    post:
      operationId: prepare_file
      parameters:
      - $ref: '#/components/parameters/digital_twin'
      - $ref: '#/components/parameters/pdf-a'
      - $ref: '#/components/parameters/accept_language'
      - $ref: '#/components/parameters/prepare_scope'
      - $ref: '#/components/parameters/signature_anchors'
      - $ref: '#/components/parameters/additional_page'
      - $ref: '#/components/parameters/qr_llx'
      - $ref: '#/components/parameters/qr_lly'
      - $ref: '#/components/parameters/qr_height'
      - $ref: '#/components/parameters/qr_page'
      - $ref: '#/components/parameters/encryption_key'
      - $ref: '#/components/parameters/password_encryption'
      summary: Prepare a file for signing
      requestBody:
        description: The file to prepare.
        required: true
        content:
          application/pdf: {}
      responses:
        200:
          description: The prepared file content.
          content:
            application/pdf:
              schema:
                type: string
        400:
          $ref: '#/components/responses/bad_request'
        401:
          $ref: '#/components/responses/unauthorized'
      tags:
      - Signing
  /sign:
    post:
      operationId: sign_file
      parameters:
      - $ref: '#/components/parameters/digital_twin'
      - $ref: '#/components/parameters/pdf-a'
      - $ref: '#/components/parameters/accept_language'
      - $ref: '#/components/parameters/additional_page'
      - $ref: '#/components/parameters/qr_llx'
      - $ref: '#/components/parameters/qr_lly'
      - $ref: '#/components/parameters/qr_height'
      - $ref: '#/components/parameters/qr_page'
      - $ref: '#/components/parameters/encryption_key'
      - $ref: '#/components/parameters/password_encryption'
      - name: hash
        in: query
        schema:
          type: string
      - name: note
        in: query
        schema:
          type: string
          maxLength: 255
      - name: legal-weight
        in: query
        schema:
          type: string
          enum:
          - AES
          - QES
          - SES
      - name: jurisdiction
        in: query
        schema:
          type: string
          enum:
          - eIDAS
          - ZertES
      - name: filename
        in: query
        schema:
          type: string
      - name: no-prepare
        in: query
        schema:
          type: boolean
      - name: position-x
        description: 'The x-coordinate of the signature from the bottom-left of the page.

          This is required when `additional-page=false`.

          '
        in: query
        schema:
          type: number
      - name: position-y
        description: 'The y-coordinate of the signature from the bottom-left of the page.

          This is required when `additional-page=false`.

          '
        in: query
        schema:
          type: number
      - name: height
        description: The height of the signature card. This is required when `additional-page=false`.
        in: query
        schema:
          type: number
      - name: page
        description: The page to place the signature on. This is required when `additional-page=false`.
        in: query
        schema:
          type: integer
          minimum: 1
      summary: Sign a file
      requestBody:
        description: The file to sign.
        required: true
        content:
          application/pdf: {}
      responses:
        200:
          description: The signed file content.
          content:
            application/pdf:
              schema:
                type: string
        400:
          $ref: '#/components/responses/bad_request'
        401:
          $ref: '#/components/responses/unauthorized'
      tags:
      - Signing
  /request/create:
    post:
      operationId: request_signature
      parameters:
      - $ref: '#/components/parameters/digital_twin'
      - $ref: '#/components/parameters/pdf-a'
      - name: send-email
        in: query
        schema:
          type: boolean
          default: false
        description: 'If `send-email=true`, the server will send the signature request to the signer''s email

          and also send reminder emails to get them to sign.

          '
      - name: name
        in: query
        schema:
          type: string
          description: 'The full name of the signer. You can omit this and send the name in parts using

            `first-name`, `middle-names`, and `last-name`.

            '
      - name: first-name
        in: query
        schema:
          type: string
      - name: middle-names
        in: query
        schema:
          type: string
      - name: last-name
        in: query
        schema:
          type: string
      - name: email
        in: query
        schema:
          type: string
          format: email
        description: The signer's email address.
        required: true
      - name: mobile-phone
        in: query
        schema:
          type: string
      - name: citizenship
        in: query
        schema:
          type: string
      - name: birthday
        in: query
        schema:
          type: string
      - name: gender
        in: query
        schema:
          type: string
      - name: domicile
        in: query
        schema:
          type: string
      - name: webhook-url
        in: query
        schema:
          type: string
          format: url
        description: 'URL-encoded callback URL that will be called with a `POST` request upon completion of the signature.

          See [Webhooks](https://developers.certifaction.com/en/guides/webhooks) for authentication and

          retry details.

          '
      - $ref: '#/components/parameters/accept_language'
      - $ref: '#/components/parameters/additional_page'
      - $ref: '#/components/parameters/qr_llx'
      - $ref: '#/components/parameters/qr_lly'
      - $ref: '#/components/parameters/qr_height'
      - $ref: '#/components/parameters/qr_page'
      - $ref: '#/components/parameters/encryption_key'
      - $ref: '#/components/parameters/password_encryption'
      - name: with-password
        in: query
        schema:
          type: boolean
        description: 'Protect the request using a password so that only the password bearer can sign.

          If enabled, a password will be generated. Send the password, together with the request URL, to the signer.

          '
      - name: hash
        in: query
        schema:
          type: string
      - name: message
        in: query
        schema:
          type: string
          maxLength: 255
      - name: transaction-id
        in: query
        schema:
          type: string
      - name: auto-sign
        in: query
        schema:
          type: boolean
          default: false
      - name: legal-weight
        in: query
        schema:
          $ref: '#/components/schemas/legal_weight'
      - name: jurisdiction
        in: query
        schema:
          type: string
          enum:
          - eIDAS
          - ZertES
      - name: filename
        in: query
        schema:
          type: string
      - name: no-prepare
        in: query
        schema:
          type: boolean
      - name: position-x
        description: 'The x-coordinate of the signature from the bottom-left of the page.

          This is required when `additional-page=false`.

          '
        in: query
        schema:
          type: number
      - name: position-y
        description: 'The y-coordinate of the signature from the bottom-left of the page.

          This is required when `additional-page=false`.

          '
        in: query
        schema:
          type: number
      - name: height
        description: The height of the signature card. This is required when `additional-page=false`.
        in: query
        schema:
          type: number
      - name: page
        description: The page to place the signature on. This is required when `additional-page=false`.
        in: query
        schema:
          type: integer
          minimum: 1
      summary: Request a signature
      requestBody:
        description: The files to sign
        required: true
        content:
          application/pdf: {}
          application/json:
            schema:
              properties:
                files:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                        format: url
                        description: 'DA URL of the documents to sign.

                          '
                      name:
                        type: string
                        description: 'Name of the document. This is used in the signature request email.

                          '
          application/x-www-form-urlencoded:
            schema:
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: url
                  description: 'DA URLs to the documents to sign. Previous signing links can be reused.

                    If a link to a password-protected request is provided, also pass the `password` parameter.

                    '
          multipart/form-data:
            schema:
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Upload PDF documents to sign.
            encoding:
              files:
                contentType: application/pdf
                style: form
      responses:
        200:
          description: The signature request was created.
          content:
            application/json:
              schema:
                properties:
                  request_url:
                    type: string
                    format: url
                  password:
                    type: string
        400:
          $ref: '#/components/responses/bad_request'
        401:
          $ref: '#/components/responses/unauthorized'
        409:
          description: The signer already has a pending signature request for the file.
      tags:
      - Signing
  /request/cancel:
    post:
      operationId: cancel_request
      summary: Cancel signature request for signer
      parameters:
      - name: email
        in: query
        schema:
          type: string
          format: email
        description: The email of the signer to cancel the request for.
        required: true
      - name: note
        in: query
        schema:
          type: string
        description: A message to the signer. You can use this to explain why you cancelled the request.
      requestBody:
        description: A file used in the signature request.
        required: true
        content:
          application/pdf: {}
      responses:
        204:
          description: The signature request to the given signer was cancelled.
        400:
          description: 'Check that:

            1. The `email` parameter was provided.

            2. The file provided has been prepared and can be read.

            '
        401:
          $ref: '#/components/responses/unauthorized'
        403:
          description: You cannot cancel the request at this time. It could be because the signer has signed already.
        404:
          description: Either the file provided or the signer email was not found.
      tags:
      - Signing
  /request/cancel/all:
    post:
      operationId: cancel_request_all
      summary: Cancel signature requests for file
      parameters:
      - name: note
        in: query
        schema:
          type: string
        description: A message to the signers. You can use this to explain why you cancelled the request.
      requestBody:
        description: A file used in the signature request.
        required: true
        content:
          application/pdf: {}
      responses:
        204:
          description: All pending signature requests for the file were cancelled.
        400:
          description: Check that the file provided has been prepared and can be read.
        401:
          $ref: '#/components/responses/unauthorized'
        403:
          description: You cannot cancel the requests at this time. It could be because a signer has signed already.
        404:
          description: The file provided was not found. Check that the file was processed and that you used it in a signature request.
      tags:
      - Signing
  /request/list:
    post:
      deprecated: true
      operationId: list_requests
      summary: List signature requests for file
      requestBody:
        description: A file (or a file URL) used in the signature request.
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                file:
                  type: string
                  format: url
                password:
                  type: string
              required:
              - file
          multipart/form-data:
            schema:
              properties:
                file:
                  type: string
                  format: binary
              required:
              - file
            encoding:
              file:
                contentType: application/pdf
      responses:
        200:
          description: List of signature requests for the file.
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                  legal_weight:
                    $ref: '#/components/schemas/legal_weight'
                  cancelled:
                    type: boolean
                  signed:
                    type: boolean
                  signer:
                    $ref: '#/components/schemas/user'
                  requester:
                    $ref: '#/components/schemas/user'
        400:
          description: Check that the file provided has been prepared and can be read.
        401:
          $ref: '#/components/responses/unauthorized'
        403:
          description: You cannot list signature requests for this file.
        404:
          description: The file provided was not found. Check that the file was processed and that you used it in a signature request.
      tags:
      - Signing
  /request/status:
    get:
      operationId: request_status
      summary: Show status of signature request
      parameters:
      - name: request_url
        in: query
        required: true
        schema:
          type: string
          format: url
        description: The URL of the signature request to check.
      - name: password
        in: query
        schema:
          type: string
        description: Password for password encrypted requests
      responses:
        200:
          description: Status of the signature request.
          content:
            application/json:
              schema:
                properties:
                  url:
                    type: string
                    format: url
                  id:
                    type: string
                  createdAt:
                    type: string
                    format: date-time
                  cancelled:
                    type: boolean
                  envelope_items:
                    type: object
                    properties:
                      legal_weight:
                        $ref: '#/components/schemas/legal_weight'
                      jurisdiction:
                        type: string
                      status:
                        $ref: '#/components/schemas/envelope_item_status'
                      signed_at:
                        type: string
                        format: date-time
                      file_url:
                        type: string
                        format: url
                      file_id:
                        type: string
                  signer:
                    type: object
                    properties:
                      email:
                        type: string
                        format: email
                  used_identification_at:
                    type: string
                    format: date-time
                  identification_method:
                    type: string
        400:
          description: Check that the file provided has been prepared and can be read.
        401:
          $ref: '#/components/responses/unauthorized'
        403:
          description: You cannot list signature requests for this file.
        404:
          description: The file provided was not found. Check that the file was processed and that you used it in a signature request.
      tags:
      - Signing
  /request/file/status:
    get:
      operationId: file_requests_status
      summary: Show status of signature requests of given file
      parameters:
      - name: file_url
        in: query
        required: true
        schema:
          type: string
          format: url
        description: The DA URL of the file to check.
      - name: password
        in: query
        schema:
          type: string
        description: Password for password encrypted document.
      responses:
        200:
          description: File status across all signature requests.
          content:
            application/json:
              schema:
                properties:
                  file_url:
                    type: string
                    format: url
                  file_id:
                    type: string
                  signature_requests:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        createdAt:
                          type: string
                          format: date-time
                        cancelled:
                          type: boolean
                        envelope_items:
                          type: object
                          properties:
                            legal_weight:
                              $ref: '#/components/schemas/legal_weight'
                            jurisdiction:
                              type: string
                            status:
                              $ref: '#/components/schemas/envelope_item_status'
                            signed_at:
                              type: string
                              format: date-time
                            file_url:
                              type: string
                              format: url
                            file_id:
                              type: string
                        signer:
                          type: object
                          properties:
                            email:
                              type: string
                              format: email
                        used_identification_at:
                          type: string
                          format: date-time
                        identification_method:
                          type: string
        400:
          description: Check that the file provided has been prepared and can be read.
        401:
          $ref: '#/components/responses/unauthorized'
        403:
          description: You cannot list signature requests for this file.
        404:
          description: The file provided was not found. Check that the file was processed and that you used it in a signature request.
      tags:
      - Signing
  /qes/check:
    post:
      summary: Check account QES status
      requestBody:
        content:
          application/json:
            schema:
              properties:
                jurisdiction:
                  type: string
              required:
              - jurisdiction
      responses:
        200:
          description: QES is enabled for your account.
        400:
          $ref: '#/components/responses/bad_request'
        401:
          $ref: '#/components/responses/unauthorized'
        404:
          description: QES is disabled for your account.
      tags:
      - Signing
components:
  schemas:
    legal_weight:
      type: string
      enum:
      - AES
      - QES
      - SES
    envelope_item_status:
      type: string
      enum:
      - unsigned
      - awaiting_upload
      - signed
      - cancelled
    prepare_scope:
      type: string
      enum:
      - sign
      - attachment
    organization:
      properties:
        id:
          type: string
        name:
          type: string
          maxLength: 80
          minLength: 2
        subscription_type:
          type: string
        quota:
          type: integer
      required:
      - id
    identity:
      properties:
        uid:
          type: string
        user_uid:
          type: string
        issuer:
          type: string
        status:
          type: string
        verification_url:
          type: string
        verification_id:
          type: string
        evidence_url:
          type: string
        proof:
          type: string
        name:
          type: string
        given_name:
          type: string
        family_name:
          type: string
        birthday:
          type: string
        signature_level:
          type: string
        signature_jurisdiction:
          type: string
      required:
      - uid
      - user_uid
      - issuer
      - status
      - verification_url
      - verification_id
      - evidence_url
      - proof
      - name
      - given_name
      - family_name
      - birthday
    user:
      properties:
        id:
          type: integer
        uid:
          type: string
        external_id:
          type: string
        email:
          type: string
        title:
          type: string
        name:
          type: string
        first_name:
          type: string
        middle_names:
          type: string
        last_name:
          type: string
        affiliation:
          type: string
        address:
          type: string
        postalcode:
          type: string
        location:
          type: string
        eth_address:
          type: string
        quota:
          type: integer
        disabled:
          type: boolean
        file_suffix:
          type: string
        permissions:
          type: array
          items:
            type: string
        subscription_type:
          type: string
        encrypt_claims:
          type: boolean
        verified_by:
          type: string
        features:
          type: object
        organizations:
          type: array
          items:
            $ref: '#/components/schemas/organization'
        identities:
          type: array
          items:
            $ref: '#/components/schemas/identity'
        theme:
          properties:
            name:
              type: string
          required:
          - name
        name_verified:
          type: boolean
    language:
      type: string
      enum:
      - de
      - en
      - fr
      - it
  parameters:
    accept_language:
      name: Accept-Language
      description: 'The language for text object placed added to the document. Pass `de` for German, `en` for English,

        `fr` for French, or `it` for Italian.

        '
      in: header
      schema:
        $ref: '#/components/schemas/language'
    signature_anchors:
      name: signature-anchors
      description: 'Place a signature card relative to plain text already present in the document. The value is a

        URL-encoded JSON object describing a single anchor; repeat the parameter to add more anchors

        (one object each). When provided, placeholder mode is enabled automatically: prepare the

        document with the anchors first, then sign each resulting placeholder via `/sign` or

        `/register` using its `id`.


        **Important**: on `/prepare`, anchors are only supported with `scope=sign` and a PAdES-enabled

        account. The anchor text must be extractable from the PDF (searchable text, not a scanned

        image).


        Fields (`id` and `anchor` are required; entries missing either are rejected with `400`):


        - `id`: unique placeholder name to sign against.

        - `anchor`: plain text to search for in the document.

        - `occurrence`: which match to use when the anchor repeats (1-based, defaults to 1).

        - `x`, `y`: offset from the matched text''s top-left (`x`+ right, `y`+ down); units `cm`/`mm`/`in`/`pt`.

        - `w`, `h`: card size (units `cm`/`mm`/`in`/`pt`). Only `w` derives the height from the aspect ratio; only `h` derives the width; without either, the base width is used.

        - `removeAnchor`: strip the matched anchor text from the PDF (defaults to `false`).


        JSON values must be percent-encoded in the query string, e.g. `{"id":"signer1","anchor":"signatures"}`

        becomes `%7B%22id%22%3A%22signer1%22%2C%22anchor%22%3A%22signatures%22%7D`.

        '
      in: query
      explode: true
      schema:
        type: array
        items:
          type: string
    pdf-a:
      name: pdf-a
      description: Enable PDF/A compatibility
      in: query
      schema:
        type: boolean
        default: false
    password_encryption:
      name: password-encryption
      description: The password encryption algorithm to use in encrypting the encryption key.
      in: query
      schema:
        type: string
        enum:
        - xor-b58
    prepare_scope:
      name: scope
      in: query
      schema:
        $ref: '#/components/schemas/prepare_scope'
      required: true
    qr_llx:
      name: qr-llx
      description: 'The x-coordinate of the Digital Twin QR code from the lower left corner of the document.

        This is required when `additional-page=false`.

        '
      in: query
      schema:
        type: number
    digital_twin:
      name: digital-twin
      description: Enable Digital Twin for the document.
      in: query
      schema:
        type: boolean
        default: false
    qr_height:
      name: qr-height
      description: The height of the Digital Twin QR code. This is required when `additional-page=false`.
      in: query
      schema:
        type: number
    encryption_key:
      name: encryption-key
      description: A hexadecimal string to encrypt the document with.
      in: query
      schema:
        type: string
    qr_page:
      name: qr-page
      description: The page to place the Digital Twin QR code on. This is required when `additional-page=false`.
      in: query
      schema:
        type: integer
    additional_page:
      name: additional-page
      description: Whether to place Digital Twin and signatures on an additional page or inline.
      in: query
      schema:
        type: boolean
        default: true
    qr_lly:
      name: qr-lly
      description: 'The y-coordinate of the Digital Twin QR code from the lower left corner of the document.

        This is required when `additional-page=false`.

        '
      in: query
      schema:
        type: number
  responses:
    unauthorized:
      description: You are not authorized to carry out the operation. Check that your API key is correct.
    bad_request:
      description: The request is not properly formed. For example, the content could not be read.
  securitySchemes:
    api_key:
      name: Authorization
      in: header
      type: apiKey