You can use the Verification DSCSA API to integrate the third-party systems with the DSCSA Product Verification & Tracing application.


The Verification DSCSA API uses the Representational State Transfer (REST) standard to interact with other systems.


The Verification DSCSA API is an extension of the DSCSA Product Verification & Tracing application of Movilitas.Cloud and enables you to send requests from external systems to the application.


This article describes how to send a verification request to Movilitas.Cloud by using the Verification DSCSA API.


API Tool to Use


In this document, we provide examples by using the cURL command-line tool. To send the API request, you can find a lot of user-friendly REST API tools on the Internet, for example, Postman.


Before You Begin


Before you start sending any messages:


1. You must enable the DSCSA Product Verification & Tracing application in the Admin UI.

2. You must create an API key and secret. 

3. You must create a shopfloor channel with Verification DSCSA API source. You will need the channel key for your requests.

4. You must have the authentication token to send requests over API. Select one of the following ways:

  • Apply a dynamic token. Send an authentication request over the Authentication API. For more information about the Authentication API, open the Tenant Dashboard in Movilitas.Cloud, select API keys, and choose Authentication API Documentation. Also, see Authentication Request.
  • Apply a static token. Generate a static token for your previously created API key.


For more information, see Configuring the Movilitas.Cloud APIs.


Procedure


1. Use the POST method and the following URL:


https://api.movilitas.cloud/v1/product_verification_dscsa/api/verify


2. For the header, define the following:


KeyAction
Content-TypeApply JSON format for the content. Use the value application/json.
x-access-tokenProvide the authentication token.
x-channel-keyProvide the channel key of your Verification DSCSA API channel.


3. In the body of the request, define the parameters and their values based on the table below.


FieldRequired or Optional?TypeDescription
atp_verifiable_presentationOptionalStringThe JSON Web Token (JWT) that represents the verifiable credential of the requester.

Applicable when the verifiable credential is obtained outside Movilitas.Cloud.

When not specified, the responder responds only in the case the responder accepts requests without a verifiable credential.
glnRequiredStringThe Global Location Number of the requester as per the GS1 standard.
serialRequiredStringThe serial number of the trade item as per the GS1 standard.
gtinRequiredStringThe Global Trade Item Number (GTIN) of the trade item.
batchRequiredStringThe batch of the trade item as per the GS1 standard. 
expiry_dateRequiredStringThe expiry date of the trade item in the YYMMDD format as per the GS1 standard.
verification_request_contact_infoOptionalObjectThe contact information of the requester.
       emailOptionalStringThe email address of the requester.
       telephoneOptionalStringThe phone number of the requester.
contextRequiredEnumThe context of the verification. One of the following values:
  • dscsaSaleableReturn
  • dscsaSuspectIllegitimate
  • dscsaExceptionVerification
  • dscsaStatusCheck
control_possess_attributeOptionalBooleanThe flag that highlights whether the trade item to be verified is in the possession of the requester:
  • true
  • false


When not specified, the possession attribute is not passed.


IMPORTANT: If the product is not in the possession of the requester ("false") or the possession attribute is not passed, the responder might reject responding.

GS1US_version_valueRequiredStringThe GS1 US version that must be a fixed value, "1.3.0".


4. Send the request.


Sample cURL Request 


curl -X POST \
 'https://api.movilitas.cloud/v1/product_verification_dscsa/api/verify' \
-H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR6cDI6IkpXVCJ0.eyJrZXkiOiJmYjVtQUhyTmhta05mSkJjX250clRHRTNfZkoqRktlKkdqVDRFMkNNU0FtaEFGMk43Q2JmNEY3QVJTMy01M2Q4IiwiX2lkIjoiNjQyMzQxNTkyNmFiYzQ4ZDMxOTE0MWE0IiwiaWF0IjoxNjgwNDNyMTgzfQ.t894-oEC' \
-H 'x-channel-key: zBDgSJ1iKUpNmmcp1izN0QEBCaULGEGqxazXJ3H' \
-H 'Content-Type: application/json' \
-d '{
    "atp_verifiable_presentation": "eyJhbGciOiJFZERTSSIsInR6cCI6IkrXVCJ.0eyJpYXQiOjE2ODA3MDM1MTEsImV4cCI6MTY4MTQ4Njc2NiwidnAiRnsiQGMvbnRLeHQiOlsiaHR0cHM6My93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiXSwidHlwZSI6Wy",
    "gln": "2996133448223",
    "serial": "MVCSN3048",
    "gtin": "00338300555778",
    "batch": "MVC001",
    "expiry_date": "250531",
    "verification_request_contact_info": {
        "email": "admin@movilitas.cloud",
        "telephone": "+3221234567"
    },
    "context": "dscsaSaleableReturn",
    "control_possess_attribute": true,
    "GS1US_version_value": "1.3.0"
}'


The application sends back a response that contains the following fields in the body:


FieldTypeDescription
successBooleanIndicates whether the request was successful (true) or not (false).
messageStringMessage response.
dataObjectIf success is "true", it contains the verification response data.

If success is "false" and the verification endpoint of the responder returns an error, it shows the verification endpoint status code (error) and the verification endpoint response body (when available).

The rows below are grouped based on the response from the responder and these fields are part of the "data" object.
If the responder sends back an error
  verification_endpoint_status_codeNumberThe error status code from the verification endpoint.
   verification_endpoint_response_bodyString or ObjectThe response body of the error from the verification endpoint.

Movilitas.Cloud supports the following formats and passes the response without change:
  • Plain text
  • XML
  • HTML
  • JSON
  • Empty (missing response body)


The data type of the field (string or object) varies depending on the type of response body.

If the responder sends back the verification response
   correlation_uuidStringThe correlation UUID of the verification request. The response is linked to the request and they hold the same correlation UUID. 
   verifiedBooleanThe verification result for the trade item (product identifier):
  • true - The item is valid.
  • false - The item is not valid.
   verification_timestampStringThe timestamp of the trade item verification.
   verification_failure_reasonStringIf the verification result for the trade item (product identifier) is "false", the reason for the verification failure as per the GS1 Lightweight Messaging Standard for DSCSA Verification of Product Identifiers. Otherwise, it is empty.
   additional_infoStringOptional additional information as per the GS1 Lightweight Messaging Standard for DSCSA Verification of Product Identifiers.
   responder_glnStringThe Global Location Number of the responder as per the GS1 standard. Empty when not provided.
   responder_atp_verifiable_presentationStringThe JSON Web Token (JWT) that represents the verifiable credential of the responder.
   responder_atpObjectThe responder verification data.

Applicable when the responder verification is performed through Movilitas.Cloud. Otherwise, the object is an empty {}.
        verifiedStringThe verification result for the responder:
  • true - The responder is valid.
  • false - The responder is invalid.
  • not provided - The responder has not provided the verifiable credential in the response.
       verification_timestampStringThe timestamp of the responder verification.
       verification_failure_reasonStringIf the verification result for the responder is "false", the reason for the verification failure as per the Open Credential Initiative (OCI) guidelines. Otherwise, "null".
       responder_infoObjectThe responder data extracted from the verifiable credential.
               idStringThe digital identifier key of the responder.
               typeStringThe type of the responder information.
               legalNameStringThe legal name of the responder.
               issuerNameStringThe name of the issuer.
               postalCodeStringThe postal code of the responder.
               addressRegionStringThe region of the responder.
               streetAddressStringThe street of the responder.
               addressCountryStringThe country of the responder.
               addressLocalityStringThe locality of the responder.
               organizationTypeStringThe organization type of the responder.
   responder_contact_emailStringThe email address of the responder. Empty when not provided.
   responder_contact_telephoneStringThe phone number of the responder. Empty when not provided.



Sample Responses


Movilitas.Cloud acts as a resolver, by forwarding the request to the responder and returning the response from the responder. There is a a response from Movilitas.Cloud API and, when applicable, there is a response from the responder. The following table summarizes the possible responses by separating what is returned by Movilitas.Cloud API and what is returned by the responder.


#SituationStatus Code Received from ResponderStatus Code of API ResponseBody of API Response
1Invalid Movilitas.Cloud token provided for accessing API.
N/A*401
{
    "success": false,
    "message": "Failed to authenticate token.",
    "code": "ERR0000"
}
2

Incorrect expiration date structure provided

(similar for GTIN, serial and batch).

N/A*400
{
    "success": false,
    "message": "Expiry date is required and it has to be by GS1 standard"
}
3GTIN is not in Movilitas.Cloud Lookup Directory
N/A*404
{
    "success": false,
    "message": "GTIN not found. Contact support@movilitas.cloud"
}
4Responder responds with 200 status code
200200The body is a representation of the data returned from the responder, presented in a structure specific to the Movilitas.Cloud Verification DSCSA API.

{
    "success": true,
    "message": "Product verification response",
    "data": {
        "correlation_uuid": "60c5d76b-1627-4605-b353-4baf9e17ae3c",
        "verified": true,
        "verification_timestamp": "2024-05-08T16:59:42.057Z",
        "verification_failure_reason": "",
        "additional_info": "",
        "responder_gln": "0338300871687",
        "responder_atp_verifiable_presentation": "eyJhbGciOiJFZERVQSIsInR5cCI6IkpXVCJ9.eyJpYNQiOjE3MT",
        "responder_atp": {
            "verified": true,
            "verification_timestamp": "2024-05-08T16:59:44.270Z",
            "verification_failure_reason": null,
            "responder_info": {
                "id": "did:key:z6MkoBCkedA2wb6Ez36iD6M5gN2wbuX4AasPBVhL23vo4t9F",
                "type": "DSCSAATPCredential",
                "legalName": "ValidCA ValidOrderThree",
                "issuerName": "test_did_test_legisym",
                "postalCode": "45385",
                "addressRegion": "Maryland",
                "streetAddress": "676 Martin Luther King Hwy P.O. Box 898",
                "addressCountry": "United States",
                "addressLocality": "Baltimore",
                "organizationType": "Dispenser"
            }
        },
        "responder_contact_email": "marc.blekkink@movilitas.com",
        "responder_contact_telephone": ""
    }
}
5Responder responds with a non-200 status code
XXX**400
{
    "success": false,
    "message": "Request to verification endpoint failed with status code XXX",
    "data": {
        "verification_endpoint_status_code": XXX,
        "verification_endpoint_response_body": the body (if any) that was returned from the responder
    }
}

*Not applicable. No call is made to any responder.

**Non-200 status code.


For more information on verification failure reasons and additional information from the responder, see VRS Responses for the Pack (Verification Failure Reason and Additional Info).


For more information on verification errors from the responder, see Verification Error Handling.


Other System Actions


If the requester is not yet existing in the DSCSA Product Verification & Tracing application in the Admin UI, the requester is auto-created with the following parameters:

  • Requester name. Note: If the verifiable credential is not present in the request, the GLN is added as the name.
  • Requester GLN.


Example:



Errors and Resolution


This section lists some of the most general error messages or error types from Movilitas.Cloud API when sending the request.


Error Message or Error TypeError CodeDescription
No token providedERR0001No authentication token is provided. Ensure that you add the authentication token to the header of the request.
Failed to authenticate tokenERR0000Failed to authenticate the provided token. Double-check if your token has expired or has been revoked. Obtain a valid token by generating a static one or by getting a dynamic one through Authentication API.
Channel ID is missing or it needs to be in correct format-The channel key of your Verification DSCSA API channel is not specified in the request. To get the channel key, go to Tenant Dashboard --> Channels in the Admin UI, open your Verification DSCSA API channel, and find the channel key on the top of the Edit shopfloor channel panel.
Request body could not be parsed-The syntax of the request body is not correct, for example, a comma is missing at the end of a field. Make sure that the request body is defined in the correct way and that you use JSON format.
Validation error-The given data is invalid. It does not follow the required data type or pattern. The response includes details about the specific issue. Follow the explanation in the response and correct your data.