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 + . 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. Response will contain b64data field which is Base64 encoded XML value of [GetSDODetails](https://doc.ingroupe.com/developer/signed-documents#sd2) 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/StreamsSearchResponse' '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/OrderUpdateStatusTypesEnum' 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//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 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' pdf: $ref: '#/components/schemas/PDFDef' 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 PDFDef: 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//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//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//signers/dd670c37-094c-4c03-bc78-5511e99e8dfc type: PUT - rel: signers-delete href: /esos/v1//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//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 - NETS 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 - NEXUSDA:CASEWORKER - NEXUSDA:CASESIGNER - NEXUSDA:CITIZEN 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 description: Order status constant OrderUpdateStatusTypesEnum: type: string enum: - READY - INPROGRESS - COMPLETED - CANCELLED description: Order update 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