Skip to Content
Technical Articles
Author's profile photo Varun Venkat

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 “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!

Assigned Tags

      5 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Goran Kovacic
      Goran Kovacic

      Hi Varun,

      thank you for the informative post. It is exactly what a customer of ours requested a couple of weeks ago!

      I understand all what you wrote and can incorporate it into our case, the only thing that makes me wonder is - how did you find the BusinessObjectTypeName? How or where did you find that the BusinessObjectTypeName for the SalesOrder is ‘BUS2032’?

      Is there are documentation or api with which you can also get the other BusinessObjectTypeName? For example for the Sales Invoice, Purchase Order, Bill of Materials, etc.

      I searched the following, but nothing had the info which I was looking for:

       

      Thank you and best regards,
      Goran

      Author's profile photo Varun Venkat
      Varun Venkat
      Blog Post Author

      Hi Goran,

      thanks for the feedback, glad to hear that you found the post helpful. To answer your question, unfortunately there is no central documentation where you can find the appropriate business object type names for the various documents such as Sales order, Purchase order etc. I faced the same situation as yourself - luckily I was able to find the correct BusinessObjectTypeName for the Sales order on another blog post.

      There seems to be one workaround that I found, by which you can find the BusinessObjectTypeName for a particular entity, however this involves some additional effort. Here are the steps, in case you want to try this out:

      1) You need access to a S/4HANA on-premise system, which you can access via the SAP Easy Access (SAP GUI) backend.
      2) Logon with your user and run the transaction code SE15

      3) Double-click Business object types as shown in the screenshot below

      4) Search for the entity, whose BusinessObjectTypeName" you are looking for in the "Short description" field

      5) You will now find the corresponding BusinessObjectTypeName of the entity you are looking for. In this case, it is BUS2012 for Purchase Orders.

      Let me know if this helps.

      Author's profile photo Goran Kovacic
      Goran Kovacic

      Hi Varun,

       

      thank you for looking into it and giving the explanation. It looks promising and will test it out!

      Yeah, it is a workaround and it works only if you have access to a S/4HANA On-Premise or Private-Cloud System, but luckily I have both 🙂

       

      Best regards,
      Goran

      Author's profile photo Bruno Della Ducata
      Bruno Della Ducata

      Hi Varun

      Thank you for this very interesting blog!

      I tried in our S/4HANA Cloud (Public) system, but for any Sales Order (Business Object Type Name BUS2032) I get a status 200 with an empty reply body!

      Do you know any prerequisites in S/4HANA Cloud must be done in order to access these attachments?

      Best Regards
      Bruno

      Author's profile photo Varun Venkat
      Varun Venkat
      Blog Post Author

      Hi Bruno, thanks for your feedback! Since you are getting a 200 status code, it definitely is not a communication arrangement or authorization problem. Since you are getting an empty reply body, I would assume that you are using a sample Sales Order that doesn't actually contain any attachments.

      SO%20without%20attachments

      SO without attachments

       

      I would suggest you go into edit mode of the Sales Order you are testing with, click on attachments and upload any pdf document. Then try running the API request again and you should see your pdf appear as a response.

      Best regards
      Varun