(PureBasic) ShippingEasy.com Calculate Signature for API Authentication

Demonstrates how to calculate the shippingeasy.com API signature for authenticating requests.

Note: This example requires Chilkat v11.0.0 or greater.

Chilkat PureBasic Module Download Chilkat PureBasic Module

IncludeFile "CkJsonObject.pb"
IncludeFile "CkDateTime.pb"
IncludeFile "CkHttp.pb"
IncludeFile "CkCrypt2.pb"
IncludeFile "CkStringBuilder.pb"
IncludeFile "CkHttpResponse.pb"

Procedure ChilkatExample()

    success.i = 0

    ; This example requires the Chilkat API to have been previously unlocked.
    ; See Global Unlock Sample for sample code.

    ; 
    ; First, concatenate these into a plaintext string using the following order:
    ; 
    ;     Capitilized method of the request. E.g. "POST"
    ;     The URI path
    ;     The query parameters sorted alphabetically and concatenated together into a URL friendly format: param1=ABC&param2=XYZ
    ;     The request body as a string if one exists
    ;     All parts are then concatenated together with an ampersand. The result resembles something like this:
    ; 
    ; "POST&/partners/api/accounts&api_key=f9a7c8ebdfd34beaf260d9b0296c7059&api_timestamp=1401803554&{ ... request body ... }"

    sbStringToSign.i = CkStringBuilder::ckCreate()
    If sbStringToSign.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    httpVerb.s = "POST"
    uriPath.s = "/partners/api/accounts"
    queryParamsStr.s = "api_key=YOUR_API_KEY&api_timestamp=UNIX_EPOCH_TIMESTAMP"

    ; Build the following JSON that will be the body of the request:

    ; {
    ;   "account": {
    ;     "first_name": "Coralie",
    ;     "last_name": "Waelchi",
    ;     "company_name": "Hegmann, Cremin and Bradtke",
    ;     "email": "se_greg_6d477b1e59e8ff24abadfb59d3a2de3e@shippingeasy.com",
    ;     "phone_number": "1-381-014-3358",
    ;     "address": "2476 Flo Inlet",
    ;     "address2": "",
    ;     "state": "SC",
    ;     "city": "North Dennis",
    ;     "postal_code": "29805",
    ;     "country": "USA",
    ;     "password": "abc123",
    ;     "subscription_plan_code": "starter"
    ;   }
    ; }

    json.i = CkJsonObject::ckCreate()
    If json.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    CkJsonObject::ckUpdateString(json,"account.first_name","Coralie")
    CkJsonObject::ckUpdateString(json,"account.last_name","Waelchi")
    CkJsonObject::ckUpdateString(json,"account.company_name","Hegmann, Cremin and Bradtke")
    CkJsonObject::ckUpdateString(json,"account.email","se_greg_6d477b1e59e8ff24abadfb59d3a2de3e@shippingeasy.com")
    CkJsonObject::ckUpdateString(json,"account.phone_number","1-381-014-3358")
    CkJsonObject::ckUpdateString(json,"account.address","2476 Flo Inlet")
    CkJsonObject::ckUpdateString(json,"account.address2","")
    CkJsonObject::ckUpdateString(json,"account.state","SC")
    CkJsonObject::ckUpdateString(json,"account.city","North Dennis")
    CkJsonObject::ckUpdateString(json,"account.postal_code","29805")
    CkJsonObject::ckUpdateString(json,"account.country","USA")
    CkJsonObject::ckUpdateString(json,"account.password","abc123")
    CkJsonObject::ckUpdateString(json,"account.subscription_plan_code","starter")

    CkJsonObject::setCkEmitCompact(json, 0)
    Debug CkJsonObject::ckEmit(json)

    ; First, let's get the current date/time in the Unix Epoch Timestamp format (which is just an integer)
    dt.i = CkDateTime::ckCreate()
    If dt.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    CkDateTime::ckSetFromCurrentSystemTime(dt)
    ; Get the UTC time.
    bLocalTime.i = 0
    unixEpochTimestamp.s = CkDateTime::ckGetAsUnixTimeStr(dt,bLocalTime)

    ; Build the string to sign:
    CkStringBuilder::ckAppend(sbStringToSign,httpVerb)
    CkStringBuilder::ckAppend(sbStringToSign,"&")
    CkStringBuilder::ckAppend(sbStringToSign,uriPath)
    CkStringBuilder::ckAppend(sbStringToSign,"&")
    CkStringBuilder::ckAppend(sbStringToSign,queryParamsStr)
    CkStringBuilder::ckAppend(sbStringToSign,"&")
    ; Make sure to send the JSON body of a request in compact form..
    CkJsonObject::setCkEmitCompact(json, 1)
    CkStringBuilder::ckAppend(sbStringToSign,CkJsonObject::ckEmit(json))

    ; Use your API key here:
    your_api_key.s = "f9a7c8ebdfd34beaf260d9b0296c7059"

    numReplaced.i = CkStringBuilder::ckReplace(sbStringToSign,"YOUR_API_KEY",your_api_key)
    numReplaced = CkStringBuilder::ckReplace(sbStringToSign,"UNIX_EPOCH_TIMESTAMP",unixEpochTimestamp)

    ; Do the HMAC-SHA256 with your API secret:
    your_api_secret.s = "ea210785fa4656af03c2e4ffcc2e7b5fc19f1fba577d137905cc97e74e1df53d"
    crypt.i = CkCrypt2::ckCreate()
    If crypt.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    CkCrypt2::setCkMacAlgorithm(crypt, "hmac")
    CkCrypt2::setCkEncodingMode(crypt, "hexlower")
    CkCrypt2::ckSetMacKeyString(crypt,your_api_secret)
    CkCrypt2::setCkHashAlgorithm(crypt, "sha256")

    api_signature.s = CkCrypt2::ckMacStringENC(crypt,CkStringBuilder::ckGetAsString(sbStringToSign))
    Debug "api_signature: " + api_signature

    ; --------------------------------------------------------------------
    ; Here's an example showing how to use the signature in a request:

    ; Build a new string-to-sign and create a new api_signature for the actual request we'll be sending...
    CkStringBuilder::ckClear(sbStringToSign)
    CkStringBuilder::ckAppend(sbStringToSign,"GET")
    CkStringBuilder::ckAppend(sbStringToSign,"&")
    CkStringBuilder::ckAppend(sbStringToSign,"/app.shippingeasy.com/api/orders")
    CkStringBuilder::ckAppend(sbStringToSign,"&")
    CkStringBuilder::ckAppend(sbStringToSign,queryParamsStr)
    CkStringBuilder::ckAppend(sbStringToSign,"&")
    ; There is no body for a GET request.

    api_signature = CkCrypt2::ckMacStringENC(crypt,CkStringBuilder::ckGetAsString(sbStringToSign))

    http.i = CkHttp::ckCreate()
    If http.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    queryParams.i = CkJsonObject::ckCreate()
    If queryParams.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    CkJsonObject::ckUpdateString(queryParams,"api_signature",api_signature)
    CkJsonObject::ckUpdateString(queryParams,"api_timestamp",unixEpochTimestamp)
    CkJsonObject::ckUpdateString(queryParams,"api_key",your_api_key)

    resp.i = CkHttpResponse::ckCreate()
    If resp.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    success = CkHttp::ckHttpParams(http,"GET","https://app.shippingeasy.com/api/orders",queryParams,resp)
    If success = 0
        Debug CkHttp::ckLastErrorText(http)
        CkStringBuilder::ckDispose(sbStringToSign)
        CkJsonObject::ckDispose(json)
        CkDateTime::ckDispose(dt)
        CkCrypt2::ckDispose(crypt)
        CkHttp::ckDispose(http)
        CkJsonObject::ckDispose(queryParams)
        CkHttpResponse::ckDispose(resp)
        ProcedureReturn
    EndIf

    Debug "response status code = " + Str(CkHttpResponse::ckStatusCode(resp))
    Debug "response body:"
    Debug CkHttpResponse::ckBodyStr(resp)


    CkStringBuilder::ckDispose(sbStringToSign)
    CkJsonObject::ckDispose(json)
    CkDateTime::ckDispose(dt)
    CkCrypt2::ckDispose(crypt)
    CkHttp::ckDispose(http)
    CkJsonObject::ckDispose(queryParams)
    CkHttpResponse::ckDispose(resp)


    ProcedureReturn
EndProcedure