Autenticación

Every API request has to be authenticated to ensure the user has access to the recuested resource. Client application authentication is done by adding some parameters to the call URL.

If you tried a request without authentication like this:

GET /companies HTTP/1.1
Host: www.hoshinplan.com

The server response would be something like:

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Connection: Keep-Alive
Content-Length: 8603
...

For our operations to work you have to provide the following parameters:

app_key

The client application key generated when creating the client application.

timestamp

The current date and time in ISO 8601 format at the moment of the API call. Don't reuse API calls since signatures expire in 5 minutes.

signature

The hash-based message authentication code (MAC) for this request using HMAC-SHA256 algorithm. To compute the value for this parameter the whole request string before adding the signature parameter has to be used. For the previuous example could be:

/companies?app_key=test_application&timestamp=2024-11-21T08:31:12+00:00

This is the value that has to be used to calculate the MAC using the secret generated when creating the client application.

For example to generate the signature you could use the following Ruby code:

Base64.encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::Digest.new('sha256'), secret, data)).strip()

For this code to work you have to require openssl and base64 in your class:

require 'openssl'
require 'base64'

Be sure to URL encode the parameter values. Adding the above parameters, the call from the example would end up being (we have added line breaks between parameters to improve readability but they should not be included):

GET /companies?
            app_key=bb39caab63c3dd6524bcaa61ec4f3b4c&
            timestamp=2024-11-21T08%3A31%3A12%2B00%3A00&
            signature=x7/8VfSlr0DlSJ+N4xBEaL1+IwtmeunasI+hYtiDjd8= HTTP/1.1
Host: www.hoshinplan.com