When accessing the Fortune3 API, you must usually create an enctrypted Hash Signature for sending each request. Although its use is highly recommended by Fortune3, this Hash Signature requirement can be turned off in the Fortune3 Admin Site under the API Setup screen. If the Hash Signature requirement is enabled (the default setting), the following items are required for each request to be authenticated:

timestamp: The time stamp (or expiration time) you use in the request must be a dateTime object (for more information, go to http://www.w3.org/TR/xmlschema-2/#dateTime). Although it is not required, we recommend you provide the time stamp in the Coordinated Universal Time (Greenwich Mean Time) time zone. For example: 2007-01-31T23:59:59.183Z.

hash: Each request must contain a valid request hash, or the request is rejected. The HMAC-SHA1 hash is calculated from the concatenation of APIUsername+APIPassword+timestamp, using your API Key as the key. For example, in the sample request below, the value of the Signature element is the HMAC-SHA1 digest of this string: [APIUsername][APIPassword]2005-01-31T23:59:59.183Z

content: this parameter should contain the xml code with your request.

To calculate the hash signature:

• Concatenate the values of the API Username, API Password, and timestamp request parameters, in that order.
• Calculate an HMAC-SHA1 signature, using your Secret Key (from Step 1) as the key.
• Convert the resulting value to base64.
• Pass the final value in the hash parameter of the Query request.

Click below to view sample codes to create the Hash Signature:

.NET Example
PHP Example
PERL Example

Example Query Snippet:

&hash=FvUH0tcso/u1P4vqJt7cXLPGrV8=
&timestamp=2011-03-23T00:43:12Z
&content=$xml

Post your XML request using a standard HTTP post to the API URL provided in the Admin Site, adding the hash, timestamp, and content parameters to the API URL (using GET or POST) as explained above. The syntax for your XML content (the content parameter) is explained in the section below and the steps ahead.

Authenticate the XML message using the API Username and API Password given to you in Step 1. Every message you send to Fortune3 must be authenticated, as shown below:

Sample Code:
<sendRequestXML>
<authenticate>
<APIUsername>LKas9iKsL</APIUsername>
<APIPassword>qKW8sXAADu91TGDl</APIPassword>
</authenticate>
</sendRequestXML>

If you do not receive an error message when posting this request, you have successfully connected to the API and authenticated.

Next: Sending the Request