openapi: 3.0.1
info:
  title: UANATACA eSAW ONE-SHOT API DOCUMENTATION
  version: v1
  description: >
    eSAW One-Shot combines Uanataca single-use certificate issuance with
    eSignAnywhere (eSAW) for electronic signatures.


    **Testing:** Uanataca `https://api.sandbox.modernpki.com`, eSAW
    `https://demo.esignanywhere.net`

    **Production:** Uanataca `https://api.modernpki.com`, eSAW
    `https://saas.esignanywhere.net`


    Uanataca endpoints use client certificate authentication; eSAW endpoints use
    the `ApiToken` header.
security: []
tags:
  - name: Create
    description: Create a certificate request and obtain esaw_token for use in the envelope
  - name: Files
    description: Upload files for use in envelopes
  - name: Envelope
    description: Create and send envelopes
paths:
  /api/v1/esawoneshot:
    post:
      tags:
        - Create
      summary: Create certificate request
      description: >
        Creates a certificate request for the signer. The response includes
        `req_pk` and **esaw_token**.

        Use **esaw_token** as `requestToken` in the envelope's
        SignaturePluginData (GenericSigningPluginBit4idOneShot) when sending the
        envelope.
      operationId: createEsawOneshotRequest
      servers:
        - url: https://api.sandbox.modernpki.com
        - url: https://api.modernpki.com
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >-
                Request body must include rao, documents (optional), and request
                with profile, registration_authority, user data,
                id_document_type, etc.
            example:
              rao:
                username: '12345678'
                password: pwd123456
                pin: 18s876d4
              request:
                profile: PFnubeNC
                registration_authority: 1012
                communication_language: ES
                id_document_type: IDC
                id_document_country: ES
                serial_number: 12976587A
                given_name: John
                surname_1: Smith
                surname_2: Smith
                email: test@test.com
                mobile_phone_number: '+34666777888'
      responses:
        '200':
          description: Certificate request created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  req_pk:
                    type: integer
                    example: 113929
                  esaw_token:
                    type: string
                    description: >-
                      Token to pass as requestToken in the envelope's
                      SignaturePluginData
                    example: >-
                      ba4019803aaf2cd0a9755a688c8963901bfef4b942d7d2179e4e1e44c602
              example:
                status: ok
                req_pk: 113929
                esaw_token: ba4019803aaf2cd0a9755a688c8963901bfef4b942d7d2179e4e1e44c602
  /Api/v6/file/upload:
    post:
      tags:
        - Files
      summary: Upload file
      description: >
        Uploads a document to the eSAW platform. Call once per document to be
        signed.

        Returns a FileId to use in the envelope send request.
      operationId: uploadFile
      servers:
        - url: https://demo.esignanywhere.net
        - url: https://saas.esignanywhere.net
      security:
        - ApiToken: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                File:
                  type: string
                  format: binary
                  description: The file to upload
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  FileId:
                    type: string
                    format: uuid
                    example: aa4e3300-c254-4430-ac16-2f2d96090b3a
              example:
                FileId: aa4e3300-c254-4430-ac16-2f2d96090b3a
  /Api/v6/envelope/send:
    post:
      tags:
        - Envelope
      summary: Create and send envelope
      description: >
        Creates and sends an envelope. Include the FileId from the file upload
        and, in the Sign activity,

        set SignaturePluginData for GenericSigningPluginBit4idOneShot with
        requestToken set to the esaw_token from the create request.
      operationId: sendEnvelope
      servers:
        - url: https://demo.esignanywhere.net
        - url: https://saas.esignanywhere.net
      security:
        - ApiToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - Documents
                - Activities
              properties:
                Documents:
                  type: array
                  items:
                    type: object
                    properties:
                      FileId:
                        type: string
                      DocumentNumber:
                        type: integer
                Name:
                  type: string
                AddDocumentTimestamp:
                  type: boolean
                ShareWithTeam:
                  type: boolean
                LockFormFieldsOnFinish:
                  type: boolean
                Activities:
                  type: array
                  description: >-
                    Include a Sign activity with
                    SignaturePluginData.requestToken = esaw_token
                EmailConfiguration:
                  type: object
                ReminderConfiguration:
                  type: object
                ExpirationConfiguration:
                  type: object
      responses:
        '200':
          description: Envelope created and sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  EnvelopeId:
                    type: string
                    format: uuid
                    example: bc6752b7-f761-4b88-91f6-5e3112a716a3
              example:
                EnvelopeId: bc6752b7-f761-4b88-91f6-5e3112a716a3
components:
  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: ApiToken
      description: >-
        API key for eSignAnywhere (Files and Envelope endpoints). Generated in
        the eSAW user panel.
