openapi: 3.0.1
info:
  title: E-Signing Order Service (ESOS) API
  version: "1.0.11"
  description: |
    ESOS is the E-Signing API for composing and managing sign orders. 
    Please refer to the IN Groupe Developer site for details on how the E-Signing service works, and what the API can be used for.

    __This specification manages the following resources__
    * orders - a container for all instructions of a sign order
    * documents - documents that are to be signed
    * attachments - additional documents (these do not get signed)
    * signers - definition of users that can sign documents
    * exec-details - this defines the rules of engagement

    __Terms and expressions__
    * Sign order, or order - the equivalent of a contract that can contain any number of signers, documents, and instructions 
    * Merchant/customer - the client or customer using this API to manage orders
    * Order ID - a unique identifier for a sign order (defined by merchants)
    * Sign process - a context defining how signer interacts with the signing service (signer + document + execution detail = sign process)

    A merchant identifier (MID) and a secret code are required to integrate with ESOS API. 
    
    The identifier and the code can be received by using the [Contact us form](https://ingroupe.com/in-trust-services-support-contact-page/) to IN Groupe support.
    To receive a dedicated setup, you need to be an E-Signing customer. To become a customer, [Contact our sales department](https://ingroupe.com/product/e-signing/)

  contact:
    url: https://doc.ingroupe.com/developer/e-signing-web-services
  
paths:

###############################################################
#
# Sign order messages
#
  /{mid}/orders:
    post:
      security:
        - esosAuth: [post]
      tags: 
        - Orders
      summary: Create a new sign order
      description: |
        Add a new sign order for signing a single document or multiple documents.
      operationId: post-orders
      parameters:
        - name: mid
          in: path
          description: >
            ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
      requestBody:
        description: Details to create a new sign order.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
        required: true
      responses:
        '200':
          description: Order is created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to create order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'
    get:
      security:
        - esosAuth: [get]
      tags: 
        - Orders
      summary: Search for existing sign orders
      description: >
        Get sign orders with optional filter criteria.
      operationId: get-orders
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: status
          in: query
          description: Status to filter the orders.  Takes multiple values separated by comma.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/OrderStatusTypesEnum'
        - name: signerReference
          in: query
          description: Signer reference to filter the orders.
          required: false
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        - name: size
          in: query
          description: Maximum number of orders to return in the response.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: page
          in: query
          description: Page to return when the number of orders exceeds page size.
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
      responses:
        '200':
          description: Sign orders are retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersSearchResponse'
        '400':
          description: Failed to retrieve sign orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'
                
  /{mid}/orders/{orderid}:
    get:
      security:
        - esosAuth: [get]
      tags: 
        - Orders
      summary: Get sign order details
      description: |
        Get order details of an existing sign order.
      operationId: get-order
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      responses:
        '200':
          description: Sign order details are retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderGetResponse'
        '400':
          description: Failed to retrieve sign order details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'
    put:
      security:
        - esosAuth: [put]
      tags: 
        - Orders
      summary: Update sign order
      description: >
        Update an existing sign order.  The following details can be updated: status, deadline, description, display info.
      operationId: update-order
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      requestBody:
        description: Details to update in the sign order.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdate'
        required: true
      responses:
        '202':
          description: The sign order is updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to update the sign order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

###############################################################
#
# Document messages
#
  /{mid}/documents/{orderid}:
    post:
      security:
        - esosAuth: [post]
      tags: 
        - Documents
      summary: Add document to a sign order
      description: |
        Add document to an existing sign order.
        A sign order must contain at least one document.  Each document must be included as Base64 encoded bytes.
        
        To enable PDF form support, provide form instruction text value in "b64rule" field together with base64 of PDF form in "b64data" field
        
        The PreApproved element is used to support large-sized documents that the signer is not required to accept manually. If set to false, the signer must manually accept the provided document.
        
        Note: Web form do not support the PreApproved flag, as web form contain fields that need to be filled out by the signer.

        __Supported document types:__
          * PDF and PDF forms
          * Plain text documents
          * XML with accompanying XSL
          * Web form
          * PDF forms with web form
      externalDocs:
        description: Visit following page for more details.
        url: https://doc.ingroupe.com/developer/insert-sign-order#documents
      operationId: post-document
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      requestBody:
        description: Document details to add to the sign order.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentAdd'
        required: true
      responses:
        '200':
          description: Document(s) is/are added to the sign order successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to add document(s) to the sign order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'
    get:
      security:
        - esosAuth: [get]
      tags: 
        - Documents
      summary: Get document(s) from an existing sign order
      description: |
        Get document(s) details from an existing sign order.
      operationId: get-document
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        - name: signerReference
          in: query
          description: Signer Reference to filter the documents that are assigned to the signer.
          required: false
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        - name: signerIdScope
          in: query
          description: Signer ID Scope to indicate whether to include the signer's personal identifier in response
          required: false
          schema:
            $ref: '#/components/schemas/SignerIdScopesEnum'
        - name: objectId
          in: query
          description: Document reference to filter the documents.
          required: false
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      responses:
        '200':
          description: Document(s) details are retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentsSearchResponse'
        '400':
          description: Failed to retrieve document(s) details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'
    delete:
      security:
        - esosAuth: [delete]
      tags: 
        - Documents
      summary: Delete document data in a sign order
      description: >
        Delete document data in an existing sign order.
        The data includes documents, SDOs, PAdES documents and signatures.
        
        Note: To delete document data, the sign order status should be one of the following: completed, expired, cancelled, failed.
      operationId: delete-document
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            type: string
        - name: objectId
          in: query
          description: Document reference of the document to delete.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      responses:
        '200':
          description: Document data is deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to delete document data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

###############################################################
#
# Attachment messages
#
  /{mid}/attachments/{orderid}:
    post:
      security:
        - esosAuth: [post]
      tags: 
        - Attachments
      summary: Add attachment to a sign order
      description:  |
        Add a single or multiple attachments to an existing sign order. Each attachment must be included as Base64 encoded bytes.
        
        Note: Attachments must be PDF documents.  Attachments are displayed to the signer in the signing UI, 
        but will not be signed by the signer.  The attachments will not be part of the SDO or PAdES document.

        __Supported attachment type:__
          * PDF
      externalDocs:
        description: Visit following page for more details.
        url: https://doc.ingroupe.com/developer/insert-sign-order#attachments
      operationId: post-attachment
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      requestBody:
        description: Attachment details to add to the sign order.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachmentAdd'
        required: true
      responses:
        '200':
          description: Attachment is added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to add attachment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'
    get:
      security:
        - esosAuth: [get]
      tags: 
        - Attachments
      summary: Get attachments from a sign order
      description: Get attachment details from an existing sign order.
      operationId: get-attachment
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      responses:
        '200':
          description: Attachment details are retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentsSearchResponse'
        '400':
          description: Failed to retrieve attachment details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'
    delete:
      security:
        - esosAuth: [delete]
      tags: 
        - Attachments
      summary: Delete attachment from sign order
      description: Delete attachment from an existing sign order.
      operationId: delete-attachment
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        - name: attachmentReference
          in: query
          description: Attachment reference to uniquely identify the attachment.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      responses:
        '200':
          description: Attachment is deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to delete attachment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

###############################################################
#
# Signer messages
#
  /{mid}/signers/{orderid}:
    post:
      security:
        - esosAuth: [post]
      tags: 
        - Signers
      summary: Add signer to sign order
      description: |
        Add signer to an existing sign order.
        
        Two types of signers are supported:
        * A physical person (an end user)
        * Or an organisation (the customer)

        The end user signer can be presented with either a specific eID or a list of all available eIDs.        
        The organisation signature is done automatically in E-Signing using the customer's organisational certificate of choice.
        
        Note:
        Signers can only be added to an existing sign order if:
        * the sign order status is one of the following: *INITIAL, READY, INPROGRESS*

        A signer can be defined with the following attributes:
        * name
        * eIDs for signing
        * notification methods
        
        eIDs can be native eIDs or authentication based eIDs.  Refer request body examples below for usage.
      externalDocs:
        description: Visit following page for more details.
        url: https://doc.ingroupe.com/developer/insert-sign-order#signers
      operationId: add-signer
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      requestBody:
        description: Signer details to add to the sign order.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignerAdd'
            examples:
              sign-method-xml-notification-example:
                summary: Add signer with native signing and xml notification
                value:
                  requestId: 369cf0e7-b175-4345-a789-b666909870c4
                  signers:
                    - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
                      signerName: Signer name
                      signerEids:
                        signerIdScope: BASIC
                        signMethods:
                          - name: NO_BANKID
                            certPolicy: PERSONALQUALIFIED
                            ids:
                              - name: SSN
                                value: 20028713506
                          - name: SE_BANKID
                      notifications:
                        - objectId: 659a79e2-7bf1-44cd-9233-dd8e48c82ef4
                          method: XML
                          endpoint: https://xml.customer.com/sign/xml/notification
                          triggers:
                            - STEPREADY
                            - STEPCOMPLETE
                            - ORDERCOMPLETE
              sign-method-with-all-eid-example:
                summary: Add signer with native signing using all eIDs configured for the merchant
                value:
                  requestId: 369cf0e7-b175-4345-a789-b666909870c4
                  signers:
                    - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
                      signerName: Signer name
                      signerEids:
                        signerIdScope: BASIC
                        signMethods: []
                      notifications:
                        - objectId: 659a79e2-7bf1-44cd-9233-dd8e48c82ef4
                          method: XML
                          endpoint: https://xml.customer.com/sign/xml/notification
                          triggers:
                            - STEPREADY
                            - STEPCOMPLETE
                            - ORDERCOMPLETE
              sign-method-email-sms-notification-example:
                summary: Add signer with native signing and email, sms notificaitons
                value:
                  requestId: 850cf0e7-b175-4345-a789-b666909870c4
                  signers:
                    - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
                      signerName: Signer name
                      signerEids:
                        signerIdScope: BASIC
                        signMethods:
                          - name: NO_BANKID
                            certPolicy: PERSONALQUALIFIED
                            ids:
                              - name: SSN
                                value: 20028713506
                          - name: SE_BANKID
                      notifications:
                        - objectId: 398a79e2-7bf1-44cd-9233-dd8e48c82ef4
                          method: EMAIL
                          endpoint: signer@customer.com
                          triggers:
                            - STEPREADY
                            - STEPCOMPLETE
                            - ORDERCOMPLETE
                        - objectId: 398a79e2-7bf1-44cd-9233-dd8e48c82ef4
                          method: SMS
                          endpoint: 4710246514
                          triggers:
                            - STEPREADY
                            - STEPCOMPLETE
                            - ORDERCOMPLETE
              auth-method-email-notification-example:
                summary: Add signer with authentication based signing and email notification
                value:
                  requestId: 3c0cf0e7-b175-4345-a789-b666909870c4
                  signers:
                    - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
                      signerName: Signer name
                      signerEids:
                        signerIdScope: BASIC
                        authMethods:
                          - name: NO_BANKID
                            ids:
                              - name: SSN
                                value: 20028713506
                          - name: SE_BANKID
                          - name: FI_TUPAS
                      notifications:
                        - objectId: 398a79e2-7bf1-44cd-9233-dd8e48c82ef4
                          method: EMAIL
                          endpoint: signer@customer.com
                          triggers:
                            - STEPREADY
                            - STEPCOMPLETE
                            - ORDERCOMPLETE
              auth-method-with-all-eid-example:
                summary: Add signer with authentication based signing using all eIDs configured for the merchant
                value:
                  requestId: 2d4cf0e7-b175-4345-a789-b666909870c4
                  signers:
                    - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
                      signerName: Signer name
                      signerEids:
                        signerIdScope: BASIC
                        authMethods: []
                      notifications:
                        - objectId: 398a79e2-7bf1-44cd-9233-dd8e48c82ef4
                          method: EMAIL
                          endpoint: signer@customer.com
                          triggers:
                            - STEPREADY
                            - STEPCOMPLETE
                            - ORDERCOMPLETE
              customer-sign-example:
                summary: Add customer as the signer using customer's organisational certificate of choice.
                value:
                  requestId: 8b0cf0e7-b175-4345-a789-b666909870c4
                  signers:
                    - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
                      signerName: Merchant X
                      merchantEid: NO_BANKID
                      notifications:
                        - objectId: 398a79e2-7bf1-44cd-9233-dd8e48c82ef4
                          method: EMAIL
                          endpoint: merchant@customer.com
                          triggers:
                            - STEPREADY
                            - STEPCOMPLETE
                            - ORDERCOMPLETE
        required: true
      responses:
        '200':
          description: Signer is added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to add signer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'
    get:
      security:
        - esosAuth: [get]
      tags: 
        - Signers
      summary: Get signer(s) from a sign oder
      description: |
        Get signer(s') details from an existing sign order.
        
        Note:
        Signer details include:
        * sign process status
        * sign process URL (if any of the documents assigned to the signer are still unsigned)
        * references to signer document(s), attachment(s), contexts
      operationId: get-signer
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        - name: objectId
          in: query
          description: Signer reference to filter for a specific signer.
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      responses:
        '200':
          description: Signer details are retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignersGetResponse'
        '400':
          description: Failed to retrieve signer details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

    put:
      security:
        - esosAuth: [put]
      tags: 
        - Signers
      summary: Update signer in a sign order
      description: |
        Update signer in an existing sign order.
        
        Following attributes of the signer can be updated:
        * Signer name
        * Signer ID

        Note:
        * A signer cannot add new eIDs.
        * A signer can only be updated if:
          1. The order status is one of the following: *INITIAL, READY, INPROGRESS*
          2. None of the documents assigned to the signer have been signed, or cancelled.
      operationId: update-signer
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client. This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      requestBody:
        description: Signer details to update in the sign order.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignerAdd'
        required: true
      responses:
        '200':
          description: Signer is updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to update signer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

    delete:
      security:
        - esosAuth: [delete]
      tags: 
        - Signers
      summary: Delete signer from a sign order
      description: >
        Delete an existing signer from an existing sign order.

        Note:
        A signer can only be deleted if:
        * The sign order status is one of the following: *INITIAL, READY, INPROGRESS*
        * None of the documents assigned to the signer have been signed, or cancelled.
      operationId: delete-signer
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        - name: objectId
          in: query
          description: Signer reference of the signer to delete.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      responses:
        '200':
          description: Signer is deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to delete the signer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

###############################################################
#
# Order execution messages
#
  /{mid}/exec-details/{orderid}:
    post:
      security:
        - esosAuth: [post]
      tags: 
        - Exec-details
      summary: Add execution details for a sign order
      description: |
        Add execution details to an existing sign order by defining the association between 
        signers, documents and attachments in the sign order through sign processes.
        
        Execution details determine sign order flow constraints such as:
        * Which documents get assigned to which signers in the sign order
        * The sequence in which signers can append their signatures
        * Required conditions for the sign order to be complete (such as minimum number of signatures)
        * Deadlines and reminders
        
        Execution details contain the following:
        * organisations: defines customer's organisation details.
        * webContexts: defines a set of URLs that tells E-Signing where a signer is supposed to perform the sign process 
        and where a signer shall be routed when he/she has signed or if an error occurs or if he/she cancels the signing.
        * steps: outlines the steps, connecting the documents with the signers and the organisations, requied to complete the sign order
        
        webContexts URLs include the following:
        * signUrlBase: Sign URL is a pointer to a sign process involving a signer and a document. The customer chooses 
        how the sign experience for the end user shall be by either presenting the sign proccess embedded on its own sign page or redirects 
        the signer to a standalone IN Groupe page. The sign URL can also be distributed to signers via notification channels. 
        If a signer is registered with the e-mail channel and the trigger OnSignProcessReady is set, the signer will receive an e-mail 
        holding the sign URL when it is his/her turn to sign. The signURLBase is the sign URL prefix. When a sign order is inserted into E-Signing 
        the WebContext is registered for later use. When a customer asks for the sign URL, E-Signing generates a unique reference 
        and appends it to the end of the signURLBase. Final Sign URL = signURLBase + <generated reference>. 
        The signURLBase value might be a URL (https://www.example.com/sign?sref=), a relative path (/sign?sref=) or empty.
        If this value is an empty string, the reference alone is returned.
        * statusUrlBase: This defines the location the signer is sent to if an error occurs or if the signer cancels/rejects the signing process. 
        The sign process is performed inside an iframe.  If an error occurs or if the user cancels/rejects the signing process, 
        the client in the sign page must break out of the iframe and redirect the user to this URL. An error code or cancel code is appended 
        to the statusUrlBase.  In addition, the sref parameter (with the unique reference that is appended to signUrlBase) can be appended to this URL.
        * styleUrl: ​This points to a customer specific css-file used to tailor the user interface.
        * exitUrl: This defines the URL where the signer is redirected upon sign completion. The sign process is performed inside an iframe. 
        Upon sign completion, the client in the sign page must break out of the iframe and redirect the user to this URL. 
        The sref parameter (with the unique reference that is appended to signUrlBase) can be appended to this URL.
      operationId: add-execdetails
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      requestBody:
        description: Execution details to add to the sign order.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecDetailsAdd'
        required: true
      responses:
        '200':
          description: Execution details are added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to add execution details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

    get:
      security:
        - esosAuth: [ get ]
      tags:
        - Exec-details
      summary: Get execution details from a sign order
      description: |
        Retrieve execution details from an existing sign order
      operationId: get-exec-details
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      responses:
        '200':
          description: Execution details are retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecDetailsSearchResponse'
        '400':
          description: Failed to retrieve execution details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

    delete:
      security:
        - esosAuth: [delete]
      tags: 
        - Exec-details
      summary: Delete execution details from sign order
      description: >
        Delete execution details from an existing sign order.
        
        Note:
        Execution details can be deleted only when:
        * The sign order status is one of the following: *INITIAL, READY, INPROGRESS* 
        * The sign process status is NOT any of the following: *COMPLETED, EXPIRED, CANCELLED, FAILED*
      operationId: delete-exec-details
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            type: string
        - name: signProcessReference
          in: query
          description: Sign process reference in the execution details to filter.
          required: false
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        - name: stepReference
          in: query
          description: Step reference in the execution details to filter.
          required: false
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      responses:
        '200':
          description: Execution details are deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to delete execution details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

###############################################################
#
# Order post processing messages
#
  /{mid}/post-processes/{orderid}:
    post:
      security:
        - esosAuth: [post]
      tags: 
        - Post-processes
      summary: Add instructions to sign order to perform after the sign order is complete
      description: |
        Add instructions to an existing sign order to perform once the sign order is complete.
        
        These instructions define additional logic that needs to be performed after document signing is complete.
        The instructions can include:
        * Verification of signature rights for signers and organisations
        * Archival of the signed documents and signatures
        * Insertion of custom properties to the sign order
      operationId: add-processes
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      requestBody:
        description: Post processing instructions to add to the sign order.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostProcessAdd'
        required: true
      responses:
        '200':
          description: Post processing instructions are added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to add post processing instructions to the sign order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

    get:
      security:
        - esosAuth: [ get ]
      tags:
        - Post-processes
      summary: Get post processing instructions from sign order
      description: Retrieve post processing instrcutions from an existing sign order
      operationId: get-processes
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      responses:
        '200':
          description: Retrieved post processing instructions successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostProcessingSearchResponse'
        '400':
          description: Failed to retrieve post processing instructions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

###############################################################
#
# SDO messages
#
  /{mid}/sdos/{orderid}:
    get:
      security:
        - esosAuth: [get]
      tags: 
        - Sign results
      summary: Get SDO (Signed Document Object) for a sign order.
      description: |
        Retrieve SDO for an existing sign order that is in COMPLETED status.
      operationId: get-sdo
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      responses:
        '200':
          description: SDO is retieved from sign order successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SDOResponse'
        '400':
          description: Failed to retrieve SDO from sign order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'
                
  /{mid}/sdos:
    post:
      security:
        - esosAuth: [post]
      tags: 
        - Sign results
      summary: Merge two SDOs
      description: |
        Merge two SDOs provided both SDOs contain same document.
      operationId: merge-sdos
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
      requestBody:
        description: SDOs to merge.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SDOMergeDef'
        required: true
      responses:
        '200':
          description: SDOs merged successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SDOMergeResponse'
        '400':
          description: Failed to merge SDOs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

  /{mid}/sdo-details:
    post:
      security:
        - esosAuth: [ post ]
      tags:
        - Sign results
      summary: Get SDO Details
      description: |
        Retrieve detailed information about the content of the input SDO.
      operationId: sdo-details
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
      requestBody:
        description: SDO to get the detailed information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SDODetailsDef'
        required: true
      responses:
        '200':
          description: SDO details are retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamsSearchResponse'
        '400':
          description: Failed to retrieve SDO details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

  /{mid}/validate-sdo:
    post:
      security:
        - esosAuth: [ post ]
      tags:
        - Sign results
      summary: Validate SDO
      description: |
        Valudate the given SDO and retrieve details from it.
      operationId: validate-sdo
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
      requestBody:
        description: SDO to validate and to get details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateSDODetailsDef'
        required: true
      responses:
        '200':
          description: Retrieved details from SDO succesfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to retrieve details from SDO.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

###############################################################
#
# PAdES messages
#
  /{mid}/pades:
    post:
      security:
        - esosAuth: [post]
      tags: 
        - Sign results
      summary: Generate PAdES from SDO
      description: |
        Generate a signed PDF or PAdES (PDF Advanced Electronic Signatures) for the signatures in the given SDO
      operationId: generate-pades
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
      requestBody:
        description: SDO details to generate PAdES.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PadesGenerateDef'
        required: true
      responses:
        '200':
          description: PAdES is generated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PadesGenerateResponse'
        '400':
          description: Failed to generate PAdES.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'
                
  /{mid}/pades/{orderid}:
    get:
      security:
        - esosAuth: [get]
      tags: 
        - Sign results
      summary: Get PAdES from sign order
      description: |
        Generate a signed PDF or PAdES (PDF Advanced Electronic Signatures) for the signatures in an SDO of an existing sign order
      operationId: get-pades
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        - name: documentReference
          in: query
          description: Document reference to filter SDO in a sign order
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        - name: signerReference
          in: query
          description: Signer reference to filter SDO in a sign order
          required: false
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        - name: padesReference
          in: query
          description: PAdES document reference to filter SDO in a sign order
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        - name: languageCode
          in: query
          description: Language to use for the signature page in the signed PDF
          required: false
          schema:
            type: string
            pattern: '^([a-zA-Z]{2})([-_][a-zA-Z]{0,2})?$'
        - name: returnPII
          in: query
          description: Flag to indicate whether to include the signer PII in PAdES
          required: false
          schema:
            type: boolean
        - name: includeCustomProperties
          in: query
          description: Flag to indicate whether to include custom properties in PAdES
          required: false
          schema:
            type: boolean
        - name: timeZone
          in: query
          description: Timezone to use for the signature page in the signed PDF
          required: false
          schema:
            $ref: '#/components/schemas/EsosTypePadesTimeZoneDef'
      responses:
        '200':
          description: PAdES is generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PadesGenerateResponse'
        '400':
          description: Failed to generate PAdES
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

  /{mid}/signaturearchive/{orderid}:
    get:
      security:
        - esosAuth: [ get ]
      tags:
        - Sign results
      summary: Get Signature Archive for a sign order
      description: |
        Retrieve ASiC (PAdES, SDO future release) for an existing sign order that is in COMPLETED status.
        Document Reference will be available for orders except ASiC output formats.
      operationId: get-asic
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      responses:
        '200':
          description: Signature Archive is retrieved from sign order successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureArchiveResponse'
        '400':
          description: Failed to retrieve Signature Archive from sign order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

###############################################################
#
# Signature messages
#
  /{mid}/signatures:
    post:
      security:
        - esosAuth: [post]
      tags: 
        - Sign imports
      summary: Add signature to sign order
      description: |
        Add signature to an existing sign order 
      operationId: add-signature
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
      requestBody:
        description: Signature details to add to an existing sign order
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignatureAdd'
        required: true
      responses:
        '200':
          description: Signature is successfully added to the sign order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to add signature to the sign order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

  /{mid}/merchant-sign:
    post:
      security:
        - esosAuth: [post]
      tags: 
        - Sign imports
      summary: Add merchant signature to document
      description: |
        Add merchant signature to the document provided using the merchantsign supported IDPs 
      operationId: post-merchantSignDocument
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
      requestBody:
        description: Document and IDP details to add merchant signature
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantSignAdd'
        required: true
      responses:
        '200':
          description: Merchant signature is successfully added to the document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosPassResponse'
        '400':
          description: Failed to add merchant signature to the document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

###############################################################
#
# Notification messages
#
  /{mid}/notifications/{orderid}:
    get:
      security:
        - esosAuth: [get]
      tags: 
        - Notifications
      summary: Get notification details
      description: |
        Retrieve notification details that are sent out for an existing sign order.
        
        Note: The notification's objectId is pointing to MessageId 
      operationId: get-notification
      parameters:
        - name: mid
          in: path
          description: ID to uniquely identify a merchant/client.  This ID is issued to the client on registration.
          required: true
          schema:
            type: integer
        - name: orderid
          in: path
          description: ID to uniquely identify the existing sign order.
          required: true
          schema:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
      responses:
        '200':
          description: Notification details are retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationsGetResponse'
        '400':
          description: Failed to retrieve notification details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsosFailResponse'

###############################################################
#
# Stream messages
#
  /{mid}/stream/{orderid}:
      get:
        security:
          - esosAuth: [ get ]
        tags:
          - Uploads
        summary: Get large data packets
        description: |
          A stream allows to get the data packets of attachment or document
        operationId: get-stream
        parameters:
          - name: mid
            in: path
            description: See /{mid}/orders POST parameter description.
            required: true
            schema:
              type: integer
          - name: orderid
            in: path
            description: See /{mid}/orders GET parameter description.
            required: true
            schema:
              $ref: '#/components/schemas/EsosTypeObjectRefDef'
          - name: type
            in: query
            description: Streams are listed below
            required: true
            schema:
              $ref: '#/components/schemas/StreamTypesEnum'
          - name: objectid
            in: query
            description: documentReference or attachmentReference object id
            required: true
            schema:
              $ref: '#/components/schemas/EsosTypeObjectRefDef'
        responses:
          '200':
            description: Request processed successfully
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/StreamsSearchResponse'
          '400':
            description: Request failed (responseType will always be FAIL).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/EsosFailResponse'

###############################################################
#
# Component schemas
#
components:
  schemas:
      
    OrderCreate:
      type: object
      required:
        [requestId, objectId, outputFormat, orderDeadline]
      properties:
        requestId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        orderDescription:
          $ref: '#/components/schemas/EsosTypeOrderDescriptionDef'
        orderInfoDisplay:
          $ref: '#/components/schemas/OrderInfoDisplayEnum'
        orderDeadline:
          type: string
          format: date-time
          description: Order deadline by which all signers in the sign order should complete signing. 
        outputFormat:
          $ref: '#/components/schemas/OutputFormatEnum'
        useOneTimeUrls:
          type: boolean
          description: Indicates whether to generate new URL for signing each time a signing URL is requested. 
        orderMetadata:
          type: array
          items:
            $ref: '#/components/schemas/NameValueDef'
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/NotificationDef'
      example:
        requestId: 2b0cf0e7-b175-4345-a789-b666909870c4
        objectId: 656a79e2-7bf1-44cd-9233-dd8e48c82ef4
        orderDescription: "New sign order"
        orderInfoDisplay: NAMESTATUSTIME
        orderDeadline: 2024-06-10T10:09:19.525Z
        outputFormat: SDO
        useOneTimeUrls: false
        orderMetadata:
          - name:  metaname-1,
            value: metavalue-1
        notifications: 
          - objectId: 30ccf0e7-b175-4345-a789-b666909870c4
            method: XML
            endpoint: "https://notifications.customer.com/signorder/notification"
            triggers:
              - ORDERCOMPLETE
              - ORDERFAIL
            
    OrderUpdate:
      type: object
      required:
        [requestId, objectId]
      properties:
        requestId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        orderDescription:
          type: string
        orderInfoDisplay:
          $ref: '#/components/schemas/OrderInfoDisplayEnum'
        orderDeadline:
          type: string
          format: date-time
          nullable: true
          description: Order deadline by which all signers in the sign order should complete signing.
        useOneTimeUrls:
          type: boolean
          description: Indicates whether to generate new URL for signing each time a signing URL is requested.
        orderStatus:
          $ref: '#/components/schemas/OrderStatusTypesEnum'
      example:
        requestId: 2b0cf0e7-b175-4345-a789-b666909870c4
        objectId: 656a79e2-7bf1-44cd-9233-dd8e48c82ef4
        orderDescription: "New sign order"
        orderInfoDisplay: NAMESTATUSTIME
        orderDeadline: 2024-06-10T10:09:19.525Z
        useOneTimeUrls: false
        orderStatus: READY 
            
    OrdersSearchResult:
      type: object
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        orderStatus:
          $ref: '#/components/schemas/OrderStatusTypesEnum'
        orderTime:
          type: string
          format: date-time
        orderDeadline:
          type: string
          format: date-time
          nullable: true
          description: Order deadline by which all signers in the sign order should complete signing.
      example:
        objectId: 656a79e2-7bf1-44cd-9233-dd8e48c82ef4
        orderStatus: READY 
        orderTime: 2024-03-18T10:09:19.525Z
        orderDeadline: 2024-06-10T10:09:19.525Z
          
    OrdersSearchResponse:
      type: object
      properties:
        responseId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        results:
          type: array
          items:
            $ref: '#/components/schemas/OrdersSearchResult'
      example:
        responseId: ab1cf0e7-b175-4345-a789-b666909639a2
        results:
          - objectId: 656a79e2-7bf1-44cd-9233-dd8e48c82ef4
            orderStatus: READY 
            orderTime: 2024-03-18T10:09:19.525Z
            orderDeadline: 2024-06-10T10:09:19.525Z

    OrderGetResult:
      type: object
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        orderDescription:
          $ref: '#/components/schemas/EsosTypeDescriptionDef'
        orderStatus:
          $ref: '#/components/schemas/OrderStatusTypesEnum'
        orderDeadline:
          type: string
          format: date-time
          nullable: true
          description: Order deadline by which all signers in the sign order should complete signing.
        outputFormat:
          $ref: '#/components/schemas/OutputFormatEnum'
        useOneTimeUrls:
          type: boolean
          description: Indicates whether to generate new URL for signing each time a signing URL is requested.
        links:
          type: array
          items:
            $ref: '#/components/schemas/LinkDef'
          description: Links to other endpoints in the API to manage the sign order, such as to update or cancel the sign order.
          
    OrderGetResponse:
      type: object
      properties:
        responseId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        results:
          type: array
          items:
            $ref: '#/components/schemas/OrderGetResult'
      example:
        responseId: cb1cf0e7-b175-4345-a789-b666909639a2
        results:
          - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
            orderDescription: "New sign order"
            orderStatus: READY 
            orderDeadline: 2024-06-10T10:09:19.525Z
            outputFormat: SDO
            useOneTimeUrls: false
            links:
              - rel: order-update
                href: /esos/v1/<merchantid>/orders/566a79e2-7bf1-44cd-9233-dd8e48c82ef4
                type: PUT
          
    PostProcessingSearchResponse:
      type: object
      properties:
        responseId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        results:
          type: array
          items:
            $ref: '#/components/schemas/PostProcessingSearchResult'

    PostProcessingSearchResult:
      type: object
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        orderStates:
          $ref: '#/components/schemas/OrderStatesDef'
        signAndProcuration:
          type: array
          items:
            $ref: '#/components/schemas/SignAndProcurationDef'
        orderArchives:
          type: array
          items:
            $ref: '#/components/schemas/OrderArchiveDef'
        customProperties:
          type: array
          items:
            $ref: '#/components/schemas/CustomPropertiesDef'
          
    DocumentAdd:
      type: object
      required:
        [requestId]
      properties:
        requestId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/DocumentAddDef'
      example:
        requestId: 2b0cf0e7-b175-4345-a789-b666909870c4
        documents:
          - objectId: a6aa79e2-7bf1-44cd-9233-dd8e48c82ef4
            documentTitle: Document title
            documentDescription: Document description
            requireAuthentication: false
            preApproved: false
            minSignerCount: 1
            content:
              contentType: TEXT_PLAIN
              b64data: VGhpcyBpcyBhIHNhbXBsZSBkb2N1bWVudC4NCg==
            
    DocumentDelete:
      type: object
      required:
        [requestId, objectId]
      properties:
        requestId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        orderId:
          type: string
          description: ID to uniquely identify the existing sign order.
        documentDescription:
          $ref: '#/components/schemas/EsosTypeDescriptionDef'
          
    AttachmentAdd:
      type: object
      required:
        [requestId]
      properties:
        requestId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentAddDef'
      example:
        requestId: 2b0cf0e7-b175-4345-a789-b666909870c4
        attachments:
          - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
            attachmentTitle: Attachment title
            attachmentDescription: Attachment description
            content:
              contentType: APPLICATION_PDF
              b64data: base64-encoded-document-bytes
            
    DocumentAddDef:
      type: object
      required:
        [objectId, documentTitle, documentDescription]
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        documentTitle:
          $ref: '#/components/schemas/EsosTypeTitleDef'
        documentDescription:
          $ref: '#/components/schemas/EsosTypeDescriptionDef'
        requireAuthentication:
          type: boolean
          description: >
            Indicates whether the signers assigned to the document are forced to identify themselves before signing the document.
            If this value is set to true, then the signers who will be added to the document MUST have the signerId defined 
            while adding them to the sign order. 
        minSignerCount:
          type: integer
          description: >
            Indicates the number of end user signers required to sign the document. When this number is reached the document status is set to complete.
        preApproved:
          type: boolean
          description: >
            Indicates if the document is to be considered as PreApproved.
        content:
          $ref: '#/components/schemas/DocumentContentDef'
          
    DocumentContentDef:
      type: object
      required:
        [contentType, b64data]
      properties:
        contentType:
          $ref: '#/components/schemas/DocumentTypesEnum'
        b64data:
          type: string
          format: byte
          description: The base64 encoded document bytes.
        b64rule:
          type: string
          format: byte
          description: The rule value of base64 encoded bytes is supported only for PDFForm and XML document type.
          
    AttachmentAddDef:
      type: object
      required:
        [requestId, objectId, attachmentTitle]
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        attachmentTitle:
          $ref: '#/components/schemas/EsosTypeTitleDef'
        attachmentDescription:
          $ref: '#/components/schemas/EsosTypeDescriptionDef'
        attachmentType:
          type: string
          description: Attachment type
        content:
          $ref: '#/components/schemas/AttachmentContentDef'
          
    AttachmentContentDef:
      type: object
      required:
        [contentType, b64data]
      properties:
        contentType:
          $ref: '#/components/schemas/DocumentTypesEnum'
        b64data:
          type: string
          format: byte
          description: The base64 encoded document bytes.
          
    SignerAdd:
      type: object
      required:
        [requestId]
      properties:
        requestId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signers:
          type: array
          description: Array of signers
          items:
            $ref: '#/components/schemas/SignerAddDef'
      example:
        requestId: 2b0cf0e7-b175-4345-a789-b666909870c4
        signers:
          - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
            signerName: Signer name
            signerEids:
              signerIdScope: BASIC
              authMethods:
                - name: NO_BANKID
                  ids:
                    - name: SSN
                      value: 20028713506
                - name: SE_BANKID
                - name: FI_TUPAS
            notifications:
              - objectId: 398a79e2-7bf1-44cd-9233-dd8e48c82ef4
                method: EMAIL
                endpoint: signer@merchant.com
                triggers:
                  - STEPREADY
                  - STEPCOMPLETE
                  - ORDERCOMPLETE
            
    SignerAddDef:
      type: object
      required:
        [objectId]
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signerName:
          $ref: '#/components/schemas/EsosTypeSignerNameDef'
        signerEids:
          $ref: '#/components/schemas/SignerEidDef'
        merchantEid:
          $ref: '#/components/schemas/MerchantSignEidNamesEnum'
        notifications:
          type: array
          description: Notification channels for the signer
          items:
            $ref: '#/components/schemas/NotificationDef'
            
    SignerEidDef:
      type: object
      properties:
        signerIdScope:
          $ref: '#/components/schemas/SignerIdScopesEnum'
        signMethods:
          type: array
          description: Array of native signing eIDs for the signer 
          items:
            $ref: '#/components/schemas/SignMethodDef'
        authMethods:
          type: array
          description: Array of authentication based signing eIDs for the signer
          items:
            $ref: '#/components/schemas/AuthMethodDef'
            
    SignMethodDef:
      type: object
      required:
        [name]
      properties:
        name:
          $ref: '#/components/schemas/SignMethodEidNamesEnum'
        certPolicy:
          $ref: '#/components/schemas/CertPolicyTypesEnum'
        ids:
          type: array
          description: Identifier of the signer such SSN, PID, etc.
          items:
            $ref: '#/components/schemas/SignMethodIdDef'
            
    AuthMethodDef:
      type: object
      required:
        [name]
      properties:
        name:
          $ref: '#/components/schemas/AuthMethodEidNamesEnum'
        ids:
          type: array
          description: Identifier of the signer such SSN, PID, etc.
          items:
            $ref: '#/components/schemas/AuthMethodIdDef'
            
    NotificationDef:
      type: object
      required:
        [objectId, method, endpoint, triggers]
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        method:
          $ref: '#/components/schemas/NotificationMethodTypesEnum'
        endpoint:
          $ref: '#/components/schemas/EsosTypeEndpointDef'
        triggers:
          type: array
          description: Array of triggers to trigger notification to the intended notification channel
          items:
            $ref: '#/components/schemas/NotificationTriggerTypesEnum'
          
    NameValueDef:
      type: object
      properties:
        name:
          type: string
          description: Key name
        value:
          type: string
          description: Key value
          
    SignMethodIdDef:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/SignMethodIdTypesEnum'
        value:
          type: string
          description: Identifier value
          
    AuthMethodIdDef:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/AuthMethodIdTypesEnum'
        value:
          type: string
          description: Identifier value

    SignatureAdd:
      type: object
      required:
        [requestId, signedJWT]
      properties:
        requestId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signedJWT:
          type: string
          description: Signed JWT
          pattern: '(^[A-Za-z0-9-_=]+)([\.])([A-Za-z0-9-_=]+)([\.]?)([A-Za-z0-9-_.+\/=]*$)'
      example:
        requestId: 3484f0e7-b175-4345-a789-b666909870c4
        signedJWT: signed-jwt-string

    MerchantSignAdd:
      type: object
      required:
        [requestId, objectId, documentDescription, content]
      properties:
        requestId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        documentDescription:
          $ref: '#/components/schemas/EsosTypeDescriptionDef'
        content:
          $ref: '#/components/schemas/DocumentContentDef'
        merchantEid:
          $ref: '#/components/schemas/MerchantSignEidNamesEnum'
      example:
        requestId: 32c2f0e7-b175-4345-a789-b666909870c4
        objectId: 2aa2f0e7-b175-4345-a789-b666909870c4
        documentDescription: Description
        content:
          contentType: TEXT_PLAIN
          b64data: base64-bytes
          b64rule: base64-rule
        merchantEid: NO_BANKID
          
    ExecDetailsAdd:
      type: object
      required:
        [requestId]
      properties:
        requestId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        organisations:
          type: array
          description: An array of customer's organisation details
          items:
            $ref: '#/components/schemas/OrganisationDef'
        webContexts:
          type: array
          description: >
            An array of URLs that tells E-Signing where a signer is supposed to complete the signing 
            and where a signer shall be routed when he/she has signed or if an error occurs or if he/she cancels the signing.
          items:
            $ref: '#/components/schemas/WebContextDef'
        steps:
          type: array
          description: An array of steps, connecting the documents with the signers and the organisations, requied to complete the sign order
          items:
            $ref: '#/components/schemas/StepDef'
      example:
        requestId: b25bf0e7-b175-4345-a789-b666909870c4
        organisations:
          - objectId: 6e6f79e2-7bf1-44cd-9233-dd8e48c82ef4
            organisationNumber: 123456789
            businessCertificateRequired: true
            countryCode: NO
        webContexts:
          - objectId: dd6379e2-7bf1-44cd-9233-dd8e48c82ef4
            signUrlBase: https://www.sign-preprod1.nets.eu/sign/index.html?sref=
            statusUrlBase: https://www.merchant.com/statusurlbase
            styleUrl: https://www.merchant.com/styleurl
            exitUrl: https://www.merchant.com/successurl
        steps:
          - objectId: 616379e2-7bf1-44cd-9233-dd8e48c82ef4
            stepNumber: 1
            stepDeadline: 2024-05-10T10:09:19.525Z
            signProcesses:
              - objectId: 746379e2-7bf1-44cd-9233-dd8e48c82ef4
                documentReference: a6aa79e2-7bf1-44cd-9233-dd8e48c82ef4
                signerReference: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
                signerRole: SIGNER
                organisationRef: 6e6f79e2-7bf1-44cd-9233-dd8e48c82ef4
                webContextReference: dd6379e2-7bf1-44cd-9233-dd8e48c82ef4
            
    StepDef:
      type: object
      required:
        [objectId, stepNumber, signProcesses]
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        stepNumber:
          type: integer
          description: Positive integer indicating the step number, starting from 1 and to the number of steps in the sign order.
        stepDeadline:
          type: string
          format: date-time
          nullable: true
          description: Step deadline.  If this value is not provided, then the step deadline is set to sign order deadline.
        signProcesses:
          type: array
          description: An array of sign processes that combines the sign order documents with the signer, organisation details and web context details.
          items:
            $ref: '#/components/schemas/SignProcessDef'
            
    OrganisationDef:
      type: object
      required:
        [objectId, organisationNumber, businessCertificateRequired]
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        organisationNumber:
          $ref: '#/components/schemas/EsosTypeOrganisationNumberDef'
        businessCertificateRequired:
          type: boolean
          description: Indicates whether a business certificate shall be downloaded and added to the signed document object (SDO).
        countryCode:
          $ref: '#/components/schemas/EsosTypeCountryCodeDef'
            
    WebContextDef:
      type: object
      required:
        [objectId, signUrlBase]
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signUrlBase:
          $ref: '#/components/schemas/EsosTypeEndpointDef'
        statusUrlBase:
          $ref: '#/components/schemas/EsosTypeEndpointDef'
        styleUrl:
          $ref: '#/components/schemas/EsosTypeEndpointDef'
        exitUrl:
          $ref: '#/components/schemas/EsosTypeEndpointDef'
            
    SignProcessDef:
      type: object
      required:
        [objectId, documentReference, signerReference]
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        webContextReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        documentReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signerReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signerText:
          $ref: '#/components/schemas/EsosTypeDescriptionDef'
        signerRole:
          $ref: '#/components/schemas/SignerRoleTypesEnum'
        organisationReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        attachmentReferences:
          type: array
          description: An array of attachment references 
          items:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signatureRequired:
          type: boolean
        signProcessDeadline:
          type: string
          format: date-time
          nullable: true
          description: >
            Sign process deadline.  This deadline should not be beyond step dealine. 
            If this value is not provided, then it will be set to step deadline.
        reminderStart:
          type: string
          format: date-time
          nullable: true
          description: >
            Indicates the date on which to send reminder notification to the signer if he or she hasn't signed the document yet.
            This value must be after now and before sign process deadline.
        reminderInterval:
          type: integer
          description: Indicates the interval to send reminder notifications to the signer from the reminderStart.  This value must be specified in hours.
          
    PostProcessAdd:
      type: object
      required:
        [requestId]
      properties:
        requestId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        postProcesses:
          type: array
          description: An array of postprocessing instructions to be processed after all signatures in a sign order are performed.
          items:
            $ref: '#/components/schemas/PostProcessDef'
      example:
        requestId: 367bf0e7-b175-4345-a789-b666909870c4
        postProcesses:
          - objectId: 6e6f79e2-7bf1-44cd-9233-dd8e48c82ef4
            signAndProcuration:
              - organisationReference:
                documentReference: a6aa79e2-7bf1-44cd-9233-dd8e48c82ef4
                signerReferences: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
                verificationRequired: true
                verificationType: SIGN
                additionalInfo: Additional information
            orderArchives:
              - archiveName: eArchive
                objectReference:
                  documentReference: a6aa79e2-7bf1-44cd-9233-dd8e48c82ef4
                indexes:
                  - name: orgNumber
                    value: 123456789
                  - name: subArchiveName
                    value: sistest
            customProperties:
              - name: saksnummer
                value: 987654321
                signerReference: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
            
    PostProcessDef:
      type: object
      required:
        [objectId]
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signAndProcuration:
          type: array
          description: >
            Defines the mapping between organisations, documents and the signers that will be included in a sign and procura verification.
            The sign and procura verification uses IN Groupe ID-Rights service.
          items:
            $ref: '#/components/schemas/SignAndProcurationDef'
        orderArchives:
          type: array
          description: An array of details to be used for archiving the SDO (Signed Document Object) once all signatures in the sign order are performed. 
          items:
            $ref: '#/components/schemas/OrderArchiveDef'
        customProperties:
          type: array
          description: An array of custom properties to be added to SDO (Signed Document Object) once all signatures in the sign order are performed.
          items:
            $ref: '#/components/schemas/CustomPropertiesDef'
            
    SignAndProcurationDef:
      type: object
      required:
        [organisationReference, documentReference, verificationType, verificationRequired]
      properties:
        organisationReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        documentReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signerReferences:
          type: array
          description: An array of signer references to be used for sign and procura verification 
          items:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        verificationRequired:
          type: boolean
          description: Indicates whether sign and procura verification is required
        verificationType:
          $ref: '#/components/schemas/SignatureVerificationTypesEnum'
        additionalInfo:
          $ref: '#/components/schemas/EsosTypeIDRightsAdditionalInfoDef'
          
    OrderArchiveDef:
      type: object
      required:
        [archiveName, objectReference]
      properties:
        archiveName:
          type: string
          description: Name of the archive
        objectReference:
          $ref: '#/components/schemas/ArchiveObjectRefDef'
        indexes:
          type: array
          description: An array of indexes (name value pairs) to be archived along with the SDO (Signed Document Object).
          items:
            $ref: '#/components/schemas/NameValueDef'
        metadata:
          type: array
          description: An array of metadata (name value pairs) to be used for archiving the SDO (Signed Document Object).
          items:
            $ref: '#/components/schemas/NameValueDef'
            
    ArchiveObjectRefDef:
      type: object
      properties:
        organisationReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        documentReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
          
    CustomPropertiesDef:
      type: object
      required:
        [name]
      properties:
        name:
          type: string
          description: Custom property name
        value:
          type: string
          description: Custom property value
        signerReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
          
    PadesGenerateDef:
      type: object
      required:
        [padesReference, sdo]
      properties:
        padesReference:
          $ref: '#/components/schemas/EsosTypePadesRefDef'
        languageCode:
          type: string
          pattern: '^([a-zA-Z]{2})([-_][a-zA-Z]{0,2})?$'
          description: The language used on the last page of PAdES document added by IN Groupe
        returnPII:
          type: boolean
          description: Indicates whether to add Personal Identifiable Info (such as SSN, PID, etc) to the last page of PAdES document added by IN Groupe
        includeCustomProperties:
          type: boolean
          description: Whether to include custom properties in PAdES document
        timeZone:
          $ref: '#/components/schemas/EsosTypePadesTimeZoneDef'
        sdo:
          $ref: '#/components/schemas/SDODef'
      example:
        padesReference: 8aa4f0e7-b175-4345-a789-b666909870c4
        languageCode: NO
        returnPII: false
        includeCustomProperties: true
        timeZone: CET
        sdo:
          b64data: sdo-base64-bytes

    SDODetailsDef:
      type: object
      required:
        [ sdo ]
      properties:
        requestId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        sdo:
          $ref: '#/components/schemas/SDODef'
        returnPII:
         type: boolean
         description: Indicates whether to add Personal Identifiable Info (SSN) to the SDO details response
        returnOrganizationNumber:
         type: boolean
         description: Indicates whether to add organization number to the SDO details response
      example:
        requestId: c434f0e7-b175-4345-a789-b666909870c4
        sdo:
          b64data: sdo-base64-bytes
        returnPII: false
        returnOrganizationNumber: false

    SDODef:
      type: object
      required:
        [b64data]
      properties:
        b64data:
          type: string
          format: byte
          description: Base64 encoded document bytes
       
    ValidateSDODetailsDef:
      type: object
      required:
        [ validateSDO ]
      properties:
        requestId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        validateSDO:
          $ref: '#/components/schemas/ValidateSDODef'
      example:
        requestId: 8f34f0e7-b175-4345-a789-b666909870c4
        validateSDO:
          b64data: sdo-base64-bytes
          sdoSealed: true

    ValidateSDODef:
      type: object
      required:
        [ b64data, sdoSealed ]
      properties:
        b64data:
          type: string
          format: byte
          description: Base64 encoded SDO bytes 
        sdoSealed:
          type: boolean
          description: Indicates whether the SDO is sealed

    DocumentsSearchResult:
      type: object
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        documentTitle:
          $ref: '#/components/schemas/EsosTypeTitleDef'
        documentDescription:
          $ref: '#/components/schemas/EsosTypeDescriptionDef'
        requireAuthentication:
          type: boolean
          description: >
            Indicates whether the signers assigned to the document are forced to identify themselves before signing the document.
            If this value is set to true, then the signers who will be added to the document MUST have the signerId defined 
            while adding them to the sign order. 
        minSignerCount:
          type: integer
          description: >
            Indicates the number of end user signers required to sign the document. When this number is reached the document status is set to complete.
        preApproved:
          type: boolean
          description: >
            Indicates if the document is to be considered as PreApproved.
        contentType:
          $ref: '#/components/schemas/DocumentTypesEnum'
        status:
          $ref: '#/components/schemas/OrderStatusTypesEnum'
        signerInfos:
          type: array
          description: An array of signer details
          items:
            $ref: '#/components/schemas/SignerInfo'
        links:
          type: array
          description: Links to other endpoints in the API to manage the documents, such as to delete the document.
          items:
            $ref: '#/components/schemas/LinkDef'

    OrderStatesDef:
        type: object
        properties:
          orderStatus:
            $ref: '#/components/schemas/OrderStatusTypesEnum'
          sealStatus:
            $ref: '#/components/schemas/OrderStatusTypesEnum'
          archivalStatus:
            $ref: '#/components/schemas/OrderStatusTypesEnum'
          signAndProcuraVerificationStatus:
            $ref: '#/components/schemas/OrderStatusTypesEnum'
          businessCertificateStatus:
            $ref: '#/components/schemas/OrderStatusTypesEnum'
          
    DocumentsSearchResponse:
      type: object
      properties:
        responseId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        results:
          type: array
          items:
            $ref: '#/components/schemas/DocumentsSearchResult'
      example:
        responseId: 6592f0e7-b175-4345-a789-b666909639a2
        results:
          - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
            documentTitle: Document title
            contentType: TEXT_PLAIN
            status: INPROGRESS
            signerInfos:
              - signerReference: 887a79e2-7bf1-44cd-9233-dd8e48c82ef4
            links:
              - rel: documents-delete
                href: /esos/v1/<merchantid>/documents/566a79e2-7bf1-44cd-9233-dd8e48c82ef4
                type: DELETE

    AttachmentsSearchResult:
      type: object
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        documentTitle:
          $ref: '#/components/schemas/EsosTypeTitleDef'
        contentType:
          $ref: '#/components/schemas/DocumentTypesEnum'
        status:
          $ref: '#/components/schemas/OrderStatusTypesEnum'
        signerInfos:
          type: array
          description: An array of signer details
          items:
            $ref: '#/components/schemas/SignerInfo'
        links:
          type: array
          description: Links to other endpoints in the API to manage the documents, such as to delete the document.
          items:
            $ref: '#/components/schemas/LinkDef'
            
    AttachmentsSearchResponse:
      type: object
      properties:
        responseId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        results:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentsSearchResult'
      example:
        responseId: 3562f0e7-b175-4345-a789-b666909639a2
        results:
          - objectId: a34a79e2-7bf1-44cd-9233-dd8e48c82ef4
            documentTitle: Document title
            contentType: TEXT_PLAIN
            status: INPROGRESS
            signerInfos:
              - signerReference: 669a79e2-7bf1-44cd-9233-dd8e48c82ef4
            links:
              - rel: attachments-delete
                href: /esos/v1/<merchantid>/attachments/a34a79e2-7bf1-44cd-9233-dd8e48c82ef4
                type: DELETE

    SignerSearchResult:
      type: object
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        documentReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signerName:
          $ref: '#/components/schemas/EsosTypeSignerNameDef'
        signerStatus:
          $ref: '#/components/schemas/OrderStatusTypesEnum'
        signProcessDeadline:
          type: string
          format: date-time
          nullable: true
        signerUrl:
          type: string
        links:
          type: array
          items:
            $ref: '#/components/schemas/LinkDef'
          
    SignersGetResponse:
      type: object
      properties:
        responseId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        results:
          type: array
          items:
            $ref: '#/components/schemas/SignerSearchResult'
      example:
        responseId: 6592f0e7-b175-4345-a789-b666909639a2
        results:
          - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
            documentReference: 656a79e2-7bf1-44cd-9233-dd8e48c82ef4
            signerName: Signer name
            signerStatus: INPROGRESS
            signProcessDeadline: 2024-05-10T10:09:19.525Z
            signerUrl: https://www.e-sign.nets.eu/sign/index.html?sref=318132FEBCF1FCF740B0B3BDF06D9B5063814E8E
            links:
              - rel: signers-update
                href: /esos/v1/<merchantid>/signers/dd670c37-094c-4c03-bc78-5511e99e8dfc
                type: PUT
              - rel: signers-delete
                href: /esos/v1/<merchantid>/signers/dd670c37-094c-4c03-bc78-5511e99e8dfc
                type: DELETE
            
    SDOResponse:
      type: object
      properties:
        responseId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        results:
          type: array
          description: An array of SDOs (Signed Document Objects) for the sign order that is in COMPLETED status
          items:
            $ref: '#/components/schemas/SDOResult'
      example:
        responseId: 6592f0e7-b175-4345-a789-b666909639a2
        results:
          - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
            orderStatus: COMPLETED
            sdo:
              b64data: sdo-base64-bytes
    
    SDOResult:
      type: object
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        orderStatus:
          $ref: '#/components/schemas/OrderStatusTypesEnum'
        sdo:
          $ref: '#/components/schemas/SDODef'

    SignatureArchiveResponse:
      type: object
      properties:
        responseId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        results:
          type: array
          description: An array of Signature Archive's for the sign order that is in COMPLETED status
          items:
            $ref: '#/components/schemas/SignatureArchiveResult'
      example:
        responseId: 6592f0e7-b175-4345-a789-b666909639a2
        results:
          - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
            objectStatus: COMPLETED
            objectType: ASIC
            documentReference: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
            b64data: asic-base64-bytes

    SignatureArchiveResult:
      type: object
      required:
        [ objectId, objectStatus, objectType, b64data ]
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        objectStatus:
          $ref: '#/components/schemas/OrderStatusTypesEnum'
        objectType:
          $ref: '#/components/schemas/OutputFormatEnum'
        documentReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        b64data:
          type: string
          format: byte
          description: Base64 encoded zip document bytes
          
    SDOMergeDef:
      type: object
      properties:
        requestId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        sdos:
          type: array
          description: Array of SDOs to merge
          items:
            $ref: '#/components/schemas/SDODef'
      example:
        requestId: 333cf0e7-b175-4345-a789-b666909870c4
        sdos:
          - b64data: sdo-base64-bytes-1
          - b64data: sdo-base64-bytes-2

    SDOMergeResponse:
      type: object
      properties:
        responseId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        results:
          type: array
          description: Merged SDO response
          items:
            $ref: '#/components/schemas/SDOMergeResult'
      example:
        responseId: 6592f0e7-b175-4345-a789-b666909639a2
        results:
          - b64data: sdo-base64-bytes
    
    SDOMergeResult:
      allOf:
        - $ref: '#/components/schemas/SDODef'
    
    PadesGenerateResult:
      type: object
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        padesReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        content:
          $ref: '#/components/schemas/DocumentContentDef'
          
    PadesGenerateResponse:
      type: object
      properties:
        responseId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        results:
          type: array
          items:
            $ref: '#/components/schemas/PadesGenerateResult'
      example:
        responseId: 6592f0e7-b175-4345-a789-b666909639a2
        results:
          - objectId: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
            padesReference: 757a79e2-7bf1-44cd-9233-dd8e48c82ef4
            content:
              contentType: TEXT_PLAIN
              b64data: base64-bytes
              b64rule: base64-rule
            
    NotificationsSearchResult:
      type: object
      required:
        [objectId, signerReference, notificationStatus, method, endpoint, trigger]
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signerReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        merchantReference:
          type: string
          description: Merchant reference
        notificationStatus:
          $ref: '#/components/schemas/OrderStatusTypesEnum'
        notificationTime:
          type: string
          format: date-time
          nullable: true
          description: Notification date and time
        method:
          $ref: '#/components/schemas/NotificationMethodTypesEnum'
        endpoint:
          $ref: '#/components/schemas/EsosTypeEndpointDef'
        trigger:
          $ref: '#/components/schemas/NotificationTriggerTypesEnum'
        stepNumber:
          type: integer
          description: Step number
        documentReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
          
    NotificationsGetResponse:
      type: object
      properties:
        responseId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        results:
          type: array
          items:
            $ref: '#/components/schemas/NotificationsSearchResult'
      example:
        responseId: 6958f0e7-b175-4345-a789-b666909639a2
        results:
          - objectId: ac6579e2-7bf1-44cd-9233-dd8e48c82ef4
            signerReference: 757a79e2-7bf1-44cd-9233-dd8e48c82ef4
            merchantReference: 326579e2-7bf1-44cd-9233-dd8e48c82ef4
            notificationStatus: COMPLETED
            notificationTime: 2024-04-10T10:09:19.525Z
            method: EMAIL
            endpoint: signer@customer.com
            trigger: SIGNPROCESSREADY
            stepNumber: 1
            documentReference: 425169e2-7bf1-44cd-9233-dd8e48c82ef4
          
    SignerInfo:
      type: object
      required:
        [signerReference]
      properties:
        signerReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signerToken:
          $ref: '#/components/schemas/EsosTypeJWTDef'
          
    LinkDef:
      type: object
      properties:
        rel:
          type: string
          description: Relationship
        href:
          type: string
          description: Relative URI of the resource
        type:
          type: string
          description: Method type

    StreamsSearchResult:
      type: object
      required:
        [ objectId ]
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        type:
          $ref: '#/components/schemas/StreamTypesEnum'
        contentType:
          $ref: '#/components/schemas/DocumentTypesEnum'
        b64data:
          type: string
          format: byte
          description: Base64 bytes
        b64rule:
          type: string
          format: byte
          description: Rule used for creating PDF.

    StreamsSearchResponse:
      type: object
      properties:
        responseId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        results:
          type: array
          items:
            $ref: '#/components/schemas/StreamsSearchResult'
      example:
        responseId: 6958f0e7-b175-4345-a789-b666909639a2
        results:
          - objectId: ac6579e2-7bf1-44cd-9233-dd8e48c82ef4
            type: DOCUMENT
            contentType: TEXT_PLAIN
            b64data: base64-document-bytes
            b64rule: pdf-rule

    JsonNotificationResponse:
      type: object
      description: Refers to JSON Notification Channel Response based on triggers
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        orderId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        merchantId:
          type: integer
        timestamp:
          type: string
        notificationType:
          $ref: '#/components/schemas/NotificationTypeEnum'
        trigger:
          $ref: '#/components/schemas/NotificationTriggerTypesEnum'
        orderNotification:
          $ref: '#/components/schemas/OrderNotificationDef'
        stepNotification:
          $ref: '#/components/schemas/StepNotificationDef'
        signProcessNotification:
          $ref: '#/components/schemas/SignProcessNotificationDef'

    ExecDetailsSearchResponse:
      type: object
      properties:
        responseId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        results:
          type: array
          items:
            $ref: '#/components/schemas/ExecDetailsSearchResult'
      example:
        responseId: 3bb2f0e7-b175-4345-a789-b666909870c4
        results:
          organisations:
            - objectId: 6e6f79e2-7bf1-44cd-9233-dd8e48c82ef4
              organisationNumber: 123456789
              businessCertificateRequired: true
              countryCode: NO
          webContexts:
            - objectId: dd6379e2-7bf1-44cd-9233-dd8e48c82ef4
              signUrlBase: https://www.sign-preprod1.nets.eu/sign/index.html?sref=
              statusUrlBase: https://www.merchant.com/statusurlbase
              styleUrl: https://www.merchant.com/styleurl
              exitUrl: https://www.merchant.com/successurl
          steps:
            - objectId: 616379e2-7bf1-44cd-9233-dd8e48c82ef4
              stepNumber: 1
              stepDeadline: 2024-05-10T10:09:19.525Z
              signProcesses:
                - objectId: 746379e2-7bf1-44cd-9233-dd8e48c82ef4
                  documentReference: a6aa79e2-7bf1-44cd-9233-dd8e48c82ef4
                  signerReference: 566a79e2-7bf1-44cd-9233-dd8e48c82ef4
                  signerRole: SIGNER
                  organisationReference: 6e6f79e2-7bf1-44cd-9233-dd8e48c82ef4
                  webContextReference: dd6379e2-7bf1-44cd-9233-dd8e48c82ef4
                  attachmentReferences: [ ]
                  signatureRequired: false
                  signProcessDeadline: 2024-05-18T11:20:47+0000
                  reminderStart: null
                  reminderInterval: 0
                  signProcessStatus: READY
                  lastUpdate : 2024-05-18T09:20:42+0000
          links:
            - rel: exec-details-delete
              href: /esos/v1/<merchantid>/exec-details/566a79e2-7bf1-44cd-9233-dd8e48c82ef4
              type: DELETE

    ExecDetailsSearchResult:
      type: object
      properties:
        organisations:
          type: array
          items:
            $ref: '#/components/schemas/OrganisationDef'
        webContexts:
          type: array
          items:
            $ref: '#/components/schemas/WebContextDef'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/StepResult'
        links:
          type: array
          items:
            $ref: '#/components/schemas/LinkDef'

    StepResult:
      type: object
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        stepNumber:
          type: integer
          description: Step number
        stepDeadline:
          type: string
          format: date-time
          nullable: true
          description: Step deadline
        stepStatus:
          $ref: '#/components/schemas/OrderStatusTypesEnum'
        signProcesses:
          type: array
          items:
            $ref: '#/components/schemas/SignProcessResult'

    SignProcessResult:
      type: object
      properties:
        objectId:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        webContextReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        documentReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signerReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signerText:
          $ref: '#/components/schemas/EsosTypeDescriptionDef'
        signerRole:
          $ref: '#/components/schemas/SignerRoleTypesEnum'
        organisationReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        attachmentReferences:
          type: array
          items:
            $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signatureRequired:
          type: boolean
          description: Indicates whether signature is required
        signProcessDeadline:
          type: string
          format: date-time
          nullable: true
          description: Sign process deadline
        reminderStart:
          type: string
          format: date-time
          nullable: true
          description: >
            Indicates the date on which to send reminder notification to the signer if he or she hasn't signed the document yet.
        reminderInterval:
          type: integer
          description: Indicates the interval to send reminder notifications to the signer from the reminderStart.
        signProcessStatus:
          $ref: '#/components/schemas/OrderStatusTypesEnum'
        lastUpdate:
          type: string
          format: date-time
          nullable: true
          description: >
            Time when signing process is updated at last.

    OrderNotificationDef:
      type: object
      properties:
        rejectText:
          type: string

    StepNotificationDef:
      type: object
      properties:
        stepNumber:
          type: integer
        targetReferences:
          type: array
          items:
            $ref: '#/components/schemas/NotificationTargetReferenceDef'

    SignProcessNotificationDef:
      type: object
      properties:
        stepNumber:
          type: integer
        targetReferences:
          type: array
          items:
            $ref: '#/components/schemas/NotificationTargetReferenceDef'
        rejectText:
          type: string
        timestamp:
          type: string

    NotificationTargetReferenceDef:
      type: object
      properties:
        signerReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        documentReference:
          $ref: '#/components/schemas/EsosTypeObjectRefDef'
        signUrl:
          type: string

###############################################################
#
# Enumerations
#    
    ObjectNamesEnum:
      type: string
      enum:
        - DOCUMENT
        - ATTACHMENT

    OrderInfoDisplayEnum:
      type: string
      enum:
        - NAME
        - NAMESTATUS
        - NAMESTATUSTIME
      description: Indicates the details (Name of the signer, Signing status and Signed time) to display in Signing GUI. 
        
    OutputFormatEnum:
      type: string
      enum:
        - SDO
        - PADES
        - ASIC
      description: >
        Output format for the sign order once all signing are completed. Default is SDO.
        
        Note: The PAdES  output format is currently only supported by BankID NO and MitID through the NemLog-in broker. 
        When PAdES is set, it will not be possible to get a SDO returned for this sign order. If SDO is set, 
        a PAdES generated from the SDO may be returned if requested.
        
    DocumentTypesEnum:
      type: string
      enum:
        - TEXT_PLAIN
        - APPLICATION_PDF
        - APPLICATION_XML
        - APPLICATION_FORM
        - APPLICATION_PDF_FORM
      description: Document type constant
        
    MerchantSignEidNamesEnum:
      type: string
      enum:
        - NO_BANKID
      description: ID Provider name constant allowed for Merchant signature
        
    SignMethodEidNamesEnum:
      type: string
      enum:
        - NO_BANKID
        - SE_BANKID
        - DK_MITID
        - FI_TUPAS
      description: ID Provider name constant
        
    SignMethodIdTypesEnum:
      type: string
      enum:
        - SSN
        - UUID
        - PID
        - RID
      description: Identifier type constant
        
    SignerIdScopesEnum:
      type: string
      enum:
        - BASIC
        - SSN
      description: Signer ID scope constant
        
    SignerRoleTypesEnum:
      type: string
      enum:
        - SIGNER
        - WITNESS
        - APPROVER
      description: Signer role constant
        
    SignatureVerificationTypesEnum:
      type: string
      enum:
        - SIGN
        - PROCURA
      description: Signature verification type constant
        
    AuthMethodEidNamesEnum:
      type: string
      enum:
        - DK_MITID
        - FI_TUPAS
        - NETS_SMS
        - NO_BANKID
        - PASSPORT_READER
        - SE_BANKID
        - SMART_ID
        - MOBILE_ID
        - VERIMI
      description: ID Provider name constant
        
    AuthMethodIdTypesEnum:
      type: string
      enum:
        - SSN
        - UUID
        - PID
        - RID
      description: Identifier type constant
        
    CertPolicyTypesEnum:
      type: string
      enum:
        - ALL
        - PERSONAL
        - PERSONALQUALIFIED
        - EMPLOYEE
        - EMPLOYEEQUALIFIED
        - ORGANISATION
      description: Acceptable certificate policy type constant
        
    NotificationMethodTypesEnum:
      type: string
      enum:
        - XML
        - EMAIL
        - SMS
        - JSON
      description: Notification method constant
        
    NotificationTriggerTypesEnum:
      type: string
      enum:
        - ORDERCOMPLETE
        - ORDERCANCEL
        - ORDERREJECT
        - ORDEREXPIRE
        - ORDERFAIL
        - SIGNPROCESSREADY
        - SIGNPROCESSCOMPLETE
        - SIGNPROCESSREMINDER
        - SIGNPROCESSREJECT
        - SIGNPROCESSEXPIRE
        - STEPREADY
        - STEPCOMPLETE
        - STEPEXPIRING
      description: Notification trigger constant
        
    OrderStatusTypesEnum:
      type: string
      enum:
        - INITIAL
        - PENDING
        - READY
        - INPROGRESS
        - COMPLETED
        - CANCELLED
        - REJECTED
        - EXPIRING
        - EXPIRED
        - FAILED
        - DELETED
      description: Order status constant

    StreamTypesEnum:
      type: string
      enum:
        - DOCUMENT
        - ATTACHMENT
        - PDFFORMDATA
        - CUSTOMRESPONSE
      description: Stream type constant

    NotificationTypeEnum:
      type: string
      enum:
        - SIGNING-PROCESS
        - STEP
        - ORDER
      description: Notification type constant

    EsosPassResponse:
      type: object
      properties:
        responseType:
          $ref: '#/components/schemas/EsosResponseTypesEnum'
        responseId:
          $ref: '#/components/schemas/EsosTypeTIDDef'
      example:
        responseType: PASS
        responseId: 3ac95124-b175-4345-a789-b666909639a2
          
    EsosFailResponse:
      type: object
      properties:
        responseType:
          $ref: '#/components/schemas/EsosResponseTypesEnum'
        responseId:
          $ref: '#/components/schemas/EsosTypeTIDDef'
        message:
          type: string
          description: Error message
      example:
        responseType: FAIL
        responseId: 61d95124-b175-4345-a789-b666909639a2
        message: Error message
          
    EsosDataResponse:
      type: object
      properties:
        responseType:
          $ref: '#/components/schemas/EsosResponseTypesEnum'
        responseId:
          $ref: '#/components/schemas/EsosTypeTIDDef'
        results:
          type: array
          items:
            $ref: '#/components/schemas/Result'
            
    Result:
      type: object

    EsosResponseTypesEnum:
      type: string
      enum:
        - PASS
        - FAIL
        - DATA
      description: Respone type constant
          
    EsosTypeTIDDef:
      type: string
      pattern: '^[a-zA-Z0-9]{36,64}$'
      description: Transaction identifier
          
    EsosTypeTitleDef:
      type: string
      pattern: '^.{4,100}$'
      description: Title text
       
    EsosTypeDescriptionDef:
      type: string
      pattern: '^.{4,240}$'
      description: Description text, with a minimum of 4 characters and a maximum of 240 characters in length 
                
    EsosTypeOrderDescriptionDef:
      type: string
      pattern: '^.{0,400}$'
      description: Order description, limited to 400 characters in length.
                
    EsosTypeOrganisationNumberDef:
      type: string
      pattern: '^.{0,20}$'
      description: Organisation number
                
    EsosTypeCountryCodeDef:
      type: string
      pattern: '^.{2}$'
      description: Country code in ISO 3166-1 alpha-2 format
      
    EsosTypeIDRightsAdditionalInfoDef:
      type: string
      pattern: '^.{0,50}$'
      description: Additional information text

    EsosTypeJWTDef:
      type: string
      pattern: '(^[A-Za-z0-9-_=]+)([\.])([A-Za-z0-9-_=]+)([\.]?)([A-Za-z0-9-_.+\/=]*$)'
      description: JSON Web Token

    EsosTypeEndpointDef:
      type: string
      pattern: '^[a-zA-Z0-9-/:_@.\?|=#%&]{8,400}$'
      description: URI
          
    EsosTypeObjectRefDef:
      type: string
      pattern: '^[a-zA-Z0-9-:_@.\?=]{1,80}$'
      description: Unique ID per request. UUID is recommended.

    EsosTypePadesRefDef:
      type: string
      pattern: '^[\p{L}0-9-:_@.\?= ]{1,40}$'
      description: Unique ID per request.  UUID is recommended.
      
    EsosTypeSignerNameDef:
      type: string
      pattern: '[^"]{0,110}'
      description: Signer name

    EsosTypePadesTimeZoneDef:
      type: string
      pattern: '^.{0,50}$'
      description: Time zone

  securitySchemes:
    esosAuth:
      type: oauth2
      description: API authentication scheme to be used for the operations
      flows:
        clientCredentials:
          tokenUrl: /esos/token
          refreshUrl: /esos/refresh
          scopes:
            post: create resources
            get: query resources
            put: update resources
            delete: purge resources

servers:
  - description: Development service (for internal use)
    url: https://www-dev-sign.bbsas.no/esos/v1
  - description: Preproduction service (for customer test)
    url: https://www.sign-preprod1.nets.eu/esos/v1
  - description: Production service
    url: https://www.e-sign.nets.eu/esos/v1