To successfully authenticate your API call, you have to pass your Consumer ID and the digital signature in the API header for every API call you make. You can get your Consumer ID and a Private Key as part of the on-boarding process. Review the Getting Started section to start using the APIs.
Integration Steps
- Make a simple API call, for example: GET Feed Status.
- Generate a signature. There are two ways to generate digital signatures: using the JAR executable or coding the signature method yourself. We strongly recommend using the JAR as this eliminates the vast majority of issues when authenticating calls.
- Pass the header attributes to authenticate your API call. See Table 1: Header Attributes.
- Validate that the call does not throw a 400 or 401 error, refer to Error Codes.
Note: If you are having trouble connecting, refer to Troubleshooting.
Table 1: Header Attributes
Name | Description | Required | Example |
WM_SVC.NAME | Walmart Service Name | Yes | Walmart Gateway API |
WM_QOS.CORRELATION_ID | A unique ID that 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 for V3, optional for V2 | 0f3e4dd4-0514-4346-b39d-… use the Consumer Channel Type received during onboarding |
WM_CONSUMER.ID | A unique ID required to access the API | Yes | G et the Consumer ID from Developer Center after logging in |
- If a 400 HTTP status code is thrown, ensure you have passed all of the mandatory headers. Also, verify that you have sent all mandatory query or path parameters as well as the proper Accept HTTP header.
- If a 401 HTTP status code is thrown, verify your signature generation to make sure that the required parameters were passed to your authentication code.
JAR executable (Recommended)
The JAR executable is available for download: digitalSignatureUtil-1.0.0.jar
The JAR requires that any server/computer calling the executable locally have Java SE 6.0 or greater installed. For more information on how to install Java, you can get it from the Oracle website.
The JAR executable can be run in any of your code that allows for calls to the console or running arbitrary commands on the command line. To run the JAR, call the JAR as follows:
java -jar DigitalSignatureUtil-1.0.0.jar DigitalSignatureUtil {requestUrl} {consumerId} {privateKey} {requestMethod} {filePath}
Note: Your program must run this JAR in the directory where the JAR is installed. See descriptions in Table 2: Jar Parameters.
Sample call to Jar executable:
java -jar DigitalSignatureUtil-1.0.0.jar DigitalSignatureUtil https://marketplace.walmartapis.com/v3/feeds/d4885da4-9bc1-4296-b26f-57e3cb0e0fc9?includeDetails=true 9a4d7659-100c-4d5e-a6b0-26faad4c9132 MIICeAIBADANBgkqhkiG9w0BAQEFAA... GET HelloWorld
Header Sample:
WM_SVC.NAME: Walmart Content
WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6
WM_SEC.TIMESTAMP: 1438147839
WM_SEC.AUTH_SIGNATURE: 7QzL9PeRt0WSGbXNGGj4kSQ9L6PMBX/q+ovdy9bDQfvdhYs8NoEsjRX4fD7UNIHTddgkmSVqAqeIIHlaLcRIl0Y4DcJqQYHL27LiWlsm91nYodGssWTKsOq6dJfUHEy95M4zXFGWDDhbHYCor28SCV/g/JdEQybGkcX9Zj5aDyg=
WM_CONSUMER.ID: a20ac266-9add-4fc7-9392-fec303f5155c
WM_CONSUMER.CHANNEL.TYPE: 0f3e4dd4-0514-4346-b39d-af0e00ea
Accept: application/xml
Table 2: Jar Parameters
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 is desired for the digital signature and timestamp. The digital signature and timestamp can also be viewed in the console. | Yes |
Self-written code (Expert)
- Assemble the following information:
- The full URL you wish to call, including any path and query parameters.
- Your Consumer ID (for example, 9a4d7659-100c-4d5e-a6b0-26faad4c9132).
- Your Base 64-encoded Private Key.
- Your request method in all capitals (for example, GET).
- Construct input for the signature (NOTE: The order of the parameters and the line returns \n are important to generate the signature properly):
the Consumer ID issued to you_ + “\n” + the url of the call you are making + “\n” + the request method of the call you are making in all capitals + “\n” + the Unix Epoch timestamp now (in milliseconds since Jan 01 1970 UTC) + “\n” - Sign the byte array representation of this data by:
- Decoding the Base-64, PKCS-8 representation of your Private Key. Note that the key is encoded using PKCS-8. Libraries in various languages offer the ability to specify that the key is in this format and not in other conflicting formats such as PKCS-1.
- Use this byte representation of your key to sign the data using SHA-256 with RSA.
- Encode the resulting signature using Base-64.
- Use the generated signature and the timestamp to make your API call.
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.
To accelerate development you can use the Google Chrome Advanced REST Client App (ARCA). If basic API calls are successful from the ARCA, but not from your own code, the problem lies in your code. If the call from the ARCA fails, there is a problem with your headers.
Test scenario with Pro Tips
- Make an API call with the ARCA:
https://marketplace.walmartapis.com/v3/feeds.
- Set the method to GET, use the headers as defined in Table 1: Header Attributes and then click Send.
- If the call from ARCA succeeds, the headers are correct. If your code fails, examine the headers.
- If the call from the ARCA fails, and you did not use the Jar executable file:
- Use the Jar executable to generate headers, and try again.
- If the call succeeds now, start by using the Jar file instead of the self-written code, or adjust the code to generate the headers correctly.
- If the call from the ARCA fails and you did use the Jar executable file:
- Send an email to CSPSupport@wal-mart.com, and ask for the new set of credentials.
- Retry with the new credentials. If this fails, and you are sure that you have configured the ARCA correctly, contact Walmart Marketplace Support.
Sample Signing Code: PHP
$URL = //Walmart API URL along with path and query parameters
$RequestMethod = //Request method type i.e GET, POST
$Timestamp = round(microtime(true) * 1000); //Current system timestamp
function _GetWalmartAuthSignature($URL, $RequestMethod, $Timestamp) {
$WalmartPrivateKey = //Your Walmart Private Key;
$WalmartConsumerID = //Your Walmart Comsumer Id;
// CONSTRUCT THE AUTH DATA WE WANT TO SIGN
$AuthData = $WalmartConsumerID."\n";
$AuthData .= $URL."\n";
$AuthData .= $RequestMethod."\n";
$AuthData .= $Timestamp."\n";
// GET AN OPENSSL USABLE PRIVATE KEY FROMM THE WARMART SUPPLIED SECRET
$Pem = _ConvertPkcs8ToPem(base64_decode($WalmartPrivateKey));
$PrivateKey = openssl_pkey_get_private($Pem);
// SIGN THE DATA. USE sha256 HASH
$Hash = defined("OPENSSL_ALGO_SHA256") ? OPENSSL_ALGO_SHA256 : "sha256";
if (!openssl_sign($AuthData, $Signature, $PrivateKey, $Hash))
{ // IF ERROR RETURN NULL return null; }
//ENCODE THE SIGNATURE AND RETURN
return base64_encode($Signature);
}
function _ConvertPkcs8ToPem($der)
{
static $BEGIN_MARKER = "-----BEGIN PRIVATE KEY-----";
static $END_MARKER = "-----END PRIVATE KEY-----";
$key = base64_encode($der);
$pem = $BEGIN_MARKER . "\n";
$pem .= chunk_split($key, 64, "\n");
$pem .= $END_MARKER . "\n";
return $pem;
}
}
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://marketplace.walmartapis.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;
}
}