General Definition
The specific format of the data exchanged, whether using asynchronous or synchronous, and using staging or not, is all implemented in Application Programming Interfaces.
While these are designed in such a way to be automatically used by other software, some documentation is still needed in order to be understood by the developers and system integrators that design, and implement systems using the API.
The SAP API Business Hub is a web application hosted by SAP to discover, explore, and test SAP and partner APIs (application programming interfaces) that are required to build extensions or process integrations. It also hosts Integration content, Events, CDS views, and more. On SAP API Business Hub you will find various resources you can use to build apps, integrations, and extensions easily. Browse through our content to find the APIs you want, seek out the integration flows that will help you work with different SAP products, and check out workflow content, events, and CDS views.
Specific for SAP BRH
SAP API Business Hub has all the information about the SAP API of SAP BRH, organized according to the communication method used:

As we have seen, in SAP BRH one can integrate both using Asynchronous (EVENTS) or Synchronous (ODATA4) communication methods. The payload is the same.
The Asynchronous or the Synchronous approach in SAP BRH are like two sides of the "same coin". Namely, the information that is exchanged is the same, the difference only being the communication method chosen, or packaging.
The API Business Hub contains the description of each detail of the payload for both communication methods, with also example code to facilitate understanding on how to integrate with other systems.

At the core of SAP BRH is the Batch: a specific Material produced in a specific Plant (or Location), with record information such as when the information was last modified, and if the record is in active or inactive status. This is the meaning of the above figure.
According to needs, the Batch has additional "properties" such as:
- the organizational area used for defining locations in a quality department, for example; production areas, storage locations, or work centers
- the order that triggered the batch creation.
- the type of order that triggered the batch creation
- the quantity
- The date on which the batch expires
- The date on which the batch was released in the source system.
- The name of the supplier associated with externally procured batches.
- …
The full list of properties (mandatory or optional ) is provided in the SAP Business Hub:

In the above figure one can see on the left side the first few lines of the documentation about the Payload for the Asynchronous (EVENTS) interface, while on the right side for the Synchronous (ODATA4) Interface.
Example for Nullable values but mandatory properties
Field name | Type and constraints | Description |
---|---|---|
plant_ID | string max Length: 10 | A unique identifier for the location (plant or customer) of the batch requiring a release decision. |
organizationalArea_code | string maxLength: 10 nullable: true | A unique identifier for an organizational area used for defining locations in a quality department, for example, production areas, storage locations, or work centers. |
It is indispensable to properly understand how to apply the documentation that is provided in the SAP API Hub. Failure in understanding it would cause major delays in the achievement of the goal of integrating with SAP BRH.
Using as example the Batches help page for Synchronous communication (Help Page - Synchronous), here we want to focus the attention on the "type and constraints" column.
In this case, plant_ID and organizationalArea_code are both of type "string".
This means, they must start and end with a double quote sign (") and they must contain content interpretable as plain text. The string does not need to be constrained to characters of the ASCII character set, as long as there can be represented in UTF16. For example, all following languages are supported (list is not comprehensive): Chinese, Hindi, Hebrew, Arabic.
Some payload errors, focusing on "ID"
Input for "ID" of Batch | Error code | Deserialization Error |
---|---|---|
9999450012 | 400 | Invalid value 9999450012 (JavaScript number) for property "ID". A string value must be specified as value for type Edm.String. |
"9999450012blablablablablabla" | 400 | Invalid value 9999450012blablablablablabla (JavaScript string). The length of the Edm.String value must not be greater than the MaxLength facet value (10) |
400 | Unexpected token , in JSON at position 8. | |
null | 400 | Value for 'ID' must not be null. |
The above table shows the reported error messages that are shown by the application when trying to post a payload that contains:
- Only digits but not encapsulated between double quotes. This is interpreted as a Number and it is not appropriate since it should be a string
- Too long string. Maximum length is specified as 10 characters
- Empty. In this case the system is reporting the position in characters from the beginning of the message. The reason for "8" is due to the fact that the message consisted in "{"ID":,…" and therefore the position of the expected beginning of the value is position 8.
- null. In this case, the developer placed a "null" value. There is big difference between an EMPTY value (as in the previous case) and a "null" value.
Other common payload errors
Not providing a mandatory field | Error code | Error description |
---|---|---|
Not providing a mandatory field | 500 | Internal Server Error |
Posting the same entity twice | 400 | Entry already exist |
https protocol name forgotten | 200 | No description |
In the above table, additional common errors are reported with their error code and the description, if available. Surely the hardest of all situations is when either no error message is reported (as for the 200) or a generic error (as for the 500). In both cases is recommended to follow the guidelines described in this document, and carefully inspect the payload content and the methods used for delivering it.
Optional is Not Always Optional
Minimal Batch payload according to the API
12345678
{
"ID": "123466",
"material_ID": "12345M",
"plant_ID": "ABCD",
"status_ID": "A",
"sourceModifiedAt": "2022-11-09T13:36:02.000Z"
}
Minimal required message
12345678910
{
"ID": "123466",
"material_ID": "12345M",
"plant_ID": "ABCD",
"status_ID": "A",
"sourceModifiedBy": "aaa",
"sourceIdentifier": "bbb",
"sourceModifiedAt": "2022-11-09T13:36:02.000Z"
}
SAP BRH is a brand new solution, rapidly evolving. The API Documentation is rapidly improving however it might contain some inconsistencies. For example, in the case of Batches, while avoiding that posting some optional values works properly, for other optional values the system returns a 400 error message with the information that the specific parameter (called "target" ) requires its value to be defined.
The above table shows (by trial and error) which parameters are really required instead of being marked as optional.
The safest way is therefore to always include all parameters in the posting and fill them with the appropriate values, and if optional use null.

Note
- Generate the payload from the source systemCode snippetExpand
{ "ID": "123466", "material_ID": "12345M", "plant_ID": "ABCD", "status_ID": "A", "sourceModifiedBy": "aaa", "sourceIdentifier": "bbb", "sourceModifiedAt": "2022-11-09T13:36:02.000Z" }
- Post to the OData4 and autoactivateCode snippetExpand
curl --header 'Authorization: Bearer {token} ' --request POST --url 'https://{yourtenant}/dso_batches/BatchesStage’ --header 'Accept: application/json’ --header 'Content-Type: application/json’ --header ‘x-sapbrh-autoactivate’ --header 'DataServiceVersion: 2.0’ --data '{ "ID": "123466", "material_ID": "12345M", "plant_ID": "ABCD", "status_ID": "A", "sourceModifiedBy": "aaa", "sourceIdentifier": "bbb", "sourceModifiedAt": "2022-11- 09T13:36:02.000Z" }'
In this example the data coming from a "source system" will have to be extracted and formatted according to the API documentation for Batches: https://api.sap.com/api/BatchesService/resource.
The "$token" is a security value that is described later in this lesson.
There are few important aspects to consider:
- Address: How to find the URL where to send the message ?
- Security: How to ensure that the call will be accepted ?
- Content: How to format the content ?
- Handling the response: How to be sure that the data was accepted by SAP BRH ?
- How to view the data in SAP BRH ?
- What to do if I see nothing in SAP BRH ?
We will address these aspects in the following pages

When your company has subscribed SAP BRH, they will get a "tenant" with the Application URL. That is the base address that needs to be put in the "URL" .
In the online documentation the string "{appName}…..{host}" needs to be substituted with the one provided in your subscription.
This information is known by the BTP Administrator of your BTP Account.
Please note that the only place to find the exact name of the endpoint is in the "Code Snippet" section of the documentation.

Note
- Get a tokenCode snippetExpand
curl --location --request POST 'https://{your authentication url}/oauth/token' --header 'Content-Type: application/x-www-form-urlencoded' --header 'Authorization: Basic base64encoded username:password' --data-urlencode 'grant_type=client_credentials' {"access_token":"…", "token_type":"bearer", "expires_in":12345, "scope":"uaa...APIACCESS", …}
- Use the token in the following callsCode snippetExpand
-- header 'Authorization: Bearer {{token}} {"access_token":"…"token_type":"bearer","expires_in":1234,"scope":"uaa…APIACCESS",…}’
Security is at the foundation of everything in SAP. The way we design software, the way we develop it, the way we test it, the way we deploy it: everywhere we think Security first.
In order to publish data in SAP BRH, you need first to get the credential of the BTP Integration Service from your BTP Administrator.
Those credentials consists in a username and a password. These have to be base64 encoded and then used as value of the $token in the header of the calls.
The output of the authorization request is a OAUTH2 token that then has to be used as value in the header of all subsequent calls.
Please be aware that the "expires_in" information tells that after that period the token will no longer be usable and therefore a new token needs to be requested again.

The single source of truth on the API is the well known API Business HUB, at the previously mentioned addresses.
There you can see not only a formal description of the payload, but also example values.
Additionally, by clicking on the "Try Out" even without adding an "environment" you can then see in the "code snippets" how the program should be written in order to interact with the SAP BRH.
Several source code examples are shown, and also command line (curl).

Hint
Access to the API Business Hub - API Reference (Batches- Staging)Also for this question, the answer is the same as before: look in the API Business Hub. In the bottom of the same page where you have found the description of the payload, is also written the Response.
As we previously described in the general pages about Synchronous Communication, there are 3 messages needed for synchronous communication.
- The payload
- The response in case everything went well
- The response in case of error.
These are all provided in the above page. In this example, if the response of the call is "201" then it means that everything went well, while if the response is 4XX then the response will also contain some additional information to let you understand what went wrong.

There are two approaches to view the data in SAP BRH when it is sent using the Synchronous approach:
- Using the User Interface "Data monitoring" - Manage Staging and Active Data"
- Programmatically by performing a "GET"
In the following screen we show for example how different Batches posted to the Staging area can be seen in the Data Monitoring application. For example purpose, we use also BatchID and MaterialID with different character sets, demonstrating the wide support for many possible cases.

There are two approaches to view the data in SAP BRH when it is sent using the Synchronous approach:
- Using the User Interface "Data monitoring" - Manage Staging and Active Data"
- Programmatically by performing a "GET"
View the data in SAP BRH through the API
123456
curl
--header ‘Authorization: Bearer $token’
--request GET
--url 'https://{yourtenant}/dso_batches/BatchesStage?$filter=(ID eq ‘\''123466’\")’
--header 'Content-Type: application/json’
With the above command you can verify that the entity that you have just posted to SAP BRH has arrived, and as well collect all the additional information that the system has generated for that specific record to make it usable in the application.

Note
{
"ID": "123467",
"material_ID": "12345M",
"plant_ID": "ABCD",
"status_ID": "A",
"sourceModifiedBy": "D069082",
"sourceIdentifier": "S4LCLNT300",
"sourceModifiedAt": "2022-11-09T13:36:02.000Z"
}
{
"material_ID": "12345M",
"ID": "123467",
"plant_ID": "ABCD",
"status_ID": "A",
"sourceModifiedBy": "D069082",
"sourceIdentifier": "S4LCLNT300",
"sourceModifiedAt": "2022-11-09T13:36:02.000Z"
}
In order to facilitate your own work, actually you do not need to create a payload with the properties in the same order as specified in the API.
As shown above you can create a payload with the properties in the order that is simpler to you,
However what is essential is that they are all there, and with the appropriate content and format !

SAP BRH API are all based on the HTTPS protocol, access is secured through OAUTH2 mechanism, are all strongly typed.
Therefore there could be many different types of reasons why a POST or a GET failed.
- Network error
For example the network connectivity is not stable and the API call could not reach the server.
Solution: Try again.
- Network encryption error
For example the Secure Socket Layer of the application executing the call is corrupted.
Solution: Verify that your SSL setup is properly working.
- Authorization error (401)
For example, the credentials that you are using to collect the authentication token are failing. You will notice this by the token request (first call shown earlier) failing.
Solution: Contact your BTP Administrator and request the new credentials.
- URL endpoint is wrong
For example, the endpoint is not found since there is a typo in the address of the endpoint.
Solution: Verify with the Business Api.
- Payload is wrong
A common way to know is by checking the return message from the API call, in case of synchronous communication we have described previously that in fact three types of messages must be handled from a synchronous service: the input, the response in case that everything went as expected, and the error message. Usually the error message contains sufficient information for a developer to understand what went wrong. For SAP BRH, an error in the format of the payload would be reported as "400 Deserialization error".
Solution: check carefully that the payload coincide with the specification. If everything is according to the specification, then the only way out is to open a ticket to the support . Few specific examples are reported in the previous slides.

SAP BRH is a highly integratable application, it enables integration using a rich set of API and supports both Asynchronous and Synchronous approaches. Through the standardized payloads, it is simple for developers to switch between the asynchronous or synchronous approach on demand. The online documentation, with source code examples makes it very simple for Integrators and Consultants to facilitate design and implement SAP BRH integration.