Skip to content

Overview

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

Terminology

TermMeaning
Access tokenA token is retrieved by the Client after a successful access authorization flow. The access token is used by the API to authenticate Clients. The access token does not contain any information that the Client (or client's application) can use.
SieSmartThe backend system to which the API connects.
IntroducerCollective name for you as the user, representing either a broker or vendor.

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

StatusMeaningDescriptionSchema
200OKThe request has been successfulDependent on request
401UnauthorizedThe auth token is invalid or not presentError
403ForbiddenThe requested operation is not authorized for your tokenError
412Precondition failedFor POST requests, the 'If-Match' header is missingError
429Too Many RequestsThe request rate limit has been reachedError
500Internal server errorInternal server errorError
503Service unavailableService unavailableError

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:

ETag Upload

Hint

  • The If-Match request header is not needed for the initial proposal creation call

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:

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