SELLSATION API

1. General

2. Authentication

3. Localization

4. URLs

5. Testing API Methods with Swagger

1. General

In this article you will find the prerequisite information (e.g. authentication) for working with the SELLSATION API. The documentation itself can be viewed in SWAGGER (see link below in the article).

The API is only accessible via HTTPS.

2. Authentication

Authentication is performed via API key through the SELLSATION OAuth2.0 Identity-Server.
It is accessible via the Url https://auth.sellsation.com.

To access the API, a Bearer Token is required. This is provided in JWT format.

Endpoint to obtain the token:

• Uri: https://auth.sellsation.com/connect/token
• Method: POST
• Headers
  • Accept : application/json
  • Content-Type : application/x-www-form-urlencoded
• Body
  • grant_type : client_credentials
  • client_id : sellsation.public
  • client_secret : [API key of the tenant] - can be retrieved via the web application in the administration
  • scope:
    • sellsation.api.public : read access
    • sellsation.api.public.write : write access
    • sellsation.api.public.admin.write: write access to admin areas (custom fields, product categories)

Important regarding the scope: depending on the required access, scopes must be combined and separated by spaces, for example:

sellsation.api.public sellsation.api.public.write sellsation.api.public.admin.write

Currently, there is no differentiation of the API key between the scopes. This may change in the future (e.g. one API key per scope).

The token received is valid for one hour and can be used to access the API.

3. Localization

All localizations implemented in SELLSATION are also applied in the API. The language used is defined via the Accept-Language header. The following languages are currently supported:

• German - de (default language)
• English - en

If no translation is available, the default language is always used for display.

4. URLs

Identity Server: https://auth.sellsation.com/

Identity Server - Token Endpoint: https://auth.sellsation.com/connect/token

5. Testing API Methods with Swagger

At the following link you will find our Swagger documentation:

API Documentation (Swagger)

Here you can test your requests against your SELLSATION tenant. Please note that our security concept requires you to obtain a Bearer Token as described above. Copy this Bearer Token into the field (described as API Key) in the following way:

"Bearer <Token>"

Please replace <Token> with the string you received from the authentication service:

6. Webhooks

Sellsation can notify other systems of data changes via HTTP. The following entities are supported:

• Projects
• Customers
• Contacts

The system to be notified must provide a public REST interface that Sellsation can call. To activate the webhook, please contact us and provide the URL of the interface.

The following data is sent to the interface when changes occur:

POST <Url>
Example body:

{
"NotificationType":"Updated",
"TenantId":123,
"Entity":"Customer",
"EntityId":123,
"ParentEntity":null,
"ParentEntityId":null,
"Initiator":"PublicApi"
}

The body follows the following JSON schema:

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"NotificationType": {
"type": "string",
"enum": ["Updated", "Created", "Deleted"]
},
"TenantId": {
"type": "integer"
},
"Entity": {
"type": "string",
"enum": ["Project", "Customer", "ContactPerson"]
},
"EntityId": {
"type": "integer"
},
"ParentEntity": {
"type": ["string", "null"],
"enum": ["Project", "Customer", null]
},
"ParentEntityId": {
"type": ["integer", "null"]
},
"Initiator": {
"type": "string"
}
},
"required": [
"NotificationType",
"TenantId",
"Entity",
"EntityId",
"Initiator"
]
}