Overview¶

Getting started with our API is straight-forward using the guide below.

Terminology¶

Prerequisites¶

• A trading agreement with Siemens Financial Services (SFS) - contact us to get this
• A signed End-User License Agreement (EULA) that covers our API connection
• Credentials (client ID and secret)

Differences between production and test APIs¶

The production version of the API provides access to real data. The system (SieSmart) is also connected to live applications such as credit search engines. The test environment is where you can develop your applications before you are ready to promote them to production. Config items, for example pricelist IDs, are consistent across the test and production environments.

The test environment is subject to regular database refreshes, therefore any data you have sent is liable to be periodically deleted.

Promoting your connection to production¶

Production API credentials are only provided by SFS after we are satisfied that your application is working correctly in the test environment. This will include (but not limited to) verifying that proposals you have sent have all the correct information. There is no limit to the amount of tests you are allowed to perform.

When everything is in order, the production credentials will be generated and sent to you.

Security considerations¶

Security is an important aspect. This API is developed by using well-tested and widely adopted security schemes. The Access Token are sent in the header of the request. All the communication between the API and client is secured by TLS, which encrypts the traffic. When developing an application, it is important to keep the credentials and tokens safe and handle them carefully. If you believe your credentials have been compromised please contact SFS immediately.

HTTP Response codes¶

SFS uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, the token has expired, etc.). Codes in the 5xx range indicate an error with our servers.

General responses to API requests

POST request precondition¶

For any modifying calls (POST, PUT, PATCH, DELETE) there is a mandatory If-Match request header. The purpose of this is to make sure you are modifying the most recent version of the proposal. This header is a string that represents a date time object.

The value for this can be retrieved from the ETag response header from the initial proposal creation, or by making a GET request to the proposal endpoint.

Here is an example of where you can capture your ETag when testing in Postman:

Request IDs¶

Each API request has an associated request identifier. You can find this value in the response headers, under X-B2B-TRACE-ID. You can also find request identifiers in the Error object of unsuccessful requests. If you provide this request identifier when contacting SFS it will allow us to debug and help you as quickly as possible.

Rate limiting¶

There is a limit of 100 requests per minute, enforced at the connecting IP address level. If you reach this limit you will receive an HTTP 429 Too Many Requests response status code. If your request rate falls below this limit then the block will be automatically removed.

Connecting to the API¶

To be able to connect to our API, there are a few requirements:

• Client ID
• Client Secret
• Access token (generate a token)

If you do not have your Client ID and Client Secret, please contact us.

The generated token is valid for 12 hours and must be sent in the header of every request.

Once you are connected successfully, there are a number of config endpoints that will help you get started.

Configuration