SD03269S/00/EN/01.24-00
71658043
2024-07-19

ProductsSolutions

Services

Special Documentation
SupplyCare Hosting API
Brief description of the API (Application ProgrammingInterface) of the software application SupplyCare Hostingfor the synchronization with third-party clients.

SupplyCare Hosting API

Table of contents

Table of contents
1

Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4

2

Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43General comments . . . . . . . . . . . . . . . . . . 5

3.1
3.2
3.3
3.4
3.5
3.6
3.7
3.83.93.10RESTful API . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Data format and encoding . . . . . . . . . . . . . . . . 5API Versioning . . . . . . . . . . . . . . . . . . . . . . . . 5
Header parameters . . . . . . . . . . . . . . . . . . . . . 5
Throttling of requests (Rate Limiting) . . . . . . . . 6
Response compression . . . . . . . . . . . . . . . . . . . 6Pagination and sorting . . . . . . . . . . . . . . . . . . . 6Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Swagger UI . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.1
4.2
4.3

Authentication and Authorization . . . . . . . . . . 7
API calls with access token . . . . . . . . . . . . . . . . 9API response codes . . . . . . . . . . . . . . . . . . . . 10

5Measuring values . . . . . . . . . . . . . . . . . 11

5.1

Current measuring values . . . . . . . . . . . . . . . . 116Master data . . . . . . . . . . . . . . . . . . . . . . . 12

6.1
6.2
6.3

Tanks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Endress+Hauser

3Introduction

SupplyCare Hosting API

1

Introduction

SupplyCare Hosting is a cloud-hosted software for inventory monitoring and supply chain
management. Main purpose of the software is to collect, consolidate and visualize
inventory data of tanks, silos and containers. The collected and processed inventory data
include the inventory, demands, delivieries and consumption. It is a scalable solution from
simple onsite monitoring up to complex supply chain management worldwide. Todays
supply chains often require synchronization between different systems (i.e. ERP) andtherefore SupplyCare offers a comprehensive API.

2ScopeThe scope of this document is to present a brief description and examples of theSupplyCare API services and the mechanisms by which a third-party client application and
SupplyCare may exchange data.
The presented services will be:• Measurement values• Master data
In this document the main workflows of the interface are described as well as how to finddetailed information on exchangeable data fields and technical definitions.

4

Endress+Hauser

SupplyCare Hosting API

General comments

3General comments

SupplyCareAPI

https

ClientApplication

SupplyCare API user
A0054025

1

Client application accessing to SupplyCare API

3.1

RESTful API

SupplyCare API services are based on HTTP REST and therefore the standard methods such
as GET, POST, PUT, PATCH and DELETE are used.

3.2

Encryption

For security reasons any request to the API must be done encrypted via HTTPS. For
compatibility reasons the API supports TLS versions from 1.2 on. We always recommendthat third-party clients keep themselves up to date to the latest version for security
reasons, but also to avoid any inconveniences when the supported TLS versions on API side
may be updated.

3.3

Data format and encoding

The data serialization format used for any request to the API or responses from the API isJSON. The character encoding used for requests and responses is UTF-8. Timestamps arealways provided in ISO 8601 format with reference to the UTC timezone. Generated texts
that occur in responses like error messages are always displayed in English language.

3.4

API Versioning

The API uses a versioning mechanism to prevent incompatibility with third-party client
applications that might be caused by future changes on SupplyCare API. The major version
number is integrated as part of the URL path: …/api/external/v1/…

3.5

Header parameters

To access to the API, each request header must contain the following parameters:Parameter name Description

Endress+Hauser

X-Tenant-Id

Must contain the “contract id” on which the request is triggered. This “contract id” can beobtained by the Endress+Hauser support.

Acceptapplication/json

Authorization

Bearer with the access token string (For details refer to "Authentication and Authorization”)

5General comments

SupplyCare Hosting API

3.6

Throttling of requests (Rate Limiting)

The number of requests to the API is limited for security reasons.
When the maximum limit is reached, the API will return the specific return code 429 Toomany requests.

3.7

Response compressionThe responses are compressed on server-side with “gzip” to reduce the amount of datatransferred.

3.8

Pagination and sorting

For responses containing collections of results, the API will use a mechanism to return
only a subset of the results. The client application can configure the maximum size of a
response page via query parameters inside the URL. The query parameter “size” will limit
the number of items inside the page. The query parameter “page” will allow to navigate
between the pages.
GET /assets?page=3&size=50
Default value for “size” is 20 (maximum 1 000).
The API also offers the possibility to sort items returned to the client application. Sorting is
supported via another query parameter “sort”.
GET /assets?sort= name,desc
Below a description of returned parameters that can be found inside the paged responses:
Returned parameter

Description

firstBoolean. For response containing the first resource element

last

Boolean. For response containing the last resource element

totalElements

Integer. Total number of available resource elements

totalPages

Integer. Total number of available pages

numberOfElements

Integer. Number of the resource elements in this response

numberInteger. Index of requested page, 0-based

sizeInteger. Number of the requested resource elements per response

3.9Filtering

The API offers the possibility to filter items. The filter parameters can be appended to therequest URL via query parameters.

3.10

Swagger UIThe SupplyCare API provides a swagger UI under following path:<SupplyCare root>/swagger-ui/index.html?urls.primaryName=External

6

Endress+Hauser

SupplyCare Hosting API

Access4Access

4.1

Authentication and Authorization

To access the SupplyCare API, for each call, a valid access token must be sent as bearer
token using the “Authorization” request header. To obtain this token, the OAuth2
Resource Owner Password Flow is implemented.
To obtain an API user, please contact Endress+Hauser support. It must be noted that foreach API user a valid e-mail address is required.
Initial password reset:
Initial credentials for the API will be received via the e-mail address defined for the user.
For security purposes, the initial password received by e-mail must be reset to a new one
before accessing to the API.
The initial password reset must be done via the SupplyCare GUI.
1.

Log in with e-mail address into SupplyCare GUI via your favorite web browser:
https://inventory.endress.com

2.

System will ask for entering a new password.

After getting the confirmation that the password has been changed, you can leave the webbrowser again.
Initial acquisition of access token:
To obtain an access token, a request to the authorization server instance must be done.
Designation

Description

Authorization
serverA POST request must be sent to following URL:
https://myendress.b2clogin.com/myendress.onmicrosoft.com/B2C_1A_CROPC/oauth2/
v2.0/token

HeaderFollowing header element must be set:Content-Type: application/x-www-form-urlencoded

Body

grant_type=password
client_id=0876b4ab-d587-4a92-9692-b3613080f511
scope=openid offline_access 0876b4ab-d587-4a92-9692-b3613080f511
username=<your username>password=<your password in clear text>

The response of the authorization server is of type application/json and will containfollowing elements:
Designation

Description

access_token

Contains the valid access token for future request to the SupplyCare API.

token_type“Bearer”

expires_in“3 600”, value is in seconds.

refresh_token

Contains the valid refresh token to request new access token after expiration.

Acquisition of access after expiration:
An access token is typically valid for a short period of time, usually one hour. To acquire a
new access token without sending the password again, it is strongly recommended to use
the refresh token that was received alongside with the access token in the initial request

Endress+Hauser

7

Access

SupplyCare Hosting API

which has a longer validity, e.g. 14 days. The following example is how the request lookslike:
Designation

Description

Authorization
serverA POST request must be sent to following URL:
https://myendress.b2clogin.com/myendress.onmicrosoft.com/B2C_1A_CROPC/oauth2/
v2.0/token

HeaderFollowing header element must be set:Content-Type: application/x-www-form-urlencoded

Body

grant_type=refresh_token
client_id=0876b4ab-d587-4a92-9692-b3613080f511
scope=openid offline_access 0876b4ab-d587-4a92-9692-b3613080f511
refresh_token=<the valid refresh token for your user>

The response of the authorization server is of type application/json and will containfollowing elements:
Designation

Description

access_token

Contain the valid access token for further requests to the SupplyCare API.

token_type“Bearer”

expires_in“3 600”, value is in seconds.

refresh_token

Contain a new refresh token.

refresh_token_expires_in“1 209 600”, value is in seconds.

When the token has expired SupplyCare API will respond with return code “401 –Unauthorized”.
Change password:
The password for an API user can be changed at any time if required by using theSupplyCare GUI.

81.

Log in with e-mail address into SupplyCare GUI via your favorite web browser: https://inventory.endress.com

2.

Click on “Forgotten your password”.

3.

System will send via the user configured e-mail address a verification code.

4.

Verification code must be entered in the SupplyCare login web page.

5.

Click on verify.

6.

System will ask for entering a new password. Click on “continue” to enter SupplyCareGUI.

Endress+Hauser

SupplyCare Hosting API

Access4.2

API calls with access token

The client application can access the SupplyCare API via following root URL:
Designation

Description

SupplyCare API

Root URL to access SupplyCare API:
https://supplycare.endress.com/SupplyCareServices/api/external/v1/

HeaderFollowing header elements must be set:
X-Tenant-Id: <SupplyCare contract id>
Accept: application/json
Authorization: Bearer <the access token value>

The contract id for SupplyCare can be obtained by contacting Endress+Hauser support.

Workflow access token

Web Client
application

Authorization
server

SupplyCareAPI

Authenticate with user credentials+ client ID
Validate
credentials
Deliver access token

Request data with token
ResponseA0054032

Endress+Hauser

9Access

SupplyCare Hosting API

4.3

API response codes

The application may return following return codes:

10Return code

Significations

200

OK: Response to a successful GET, PUT, PATCH or DELETE. Can also be used for a POST that
doesn't result in a creation.

201

Created: response to a POST that results in a creation.

202

Accepted: the request has been accepted but the action behind it is not yet completed, e.g. used
for asynchronous processing.

204

No Content: response to a successful request that won't be returning a payload.

304

Not Modified: used when HTTP caching headers are in use.

400

Bad Request: the request is malformed. A detailed error message should be returned in thepayload.

401

Unauthorized: when no or invalid authentication details are provided.

403

Forbidden: when authentication succeeded but authenticated user doesn't have access to theresource, or the action is for other reasons not allowed.

404

Not found: when a non-existent resource or an unknown path is requested. Can also happen incase a feature toggle for a certain endpoint is disabled, e.g.: because of licensing.

405

Method Not Allowed: when the used HTTP method isn't allowed for the requested resource.

410

Gone: indicates that the resource at this endpoint is no longer available, e.g.: because of a nolonger supported API version.

415

Unsupported Media Type: If an invalid or non-supported content type was provided as part of
the request.

429

Too many requests: when a request is rejected due to rate limiting

Endress+Hauser

SupplyCare Hosting API

Measuring values

5

Measuring values

5.1

Current measuring values

SupplyCare API enables you to manage the current values 1) from tanks.
Following use cases are supported:
Read current values
Details regarding supported services and their respective parameters can be found under
the following swagger-ui url:
https://supplycare.endress.com/SupplyCareServices/swagger-ui/index.html#/tankvalues
Details on parameter definition can be found on the page described above, inside the"schema" section.
When executing search queries, the following query parameters can be used to filter
results in order to improve the efficiency of the expected response.
Filters table:1)

DesignationDescription

nameFilter tanks by name (partial search, case insensitive)

exactName

Filter tanks by name (Equals, case sensitive)

location.name

Filter tanks by tank location name (partial search, case insensitive)

type.name

Filter tanks by tank type name (partial search, case insensitive)

product.name

Filter tanks by product name (partial search, case insensitive)

buyer.name

Filter tanks by buyer company name (partial search, case insensitive)

seller.name

Filter tanks by seller company name (partial search, case insensitive)

description

Filter tanks by description (partial search, case insensitive)

additionalData1Filter tanks by Data 1 (partial search, case insensitive)

additionalData2

Filter tanks by Data 2 (partial search, case insensitive)

additionalData3

Filter tanks by Data 3 (partial search, case insensitive)

Read current values of an existing tankEndress+Hauser

11Master data

SupplyCare Hosting API

6

Master data

6.1

Tanks

SupplyCare API enables you to manage tanks, including their respective details.
Following use cases are supported for tanks:• Create a new tank
• Read details about existing tanks• Update an existing tank
• Delete a tank
Details regarding supported services and their respective parameters can be found under
the following swagger-ui url:
https://supplycare.endress.com/SupplyCareServices/swagger-ui/index.html#/tanks
Details on parameter definition can be found on the page described above, inside the"schema" section.
When executing search queries, the following query parameters can be used to filter
results in order to improve the efficiency of the expected response.
Filters table:
Designation

Description

nameFilter tanks by name (partial search, case insensitive)

exactName

Filter tanks by name (Equals, case sensitive)

location.name

Filter tanks by tank location name (partial search, case insensitive)

type.name

Filter tanks by tank type name (partial search, case insensitive)

product.name

Filter tanks by product name (partial search, case insensitive)

buyer.name

Filter tanks by buyer company name (partial search, case insensitive)

seller.name

Filter tanks by seller company name (partial search, case insensitive)

description

Filter tanks by description (partial search, case insensitive)

additionalData1

Filter tanks by Data 1 (partial search, case insensitive)

additionalData2

Filter tanks by Data 2 (partial search, case insensitive)

additionalData3

Filter tanks by Data 3 (partial search, case insensitive)

6.2

Products

The SupplyCare API enables you to manage products, including their respective details.
Following use cases are supported for products:• Create a new product• Read details about existing products• Update an existing product• Delete a productDetails regarding supported services and their respective parameters can be found under
the following swagger-ui url:
https://supplycare.endress.com/SupplyCareServices/swagger-ui/index.html#/products
Details on parameter definition can be found on the page described above, inside the"schema" section.
When executing search queries, the following query parameters can be used to filter
results in order to improve the efficiency of the expected response.

12Endress+Hauser

SupplyCare Hosting API

Master data

Filters table:
Designation

Description

nameFilter products by name (partial search, case insensitive)

exactName

Filter products by name (Equals, case sensitive)

identifierFilter products by identifier number (Equals, case sensitive)

identifierAgency

Filter products by identifier agency (Equals, case sensitive)

consistency

Filter products by consistency (Equals; supported one of following choices: LIQUID,SOLID, UNKNOWN)

6.3

Locations

SupplyCare API enables you to manage locations, including their respective details.
Following use cases are supported for locations:• Create a new location• Read details about existing locations• Update an existing location• Delete a location
Details regarding supported services and their respective parameters can be found under
the following swagger-ui url:
https://supplycare.endress.com/SupplyCareServices/swagger-ui/index.html#/locations
Details on parameter definition can be found on the page described above, inside the"schema" section.
When executing search queries, the following query parameters can be used to filter
results in order to improve the efficiency of the expected response.
Filters table:

Endress+Hauser

Designation

Description

nameFilter products by name (partial search, case insensitive)

exactName

Filter locations by name (Equals, case sensitive)13

*71658043*
71658043

www.addresses.endress.com