To authenticate an API call successfully, pass a Consumer ID and digital signature in the header for every API call.
Register as a Walmart Drop Ship Vendor to receive a Consumer ID and Private Key. Log into the Developer Portal to obtain these items. For instructions, See Introduction to DSV APIs.
You can use the Consumer ID and Private Key, along with other required header parameters, to generate a digital signature.
Integration Process
You can integrate with the DSV APIs by calling an API and generating a digital signature.
- Choose a simple GET method to call one of the DSV resources. For example, call GET Feed Status: GET /v3/feedstatus.
- Generate a digital signature.
Note: The digital signature will expire in 15 minutes; regenerate the signature using the same procedure. There are two ways to generate a digital signature:
Using the executable JAR file will eliminate a majority of authentication issues.
Pass the following header keys to authenticate your API call:
Name | Description | Required | Example |
---|---|---|---|
WM_SVC.NAME | Walmart Service Name | Yes | Walmart Gateway API |
WM_QOS.CORRELATION_ID | A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID | Yes | 1234hfvgtr |
WM_SEC.TIMESTAMP | The Epoch timestamp | Yes | 1443748249449 |
WM_SEC.AUTH_SIGNATURE | The vendor’s digital signature, generated by running the JAR file or custom generation code | Yes | 9fg3TPeRt0WSGbXNGGj4kSQ9L6PMBX/q+ovdy9bDQfvdhYs8NoEsjRX4fD7UNIHTddgkmSVqAqeIIHlaLcRIl0Y4DcJqQYHL27LiWlsm91nYodGssWTKsOq6dJfUHEy95M4zXFGWDDhbHYCor28SCV/g/JdEQybGkcX9Zj5aDyg= |
WM_CONSUMER.CHANNEL.TYPE | A unique ID to track the consumer request by channel | Yes | 0f3e4dd4-0514-4346-b39d-… use the Consumer Channel Type received during onboarding |
WM_CONSUMER.ID | A unique ID required to access the API | Yes | Get the Consumer ID from Developer Center after logging in |
Accept | The returned data format in the response | No | application/xml |
Note: Content Type for Get calls is not required but may be automatically pre-filled and cause a system error during authentication. If you receive this error, check to see if Content Type is included as a header parameter and remove it.
If you are having trouble connecting to Developer Center, refer to Troubleshooting.
- Make sure the call does not throw a 400 or 401 error. For more information, refer to Error Codes.
- If a 400 HTTP status code is received, validate the mandatory headers and all mandatory query or path parameters.
- If a 401 HTTP status code is received, verify the digital signature.
Generate a Digital Signature Using an Executable JAR File (Recommended):
To generate a digital signature using the executable JAR file, follow these steps:
- Download Java 6.0 or greater. If it is not installed on your computer, go to: https://java.com/en/download
- Download the executable JAR file: digitalSignatureUtil-1.0.0.jar
- Use the following command to run the executable JAR file: java -jar DigitalSignatureUtil-1.0.0.jar DigitalSignatureUtil {requestUrl} {consumerId} {privateKey} {requestMethod} {filePath}
Note: Your program must run this executable JAR file in the directory where the executable JAR file is located.
Running the executable JAR file returns the following two headers as the console output:
- WM_SEC.AUTH_SIGNATURE
- WM_SEC.TIMESTAMP
The executable JAR file uses five parameters; see the table below:
Name | Description | Required |
---|---|---|
requestUrl | The full URL to call, including path and query parameters | Yes |
consumerId | The Consumer ID retrieved from Developer Center after login | Yes |
privateKey | The vendor’s Base-64-encoded, PKCS#8 stored Private Key | Yes |
requestMethod | Use method GET (all capital letters) to call this API | Yes |
filePath | The absolute (full) path of the file desired for the digital signature and timestamp. The digital signature and timestamp can also be viewed in the console. | Yes |
Note: Generate a digital signature and timestamp for every API call, even if it is for the same API. Sample call to the executable JAR
java -jar DigitalSignatureUtil-1.0.0.jar DigitalSignatureUtil https://api-gateway.walmart.com/v3/feeds/d4885da4-9bc1-4296-b26f-57e3cb0e0fc9?includeDetails=true 9a4d7659-100c-4d5e-a6b0-26faad4c9132 MIICeAIBADANBgkqhkiG9w0BAQEFAA... GET HelloWorld
Sample output authentication signature (Note For security reasons, the authentication signature is truncated.)
WM_SEC.AUTH_SIGNATURE:Lhq8pXEC9...
WM_SEC.TIMESTAMP:1438149671421
Generate a Digital Signature with self-written code
To get the digital signature using self-written code, follow these steps:
- Get the Consumer ID and Private Key from the Developer Portal.
- Get the full URL you wish to call, including any path and query parameters.
- Use the GET method to construct an input for the digital signature.
Use the structure listed below:
The Consumer ID_ + “\n” + the URL of the API call + “\n” + the request method of the API call in all capitals + “\n” + the current Unix epoch timestamp + “\n”
Note: The order of the parameters and the line returns \n are important to generate the signature properly; see the sample code in the right pane.
- Generate the byte array of the structured data listed in step 3 using the following steps:
- Decode the byte array with Base-64.
- Encode the resulting value using PKCS#8 to represent your Private Key.
Libraries in various languages offer the ability to identify that the Private Key is in PKCS#8 format and not in other conflicting formats such as PKCS#1. - Use this byte representation of the Private Key to sign the data using SHA-256 with RSA.
- Encode the generated digital signature using Base 64.
- Use the generated digital signature and Unix epoch timestamp to make an API call.
Sample Signing Code: JAVA
import org.apache.commons.codec.binary.Base64;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.Signature;
import java.security.spec.PKCS8EncodedKeySpec;
public class SHA256WithRSAAlgo {
private static String consumerId = "b68d2a72...."; // Trimmed for security reason
private static String baseUrl = "https://api-gateway.walmart.com/v3/feeds";
private static String privateEncodedStr = "MIICeAIBADANBgkqhkiG9w0BAQEFAA......"; //Trimmed for security reasons
public static void main(String[] args) {
String httpMethod = "GET";
String timestamp = String.valueOf(System.currentTimeMillis());
String stringToSign = consumerId + "\n" + baseUrl + "\n" + httpMethod + "\n" + timestamp + "\n";
String signedString = SHA256WithRSAAlgo.signData(stringToSign, privateEncodedStr);
System.out.println("Signed String: " + signedString);
}
public static String signData(String stringToBeSigned, String encodedPrivateKey) {
String signatureString = null;
try {
byte[] encodedKeyBytes = Base64.decodeBase64(encodedPrivateKey);
PKCS8EncodedKeySpec privSpec = new PKCS8EncodedKeySpec(encodedKeyBytes);
KeyFactory kf = KeyFactory.getInstance("RSA");
PrivateKey myPrivateKey = kf.generatePrivate(privSpec);
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(myPrivateKey);
byte[] data = stringToBeSigned.getBytes("UTF-8");
signature.update(data);
byte[] signedBytes = signature.sign();
signatureString = Base64.encodeBase64String(signedBytes);
} catch (Exception e) {
e.printStackTrace();
}
return signatureString;
}
}
Troubleshooting
New users can experience difficulty when trying to integrate with the platform for the first time. Typically, errors occur when incorrect headers are generated (such as the timestamp or authentication signature). To avoid errors, use the headers listed in the header samples displayed in each corresponding section. Sample Request Header
WM_SVC.NAME: Drop Ship Vendor Services
WM_CONSUMER.ID: a20ac266-9add-4fc7-9392-fec303f5155c
WM_SEC.TIMESTAMP: 1438147839
WM_SEC.AUTH_SIGNATURE: j7Lh5PeRt0WSGbXNGGj4kSQ9L6PMBX/q+ovdy9bDQfvdhYs8NoEsjRX4fD7UNIHTddgkmSVqAqeIIHlaLcRIl0Y4DcJqQYHL27LiWlsm91nYodGssWTKsOq6dJfUHEy95M4zXFGWDDhbHYCor28SCV/g/JdEQybGkcX9Zj5aDyg=
WM_CONSUMER.CHANNEL.TYPE: 0f3e4dd4-0514
Testing the API Calls
To accelerate development, you can use an online tool such as the Google Chrome Advanced Rest Client App (ARCA), Postman, etc.
To test your API calls using the ARCA, follow the steps below:
- Enter the URL: https://api-gateway.walmart.com/v3/feeds?feedType=SUPPLIER_FULL_ITEM
- Select GET from the drop-down menu.
- Configure the headers as listed in step 3 of the ‘Integration Steps’ section.
- Click Send.
If basic API calls are successful from the ARCA but are not successful from the self-written code, the problem lies in the self-written code. If the calls fail from the ARCA, there is a problem with the headers in the call.
Troubleshooting Hints
- If the call from the ARCA succeeds, the headers are correct. However, if the call fails, examine the headers.
- If the call from the ARCA fails and you are not using the executable JAR file, generate the headers using the executable JAR file and try again. If the call now succeeds, either start using the executable JAR file in place of the self-written authentication code, or adjust the self-written code to generate the headers correctly.
- If the call from the ARCA fails while using the executable JAR file, generate a new set of credentials from Developer Portal and retry with the new credentials. This ensures that the credentials are not obsolete, or you have not reset the Private Key recently.
- If the ARCA is configured correctly and the most current credentials are being used, but errors still exist, contact Partner Support.