MDLP credential management APIs

Russia Compliance supports exportable and non-exportable certificates to digitally sign reports that are submitted to MDLP.

Owners who use exportable certificates can use the credentials API.

If Owners who use non-exportable certificates choose to build their own app to digitally sign reports, they must integrate with the Report retrieval APIs. Owners can also use the TraceLink-provided Russia Report Signature Appender app to digitally sign reports without any integration. See Retrieve non-exportable certificates for domestic credentials for more information.

Digital Certificate Upload (REST)

Authentication

Owners who choose to use exportable certificates for domestic MDLP credentials must use the Web UI and the Digital Certificate Upload REST API. Administrators use the Web UI to configure the app and the REST API to upload digital certificates to a secure TraceLink server in Russia, which MDLP requires for domestic credentials.

An IT professional uses the following message to finish configuring exportable domestic credentials for MDLP by uploading a digital certificate to a secure TraceLink server in Russia, which MDLP requires for domestic credentials. The upload can be completed using a curl command on a computer with a UNIX or Windows 10 operating system.

A TraceLink Administrator must generate the ruconnectorToken (i.e. security token) for the message in the Company Administration Web UI when they enter the domestic credentials.

The security token is valid for 30 minutes after generation.

Use a Post curl command to the following URL:

  • itest – https://itest-upload.ru1.tracelink.com/api/credentials
  • prod – https://upload.ru1.tracelink.com/api/credentials

Include a Content-Type header key-value pair with a value of multipart/form-data in the curl command.

Guidelines

Data Element Occurs
Length		 Type Description
ruconnectorToken

[1...1]

[1/36]

 String Required. The TraceLink provided value when saving credentials for a domestic account. This token is valid for 30 minutes.
password

[1...1]

[-]

 String Required. The password for the digital signature.
file

[1...1]

[-]

 String Required. The location on the local computer where the digital signature is located. Include @ before the file name.

Example

Copy 
curl -i -X POST -H "Content-Type: multipart/form-data" -F "ruconnectorToken=0c382d0e-bcd7-4ed7-b502-a1210bb529f9" -F "password=pfx_password" -F "file=@credentials.pfx" https://itest-upload.ru1.tracelink.com/api/credentials

Errors

There are no errors for in this request. See the Digital Certificate Upload response for examples of a successful and failed response.

Guidelines

There are no elements in this response.

Example - Success

Copy 
HTTP/1.1 100 Continue
HTTP/1.1 201 Created
Date: Wed, 26 Feb 2020 19:44:33 GMT
Content-Length: 0

Example - Failure

Copy 
HTTP/1.1 100 Continue
HTTP/1.1 400 Bad Request
Date: Fri, 28 Feb 2020 14:49:20 GMT
Content-Type: text/plain
Content-Length: 30
Ru Connector Token has expired

Report retrieval APIs

Owners can build their own app to retrieve reports by using the following APIs in this order:

Use this message to retrieve the token provided by TraceLink to use in the Tasks and Task Result APIs. The token is valid for 600 minutes i.e. 10 hours. The User ID and Password are provided when Administrators configure Russia Compliance.

Authentication

Use a POST curl command to the following URL:

  • itest – https://itest-upload.ru1.tracelink.com/api/token
  • prod – https://upload.ru1.tracelink.com/api/token

Include a Content-Type header key-value pair with a value of application/json in the curl command.

Request guidelines

Data Element Type Description
userId String Required. The TraceLink-provided value when saving credentials for a domestic account using the Certificate Digest and Certificate ID.
password String Required. The TraceLink-provided value when saving credentials for a domestic account using the Certificate Digest and Certificate ID.

Request examples

Curl

Copy 
curl --location "https://qe-upload.ru1.tracelink.com/api/token" ^
--header "Content-Type: application/json" ^
--data "{""userId"":""m?Hw!8InpM%sd44K"",""password"":""N(1^dQ6Q#(#xpj<I""}"

JSON

Copy 
{
    "userId": "i0lNgFiBQ9WurPil",
    "password": "!SNuBbOAwR)Yizw="
}

Response guidelines

Data Element Type Description
token String The token that is obtained for a User ID and Password combination, and must be used in the Task and Task Result APIs.
lifeTime String The validity of the token in minutes. Default value is 600 minutes.
certThumbprint String The Thumbprint credentials that are configured for MDLP.
errorMessage String Displays an error message for a failed authentication.

Response example

Success

Copy 
{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb21wYW55SWQiOiIwZmI1Njk1Yi1kODJlLTRkMmQtODVmOC01NTZhMjFhZjljNDkiLCJwYXNzd29yZCI6IiFTTnVCYk9Bd1IpWWl6dz0iLCJsb2NhdGlvbklkIjoiZGYxNmZjOTQtYmZhNS00NmI0LThmY2EtMjNiZmMzOTNjYWMyIiwiZXhwIjoxNzE4OTgxNjc0LCJ1c2VySWQiOiJpMGxOZ0ZpQlE5V3VyUGlsIn0.-K661S6UNWJNUofbODziSotb0rYbAahzQjBLcuhgXbc",
    "lifeTime": 600,
    "certThumbprint": "cba7ccccb875295fa94ab411fc2c614a95f94684"
}

Failure

Copy 
{
    "errorMessage": "Authentication failed. Please check your user ID and password, or ensure all required keys are provided."
}

Errors

Element Error Message Description
User ID Authentication failed. The error occurs if the user ID is incorrect.
Authentication failed. Please check your user ID and password, or ensure all required keys are provided. The error occurs if either user ID or password is not provided.
Password Authentication failed. The error occurs if the password is incorrect.
Authentication failed. Please check your user ID and password, or ensure all required keys are provided. The error occurs if either user ID or password is not provided.

Use this message to retrieve up to 5 reports that require a signature. The reports must be signed and returned with the Task Result API while the token is still valid (i.e. within 600 minutes of retrieving the token).

Authorization

Use a GET curl command to the following URL:

  • itest – https://itest-upload.ru1.tracelink.com/api/tasks
  • prod – https://upload.ru1.tracelink.com/api/tasks

Include a Content-Type header key-value pair with a value of application/json in the curl command.

Include an authorization token header value with the token provided by TraceLink in the Token's response.

This request does not include any elements in the payload.

Request example

Copy 
curl --location "https://itest-upload.ru1.tracelink.com/api/tasks" ^
--header ""Authorization": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb21wYW55SWQiOiIwZmI1Njk1Yi1kODJlLTRkMmQtODVmOC01NTZhMjFhZjljNDkiLCJsb2NhdGlvbklkIjoiMDAwMDAwMDAxMjE0MzUiLCJleHAiOjE3MjA3NDA4Mzd9.3TXEOR6B1AJd9hwMKU3ylGy6OmSj_U_d_EOs2aYewBo""

Response guidelines

Data Element Type Description
taskList String

Required. The Russia Compliance reports that require a signature. The signed reports must be returned with the Task Result request in the same order as they are provided in this response.
  taskId String Unique identifier for each report.
  signingTaskContentPreSignedUrl String

Presigned URL of the request file that needs to be signed before submitting to the MDLP and responded with the taskId as primary identifier for the Task Result endpoint.
  signatureType String

The signature type for the report. Valid values:

  • Attached - The signature is attached to the report.

  • Detached - The signature is not attached to the report.

  signingPayload String Token to be signed in case the taskId is mdlp_token_request or oms_token_request.
errorMessage String Displays if the token is invalid.
errorCode String Displays if the token is invalid.

Response example

Copy 
{
  taskList": [
  {
     "taskId": "mdlp_token_request",
     "signatureType": "DETACHED",
     "signingPayload": "ff344de4-da5d-41e6-96db-e5b578ab85eb"
  },
  { 
     "taskId": "oms_token_request",
     "signatureType": "DETACHED",
     "signingPayload": "e7a0d24d-d50a-4d06-be8f-de2e5b2911c1"
  },
  { 
     "taskId": "1720103193_297942f6-8b41-46f4-b163-df6748a4fd57",
     "signingTaskContentPreSignedUrl": "https://<aws_path>/russia-pharma-compliance/non-export-cert-signing-documents/credentialId%3D0fb5695b-d82e-4d2d-85f8-556a21af9c49_00000000121435/reports-request/1720103193_297942f6-8b41-46f4-b163-df6748a4fd57?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240704T142657Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3599&X-Amz-Credential=AKIAU7PFTQKSM3KZKXWJ%2F20240704%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=60c4f812379cc802d4183f7692650ee55ff50f8db692bec9d284e2c6b2cebfe4",
     "signatureType": "DETACHED"
  },
  { 
     "taskId": "1720077318_075341e1-886f-4e7c-9f43-43d4aec71bd1",
     "signatureType": "https://<aws_path>/russia-pharma-compliance/non-export-cert-signing-documents/credentialId%3D0fb5695b-d82e-4d2d-85f8-556a21af9c49_00000000121435/reports-request/1720077318_075341e1-886f-4e7c-9f43-43d4aec71bd1?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240704T071904Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3599&X-Amz-Credential=AKIAU7PFTQKSM3KZKXWJ%2F20240704%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=fe5f943d81c429bd64a213293c1698c391a30514b6063bf9f2e977a5f9442ff8",
     "signatureType": "DETACHED"
  }
 ]
}

Errors

Element Error Message Description
Authorization Authentication Failure. The error occurs if the token provided in the header is invalid or expired.

Use this message to return the signed reports to Russia Compliance. Each request can only contain one report at a time

Authorization

Use a POST curl command to the following URL:

  • itest – https://itest-upload.ru1.tracelink.com/api/taskResult
  • prod – https://upload.ru1.tracelink.com/api/taskResult

Include a Content-Type header key-value pair with a value of application/json in the curl command.

Include an authorization token header value with the token provided by TraceLink in the Token's response.

Request guidelines

Data Element Type Description
signedData String

Required. The signingPayload or signingTaskContentPreSignedUrl from the Task response that identifies the report.
taskId String

Required. The unique identifier of the report from the Task response.
status String

Required. The status of the digital signature. Valid values:

  • SUCCESS - The report is signed successfully.

  • ERROR - The report could not be signed.
signingPayload String

Optional. The signingPayload from the Task response that identifies the report.
errorCode String Required if the status is ERROR. Valid value is INTERNAL_FAILURE.
errorDescription String Required if the status is ERROR. The description of the error.

Request examples

Copy 
{
"signedData": "<signedValue>", 
"taskId": "1720112492_b6ec24af-dbb4-4e75-ad0d-475d6625aa0b_2",
"status": "SUCCESS"  
}

Copy 
{
"signedData": "<signedValue>", 
"signingPayload": "e7a0d24d-d50a-4d06-be8f-de2e5b2911c1",
"taskId": " "oms_token_request",
"status": "SUCCESS"  
}

Response guidelines

If the request is successful, there is no response payload. The following elements are only returned if an error occurs.

Data Element Type Description
errorMessage String

The description of the error that occurred.
errorCode String

The error code. Valid values:

  • 101 - Authentication failure.

  • 105 - The payload of the request exceeded the maximum 5KB limit.

Response example

Copy 
{
"errorMessage": "Payload size exceeds the configured maximum limit (in KB): 5", 
"errorCode": 105  
}

Errors

Element Error Message Description
Authorization Authentication Failure The error occurs if the token provided in the header is invalid or expired.
Request message size Payload size exceeds the configured maximum limit (in KB): [5] The error occurs if the payload size exceeds the configured maximum limit of 5 KB.