The transition from the old Optimizer to the New Optimizer in the REST API may necessitate minor adjustments in client implementations; however, significant changes are generally not required. This migration guide aims to provide a comprehensive overview of the steps needed to successfully migrate from the old Optimizer to the New Optimizer.

1 Conceptual Changes
2 Changes in API Calls
- 2.1 Removed and Deprecated calls
- 2.2 Modified calls
  - 2.2.1 Endpoint renaming
  - 2.2.2 Updated Request Body for /sign
3 Changes in the response structure
- 3.1 Create Request
- 3.2 Upload Document
- 3.3 Send OTP
- 3.4 Sign
- 3.5 Create Token
- 3.6 Upload Image

Conceptual Changes

The new Optimizer is redefining the routing structure by transitioning from the previous format of all routes strictly using /api/v1 in the path component to a new format that utilizes /oneshot/api/v1.

Changes in API Calls

Removed and Deprecated calls

As part of the recent updates, the following calls have been removed:

POST /api/v1/settings
GET /api/v1/settings
GET /api/v1/requests
GET /api/v1/async/status/{{request-pk}}

Modified calls

Endpoint renaming

Previous: POST /api/v1/request
Current: POST /oneshot/api/v1/create
Previous: GET /api/v1/document/{{request-pk}}/signed/{{document-id}}
Current: GET /oneshot/api/v1/document/{{request-pk}}/{{document-uid}}
Note: You must now specify in the query parameters whether you want to retrieve the signed document or the original version.

Updated Request Body for `/sign`

The structure of the main request body for:

POST /oneshot/api/v1/sign/{{request-pk}}/

has been updated. Below is an example of the base request body format:

{
  "secret": "string",
  "signature": {
    "appearance": {
      "text": [
        "string"
      ],
      "date": "string",
      "timezone": "string",
      "position": "string",
      "page": 0,
      "image": "string"
    }
  }
}

Changes in the response structure

Some API calls now yield different outcomes.

Create Request

The create request call now presents an updated message. Previously, it only provided the status and details.

Now, it indicates whether the request was successful, includes an informational message about its creation along with the corresponding primary key (PK), and details the request's status, whether it is asynchronous or synchronous, and the associated PK.

{
    "status": "success",
    "message": "Request created with pk 349826",
    "detail": {
        "status": "ENROLLREADY",
        "asyncmode": false,
        "pk": 349826
    }
}

Upload Document

The upload document feature now presents an enhanced message. Previously, it only provided the status and details.

Now, it includes the name assigned to the document key along with its unique identifier (UID):

{
    "status": "success",
    "detail": [
        {
            "name": "file0",
            "uid": "84f54176-3600-4f70-9f20-7ce25e88b91f"
        }
    ]
}

Send OTP

The send OTP call now presents a clear message indicating the phone number to which the OTP has been dispatched.

{
    "status": "success",
    "detail": "OTP successfully sent to +34640234526"
}

Sign

The sign call has been updated to provide more comprehensive information. Previously, it only displayed the status and details.

Now, it shows the call status along with an informational message. Additionally, the details section includes the request number and the document that has been signed.

{
    "status": "success",
    "message": "Signature process for Request 360522 completed",
    "detail": {
        "request": "360522",
        "documents": {
            "signed": [
                "9473e0c6-0ffa-4d4c-8d77-b135dad8b227"
            ],
            "inerror": []
        }
    }
}

Create Token

The create token call now provides a more informative response. Previously, it only displayed the status and details.

Now, it indicates whether the call was successful, includes an informational message, and presents the generated token in the details.

{
    "status": "success",
    "message": "Token created",
    "detail": {
        "token_uid": "1c35903b-f2bf-487b-9239-4fcd49bcc"
    }
}

Upload Image

The upload image call has also been enhanced to deliver a clearer response. In the past, it merely showed the status and details.

Now, it confirms whether the call was successful, provides an informational message, and includes the generated UID in the details.

{
    "status": "success",
    "message": "Image uploaded with uid 6eeec456-a61c-41fb-97f1-ef600d3866ea",
    "detail": {
        "image_uid": "6eeec456-a61c-41fb-97f1-ef600d3866ea"
    }
}

Migrate REST API clients from old Optimizer to New Optimizer One-Shot