SocrateCloud API Overview

The SocrateCloud API is designated to allow SocrateCloud Partners to develop their own applications for accessing data within SocrateCloud platform.

SocrateCloud API Does

The SocrateCloud API expose SocrateCloud data with some business logic to your applications and you, in turn, can add, modify or delete this data from your applications.

The entire SocrateCloud security policy is automatically applied.

SocrateCloud API Does Not Do

The SocrateCloud API will not allow you to extend or modify the existing features of web interfaces, or to modify the incorporated business logic.

Prerequisites

The SocrateCloud API is aligned to the standard application-to-application interface. To use it requires a good knowledge of using API's, RESTful principles and practices, and a wide programming experience.

We also recommend to pass the technical training for SocrateCloud platform.

In order to interact with SocrateCloud API, you need:

• a valid Tenant 

• a valid User, with a valid role assigned (Administrators have access to the API by default)

  • a valid SocrateCloud Subscription

  • one (minimum) defined Price List with:

    • Active = Yes;

    • Default = Yes;

    • Currency = same currency as on default accounting schema of Tenant;

    • Sales Price List = Yes;

    • one (minimum) Version.

Securities

1. Supported protocols

   • TLS 1.2

2. Cipher Available

   • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256

   • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256

   • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA

   • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA

   • TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256

   • TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256

   • TLS_ECDH_anon_WITH_AES_128_CBC_SHA

   • TLS_ECDH_ECDSA_WITH_NULL_SHA

   • TLS_ECDH_RSA_WITH_NULL_SHA

   • TLS_ECDH_anon_WITH_NULL_SHA

   • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

   • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

   • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

   • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

   • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

   • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

   • TLS_ECDHE_ECDSA_WITH_NULL_SHA

   • TLS_ECDHE_RSA_WITH_NULL_SHA

3. Handshake Unavailable

   • Android 2.3.7

   • IE 6 / XP

   • IE 8 / XP

   • Java 6

   • OpenSSL 0.9.8y

   • Windows 98

   • Windows XP

   • Windows 2000

   • Windows Vista

Concurrency restriction

Starting from 1 January 2023, all API calls will be restricted to only one active call per IP address and endpoint. A second call in parallel for the same IP / endpoint will be rejected with 429 HTTP status.

Rate limiting

The SocrateCloud API is enforces rate limiting. This means that only a certain number of requests are allowed per minute depending. BITSoftware reserves the right to adjust the rate limits at any time to provide a high quality of service for all clients. If a client repeatedly exceeds the rate limits, or engages in behavior that is deemed to be suspicious - BITSoftware reserves the right to temporarily or permanently suspend the API key of the requests.

Fair use

The user is expected to interact with the SocrateCloud API using the functionality described in this document. We reserve the right to temporarily suspend API access, or perform any other actions we deem to be necessary, if a user interacts with the SocrateCloud API or SocrateCloud web application in ways that are not described in this document or that we judge to be harmful. Including, but not limited to: repeatedly exceeding rate limits or scripting calls to endpoints not described in this document.

Users that are suspected of violating the above will be contacted through their assigned SocrateCloud account manager.

General rules

• The elements written with red font on this site are currently under development.

• All filter parameters for GET operations are sent by query parameters in the URL. For example, to list only Business Partners which are employees: 

  • • https://api.socratecloud.com/webapi/rest/bpartner/full/list/0?startRow={0}&endRow={100}&accessToken={access_token}&IsEmployee=true

• In POST operations, products and business partners are sent by Value (key). All other entities by Name.

• In POST operation, all entities sent must be Active!

• For all GET operations (list), you can specify thru query parameters the sort options, using OrderBy parameter. Example:  

  • https://api.socratecloud.com/webapi/rest/product/list/0?accessToken=....&OrderBy=Name,ProductType%20DESC

  • you can specify all fields as you need, separated by coma;

  • for descending order use DESC after the field that you want to sort in descending order, separated by one space;

  • if something is misspelling the system will return an error;

  • if the specified field does not exist in the available list columns, then the system will return an empty resultset;

  • not all the fields are available for sort order - is the case of calculated fields like: QtyOnHand, QtyAvailable, ListPrice, StdPrice, etc.

• Date filter parameters for GET operations (list) can be used to filter on a specific date or a date range.

• The format for the date filter can be one of the following:

  • Fix date: DateParameterName=YYYY-MM-DD HH:MI:SSZ

Example for fix date 2014-01-06 00:00:00+0000:

• https://api.socratecloud.com/webapi/rest/internal_material_receipt/list/0?accessToken=....&MovementDate=2014-01-06%2000:00:00%2B0000

• • Interval: DateParameterName=YYYY-MM-DD HH:MI:SSZ,YYYY-MM-DD HH:MI:SSZ 

Example for interval 2014-01-06 00:00:00+0000 until 2014-01-15 00:00:00+0000:

• • • https://api.socratecloud.com/webapi/rest/internal_material_receipt/list/0?accessToken=....&MovementDate=2014-01-06%2000:00:00%2B0000,2014-01-15%2000:00:00%2B0000

  • Until date inclusive: DateParameterName=<=YYYY-MM-DD HH:MI:SSZ or DateParameterName=,YYYY-MM-DD HH:MI:SSZ

    • The second format is actually the interval format without specifying the start date.

Example for until date 2014-01-06 00:00:00+0000 using the <= operator:

• • • https://api.socratecloud.com/webapi/rest/internal_material_receipt/list/0?accessToken=....&MovementDate=%3C%3D2014-01-06%2000%3A00%3A00%2B0000

Example for until date 2014-01-06 00:00:00+0000 using the interval format without specifying the start date:

• • • https://api.socratecloud.com/webapi/rest/internal_material_receipt/list/0?accessToken=....&MovementDate=%2C2014-01-06%2000%3A00%3A00%2B0000

  • From date inclusive: DateParameterName=>=YYYY-MM-DD HH:MI:SSZ or DateParameterName=YYYY-MM-DD HH:MI:SSZ,

    • • The second format is actually the interval format without specifying the end date.

Example for from date 2014-01-06 00:00:00+0000 using the >= operator:

• • • • https://api.socratecloud.com/webapi/rest/internal_material_receipt/list/0?accessToken=....&MovementDate=%3E%3D2014-01-06%2000%3A00%3A00%2B0000 

Example for from date 2014-01-06 00:00:00+0000 using the interval format without specifying the end date:

• • • • https://api.socratecloud.com/webapi/rest/internal_material_receipt/list/0?accessToken=....&MovementDate=2014-01-06%2000%3A00%3A00%2B0000%2C

  • Until date exclusive: DateParameterName=<YYYY-MM-DD HH:MI:SSZ

Example for until date 2014-01-06 00:00:00+0000:

• • • • https://api.socratecloud.com/webapi/rest/internal_material_receipt/list/0?accessToken=....&MovementDate=%3C2014-01-06%2000%3A00%3A00%2B0000

  • From date exclusive: DateParameterName=>YYYY-MM-DD HH:MI:SSZ

Example for until date 2014-01-06 00:00:00+0000:

• • • • https://api.socratecloud.com/webapi/rest/internal_material_receipt/list/0?accessToken=....&MovementDate=%3E2014-01-06%2000%3A00%3A00%2B0000

Examples:

A few examples of what your applications can do with SocrateCloud API:

• • create and sync documents;

  • print documents;

  • create and sync projects;

  • create and sync tasks and time spent;

  • create and sync requests;

  • create and sync entities used for all above, as Users, Organizations, Business Partners, Products etc;

  • ask for some reports.