Create JSON payload based on API documentation

Introduction

This blog describes the way, how to create the simplest payload with minimum set of fields, which can be used for tests via Postman (for example). Additionally, such payload helps to identify obligatory for the mapping fields, in case of Integration Flow creation. Therefore this action can be considered as the recommended first step in the integration flow development process in order to avoid payload-related issues.

During the demo following components would be needed:

• SAP S/4HANA Cloud System
• Postman
• API Business Hub

Preparation

For this demo we will use Material Documents – Read, Create API. On “Details” tab you can find Communication Scenario name, with which it is necessary to create Communication Arrangement in SAP S/4HANA Cloud System. Refer to this blog for Communication Arrangement´ creation steps.

Once you created the Communication Arrangement, copy OData service url to Postman and add /A_MaterialDocumentItem in the end of the link to reach the existing entries.

Communication Arrangement

Postman

Go to the Authorisation tab in Postman, select Basic Auth type and enter credentials of the user, you created for the Communication Arrangement earlier:

Make sure you selected Get as the operation and send the request.

When the request is fulfilled you can see items in Body tab of the lower part of the screen, existing in the SAP S/4HANA Cloud System:

Items

We will need the values, provided in any item to fill values of obligatory fields of our future sample payload. 

Building the Payload

Now let´s go back to SAP API Business Hub, Material Documents – Read, Create API and copy to Notepad (or Notepad++) structure of Post request for /A_MaterialDocumentHeader:

Post structure

Then we need to go to Details tab again, scroll down and go to the Business Documentation:

Then go to Create Material Documents page. Here you can check, which fields are mandatory for Header and for Item. This is the minimum set of fields, we need to have in our payload from general technical perspective. And for them we need to provide values out of our Get request results:

Documentation

In the same time, it is necessary to mention that knowledge of your business processes will be necessary anyway. Based on the customizing done in your SAP S/4HANA System and way, the business process is built, the fields, mentioned in the Document as the Optional could be mandatory in your case. There are two ways to identify them:

1. Try to create Material Document Item manually in the system.
2. Try to post the Payload from Postman with the minimum set of fields and check Body area in the lower part of the screen. The errors, saying which fields are missed will be available there.

The only thing, which is left to do now is to check field by field Post sample request, we took from the SAP API Business Hub, delete unnecessary fields and fill the rest with results from our Get request.

Here it is the payload with minimum set of fields, which worked for my system:

{
    "DocumentDate": "/Date(1611320834000)/",
    "PostingDate": "/Date(1611320834000)/",
    "GoodsMovementCode": "01",
    "to_MaterialDocumentItem": {
        "results": [
            {
                "Plant": "ROT1",
                "StorageLocation": "RO1Z",
                "GoodsMovementType": "101",                
                "PurchaseOrder": "4500001080",
                "PurchaseOrderItem": "10",
                "GoodsMovementRefDocType": "B",                                
                "QuantityInEntryUnit": "1",               
                "SerialNumbersAreCreatedAutomly": true
            }
        ]
    }
}

Important remark: do not forget to change A_MaterialDocumentItem in the link of our request to A_MaterialDocumentHeader – the Material Document API does not support direct posting on Item level:

Postman – change URL

Conclusion

After this operations you have the working directly with SAP S/4HANA system payload and can move to Integration Flow development and mapping tasks.