Verify Pack (Verification DSCSA API) : Movilitas.Cloud Support

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:

Key	Action
Content-Type	Apply JSON format for the content. Use the value application/json.
x-access-token	Provide the authentication token.
x-channel-key	Provide 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.

Field	Required or Optional?	Type	Description
atp_verifiable_presentation	Optional	String	The 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.
gln	Required	String	The Global Location Number of the requester as per the GS1 standard.
serial	Required	String	The serial number of the trade item as per the GS1 standard.
gtin	Required	String	The Global Trade Item Number (GTIN) of the trade item.
batch	Required	String	The batch of the trade item as per the GS1 standard.
expiry_date	Required	String	The expiry date of the trade item in the YYMMDD format as per the GS1 standard.
verification_request_contact_info	Optional	Object	The contact information of the requester.
email	Optional	String	The email address of the requester.
telephone	Optional	String	The phone number of the requester.
context	Required	Enum	The context of the verification. One of the following values: dscsaSaleableReturn dscsaSuspectIllegitimate dscsaExceptionVerification dscsaStatusCheck
control_possess_attribute	Optional	Boolean	The 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_value	Required	String	The 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:

Field	Type	Description
success	Boolean	Indicates whether the request was successful (true) or not (false).
message	String	Message response.
data	Object	If 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_code	Number	The error status code from the verification endpoint.
verification_endpoint_response_body	String or Object	The 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_uuid	String	The correlation UUID of the verification request. The response is linked to the request and they hold the same correlation UUID.
verified	Boolean	The verification result for the trade item (product identifier): true - The item is valid. false - The item is not valid.
verification_timestamp	String	The timestamp of the trade item verification.
verification_failure_reason	String	If 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_info	String	Optional additional information as per the GS1 Lightweight Messaging Standard for DSCSA Verification of Product Identifiers.
responder_gln	String	The Global Location Number of the responder as per the GS1 standard. Empty when not provided.
responder_atp_verifiable_presentation	String	The JSON Web Token (JWT) that represents the verifiable credential of the responder.
responder_atp	Object	The responder verification data. Applicable when the responder verification is performed through Movilitas.Cloud. Otherwise, the object is an empty {}.
verified	String	The 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_timestamp	String	The timestamp of the responder verification.
verification_failure_reason	String	If 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_info	Object	The responder data extracted from the verifiable credential.
id	String	The digital identifier key of the responder.
type	String	The type of the responder information.
legalName	String	The legal name of the responder.
issuerName	String	The name of the issuer.
postalCode	String	The postal code of the responder.
addressRegion	String	The region of the responder.
streetAddress	String	The street of the responder.
addressCountry	String	The country of the responder.
addressLocality	String	The locality of the responder.
organizationType	String	The organization type of the responder.
responder_contact_email	String	The email address of the responder. Empty when not provided.
responder_contact_telephone	String	The 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.


{
    "success": false,
    "message": "Failed to authenticate token.",
    "code": "ERR0000"
}
{
    "success": false,
    "message": "Expiry date is required and it has to be by GS1 standard"
}
{
    "success": false,
    "message": "GTIN not found. Contact support@movilitas.cloud"
}
{
    "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": ""
    }
}
{
    "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
    }
}

#	Situation	Status Code Received from Responder	Status Code of API Response	Body of API Response
1	Invalid 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" }
3	GTIN is not in Movilitas.Cloud Lookup Directory	N/A*	404	{ "success": false, "message": "GTIN not found. Contact support@movilitas.cloud" }
4	Responder responds with 200 status code	200	200	The 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": "" } }
5	Responder 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 Type	Error Code	Description
No token provided	ERR0001	No authentication token is provided. Ensure that you add the authentication token to the header of the request.
Failed to authenticate token	ERR0000	Failed 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.

Verify Pack

Related Articles