Access a sales order document through an external system using the Attachments API

In this blog post, I would like to walk you through how you can access a sales order document SAP S/4HANA Cloud from an external system using the functionality of the Attachments API. To demonstrate the behavior of the API calls, I’ll be using Postman.

Prerequisites:

• You have setup the necessary communication arrangement along with a communication user with the necessary permissions to access the sales order document. Please refer to the following blog to see how this is done.
  • * The blog shows the process for the “Puchase Order intregration” communication scenario. Make sure you create a communication scenario for “Sales Order integration” (SAP_COM_0109) as well.
• Select a specific sales order from your S/4HANA Cloud system that you will use as an example over the course of this blog. Use the Sales Order ID shown in the “Manage Sales Order” application for this.
  • For the demo scenario, I will be using the Sales Order 324979

Once the prerequisites are out of the way, you can proceed with the following steps:

1. Now, switch to Postman to get started with the demo. The first step is to request an x-csrf-token from the test landscape you are using.
   • Method: GET
   • Request URL:
     • <test system endpoint URL>/sap/opu/odata/sap/API_CV_ATTACHMENT_SRV
   • Authorization: Basic Auth
     • Use the username and password of the communication user that you have setup in the beginning
   •  Headers:
     • Key: x-csrf-token
     • Value: Fetch
   • Once you send this request, you should receive a “200” response code indicating that the request has been successfully sent. In the response section, under the “Headers” tab, copy the value of the x-csrf-token. This token will be used for the subsequent requests to authenticate your user.
     

1. Now that we have a token, we can go ahead and send our first request to the system. This request will call the “getAllOriginals” API and fetch the metadata of the Sales order document that we are trying to view.

• • Method: GET
  • Request URL:
    • <test system endpoint URL>/sap/opu/odata/SAP/API_CV_ATTACHMENT_SRV/GetAllOriginals
  •  Params:
    • LinkedSAPObjectKey: <ID of the Sales order that you want to access>
      • The value must be 9 digits long, so prefix the ID of the sales order with leading zeroes as shown in the screenshot below.
      • In the example I’ve shown the Sales order ID is ‘324979’, which needs to be inputted as ‘0000324979’
    • BusinessObjectTypeName: ‘BUS2032’ (this is the BusinessObjectTypeName for Sales orders in general)
      
  • Authorization: Basic Auth
    • Use the username and password of the communication user that you have setup in the beginning
  •  Headers:
    • Key: x-csrf-token
    • Value: <value of the token copied from Step 1>
  • Once you send this request, you should receive a “200” response code indicating that the request has been successfully sent. In the response section, under the “Body” tab, you will see a response that looks like this:
    
  • Copy the values of all the attributes of the <title> tag as you will be needing these for the next request. In the screenshot above, you will notice that the attributes “DocumentInfoRecordDocVersion” and “DocumentInfoRecordDocPart” have empty values. For these, use the values ‘00’ and ‘000’ respectively.

1. Now that we have the metadata of the sales order document we want to view, we can proceed with the final request. We now call the of the “Download Attachment Content” API, which will return the sales order attachment as a pdf document.
   • Method: GET
   • Request URL:
     • <test system endpoint URL>/sap/opu/odata/ SAP/API_CV_ATTACHMENT_SRV/AttachmentContentSet(DocumentInfoRecordDocType='<value from previous response>’,DocumentInfoRecordDocNumber='<value from previous response>’,DocumentInfoRecordDocVersion=’00’, DocumentInfoRecordDocPart=’000′, LogicalDocument='<value from previous response>’,ArchiveDocumentID=’ <value from previous response>’,LinkedSAPObjectKey=’0000324979′,BusinessObjectTypeName=’BUS2032′)/$value
   •  Headers
     • Key: x-csrf-token
     • Value: <value of the token copied from Step 1>
   • Once you send this request, you should receive a “200” response code as well as the attachment of the Sales order document from the S/4HANA Cloud system.
     

Note:

In case you don’t receive an HTTP 200 response code for any of the requests above, please refer to the following checklist, that lists some of the common sources of error:

• Incorrect username or password of the Communication user you are using.
• The validity of the x-csrf-token used for authentication has expired.
  • In this case, create a new token by repeating Step 1.
• In Step 2, the parameter values need to be enclosed in single quotes.
• In Step 3, the key-value pairs are not entered as query parameters of the request, rather directly appended to the request URL.

Feel free to leave a comment if this blog helped you out, or if you have any issues with any of the steps!