Logo Sitagri

Sitagri API: documentation

This guide is designed to help you connect to FinanceAgri's API and exploit the data extraction.

The API is RESTful and communicates over HTTP (and websockets). The responses bodies are formatted as JSON.

All examples will require basic knowledge of linux as well as the following programs:

On a Debian-based system you can install them with the following commands (for npm install you need to have Node installed, see how):

root@computer:~# apt-get install curl jq
root@computer:~# npm install -g wscat

Please ensure cURL supports gzip too:

user@computer:~$ curl -V | grep libz -o >/dev/null && echo "OK" || echo "FAIL"

Table of Contents

For market data documentation please see Sitagri API documentation - market data.

Requirements

Programming language

You can use any programming language you want as long as it allows you to make HTTP requests, use websockets (mandatory only if you want to receive prices or news by push) and parse JSON. All responses can be gzipped so you must support that too.

Network

The API requests are using HTTP(s) custom headers (prefixed with X-) to transfer tokens. If you are connected to the internet behind a proxy server, please ensure the proxy does not strip the custom headers from the requests.

Should you use an old version of nodejs (which embeds the CAs) or an old server that does not recognize our SSL certificate, you can download the CA's cross-signed intermediate certificate here: https://www.gandi.net/static/CAs/GandiStandardSSLCA2.pem.

Any HTTP client should support TLS 1.2+. Although the current API might support versions below TLS 1.2 this is subject to change without notice, to ensure security.

⚠️ All HTTP requests should be made with HTTP 1.1 as minimal versions. Any requests using a version below that might be refused in the future.

Get your credentials

Get your application token

The application token will be referenced as APP-TOKEN in this documentation.

NOTICE:

If not provided, the application token is 8998751E-B8B6-4C6E-BFBD-155394B1A7A8.

Get your GUID token

This GUID (Globally Unique Identifier) is provided by your contact at FinanceAgri. It should be similar to 86FD4502-7E02-D93A-0B5E-E2A743F2C127. Henceforth, it will be referred to as YOUR-GUID-TOKEN.

Get your user credentials

This is used internally to authenticate the FinanceAgri's customers.

Log in

Open a session

Send a POST request to https://login.financeagri.com/login/APP-TOKEN with the following headers:

and the following body:

{"thirdApp": "YOUR-GUID-TOKEN"}

Notice: Do not replace the thirdApp key, only its value !

If you are using user credentials instead of a GUID token, the following body will be used:

{"login":"LOGIN", "password": "PASSWORD"}

Notice:

In order to be able to decode the gzipped response with curl, we will use the --compressed parameter.

Though this makes the Accept-Encoding header redundant, for the purpose of this tutorial it shall be maintained.

Example with 46FE2143-C2BA-10E5-876C-FAC09809071D as GUID token:

The following request:

user@computer:~$ curl -X POST "https://login.financeagri.com/login/8998751E-B8B6-4C6E-BFBD-155394B1A7A8" \
-H "Accept: application/json, text/*;q=0.2" \
-H "Accept-Charset: utf-8" \
-H "Accept-Encoding: gzip, deflate" \
-H "Content-Type: application/json" \
-d '{"thirdApp": "46FE2143-C2BA-10E5-876C-FAC09809071D"}' \
--compressed

should return a content similar to this:

{
  "command": "login",
  "status": "ok",
  "data": {
    "token": "85045E8E-CE68-2956-9E11-96F51837C71B",
    "application": "8998751E-B8B6-4C6E-BFBD-155394B1A7A8",
    "clientIPAddress": "127.0.0.1",
    "creationTimestamp": 1453992494,
    "sessionTimeout": 900,
    "account": {
      "thirdAppGuid": "46FE2143-C2BA-10E5-876C-FAC09809071D",
      "thirdAppName": "API Tutorial"
    },
    "accessRights": {
      "application": {
        "authType": "none",
        "maxSimultaneousSessions": 1,
        "maxConfigurations": 1,
        "restrictedIPAddresses": ["127.0.0.1"],
        "startTimestamp": 1433862618,
        "endTimestamp": 1528622627,
        "readOnlyConfig": false
      },
      "services": {
        "AgriMarketService": {
          "url": "http://market.financeagri.com",
          "accessRights": {
            "marketRights": {
              "ECBOT": "REALTIME",
              "EURONEX": "REALTIME"
            },
            "newsRights": {
              "AFP": "SEARCH",
              "SITALERT": "SEARCH",
              "SITCEREALS": "SEARCH",
              "SITCFTC": "SEARCH",
              "SITENERGY": "SEARCH",
              "SITFOREX": "SEARCH",
              "SITMORNBRIEF": "SEARCH",
              "SITOLEAG": "SEARCH",
              "SITTENDERS": "SEARCH",
              "SITUSDA": "SEARCH"
            }
          }
        }
      }
    }
  }
}

However, had the session failed to be created then the result would be:

{
  "command": "login",
  "status": "error"
}

Other error status messages include:

Notice:

In case of maxQuotaReached error, the data field is an array of objects with two keys: the IP address which opened the session, and the associated token. As there is no way to close a remote session (a session opened with a different IP than your current one), please ensure to logout, or you will have to wait for the session to expire by itself.

Extract the session parameters

From the JSON received, extract:

Notice:

You can output the previous request response to session.json by appending -o session.json and then use jq to parse it.

user@computer:~$ cat session.json | jq ".data | {token: .token, timeout: .sessionTimeout, url: .accessRights.services.AgriMarketService.url}"

which will output:

{
 "url": "https://market.financeagri.com",
 "timeout": 900,
 "token": "85045E8E-CE68-2956-9E11-96F51837C71B"
}

Retrieve the current session

If you need information from your current session and you only kept the token from your initial request, you can retrieve it with a request to https://login.financeagri.com/session with the following headers:

Example:

user@computer:~$ curl "https://login.financeagri.com/session" \
-H "Accept: application/json, text/*;q=0.2" \
-H "Accept-Charset: utf-8" \
-H "Accept-Encoding: gzip, deflate" \
-H "Access-Control-Request-Headers: x-session-token" \
-H "X-Session-Token: 85045E8E-CE68-2956-9E11-96F51837C71B" \
--compressed

Keep the login session alive

On a regular basis, before the session's timeout delay (data.sessionTimeout), send a keep-alive request to https://login.financeagri.com/keepAlive with the following headers:

Example: if data.sessionTimeout equals 900 you should send a keep-alive request every 800 seconds (a 100s threshold is used here).

Example:

user@computer:~$ curl "https://login.financeagri.com/keepAlive" \
-H "Accept: application/json, text/*;q=0.2" \
-H "Accept-Charset: utf-8" \
-H "Accept-Encoding: gzip, deflate" \
-H "Access-Control-Request-Headers: x-session-token" \
-H "X-Session-Token: 85045E8E-CE68-2956-9E11-96F51837C71B" \
--compressed

Change your password

This part is not documented yet.

Log out

Send a GET request to https://login.financeagri.com/logout.

Example:

$ curl "https://login.financeagri.com/logout" \
-H "Access-Control-Request-Headers: x-session-token" \
-H "X-Session-Token: 85045E8E-CE68-2956-9E11-96F51837C71B" \

You can check the request status with the response body:

{"command":"logout","status":"ok"}

Notice:

Remember to stop sending keepalive requests.