Enterprise Resource Planning Blogs by Members
Gain new perspectives and knowledge about enterprise resource planning in blog posts from community members. Share your own comments and ERP insights today!
cancel
Showing results for 
Search instead for 
Did you mean: 
M_Kalyabin
Participant
1,891

From IDOCs to APIs

 

M_Kalyabin_1-1731933215329.png

 

In my previous posts, I described various aspects of EDI inbound order processing using the classical IDOC-based approach. However, SAP considers IDOCs an outdated technology, and the use of APIs is recommended for S/4HANA implementations. The purpose of this article is to demonstrate how a functional consultant can select and test an API for sales order creation.

This article explains how to select an API and test a SOAP API using simple requests directly with system master data. The next article will cover mapping external data, such as customer partner and material numbers, GLNs, EAN/GTINs, and sales area determination.

How to select API for Sales order creation: B2B API

Let's start from selection of API for Sales order creation for SAP S/4 HANA Cloud Private Edition. The starting point for searching for APIs is the SAP Business Accelerator Hub.

By selecting the APIs section and filtering by the product SAP S/4HANA Cloud Private Edition, you will find a wide range of more or less relevant results. The most important factor for selection is the purpose coded as A2A, A2X, and B2B. It’s also essential to note whether the API is marked as ODATA or SOAP, as this affects the implementation and testing technique. However, I believe the purpose is the primary criterion for selection, while the API type should be considered secondarily.

api.sap.comapi.sap.com

A2X, A2A, or B2B - What to Select for EDI Interchange?

The SAP Help Portal provides the following explanation of these API types in the APIs for Sales article:

  • A2X stands for application to X users. You can use an A2X service to connect SAP S/4HANA with another system in your system landscape. It is an OData-based web service with a synchronous execution.
  • A2A stands for application to application. You can use an A2A service to connect SAP S/4HANA with another system in your system landscape. It is a SOAP-based web service with an asynchronous execution.
  • B2B stands for business to business. You can use a B2B service to connect SAP S/4HANA with a system in another system landscape. It is a SOAP-based web service with an asynchronous execution.

Based on this description, I conclude that for EDI purpose, B2B is the more applicable option.

Indeed, if you compare body structure of A2X and B2B, you will find the difference. B2B provides wide options for external data, such as GLNs, external partner numbers, EAN/GTINSs, Customer material info records (CMIR) and so on. Alternatively, A2X looks like a reflection of SAP standard tables and dedicated to work with internal SAP identifiers. 

B2B vs A2X: partner detailsB2B vs A2X: partner details

Based on the explanation above, I selected the "Sales Order/Customer Return - Create, Update, Cancel (B2B)" API.

Basic information about this API is available on the API page of SAP Business Accelerator Hub. The Documentation tab on the API page provides a link to help.sap.com , where additional details can be found, including configuration steps and sample payloads. The technical name of this service is ORDERREQUEST_IN, which will be needed later.

Setup for Testing: AIF

The SOAP API OrderRequest_In uses the SAP Application Interface Framework (AIF) for processing and monitoring. To begin, ensure that the scenario ID SAP_COM_0223 is deployed as described in the relevant section of SAP Help.

Checking Deployment

To verify if the scenario is already deployed:

  1. Use the monitoring transaction code /AIF/ERR - Monitoring and Error Handling .
    As with all transaction codes starting with /, run it as /n/AIF/ERR from the Command field or add it to your Favorites.
  2. Check if /SDEDI Sales & Distribution EDI Integration is available in the Namespace search help. If it is not available, you will need to deploy it.
    SAP "Monitoring and Error Handling" screen with '/SDEDI' namespace for Sales & Distribution EDI Integration.SAP "Monitoring and Error Handling" screen with '/SDEDI' namespace for Sales & Distribution EDI Integration.

Sales & Distribution EDI Integration Deployment

To deploy the required content:

  1. Use transaction code /AIF/CONTENT_EXTRACT (AIF Content Transport – Deploy).
  2. Add the deployment scenario ID SAP_COM_0223.
  3. Press F8 (Execute) to complete the deployment.

"AIF Content Transport" screen for deploying scenario ID SAP_COM_0223."AIF Content Transport" screen for deploying scenario ID SAP_COM_0223.

Confirmation of Successful Deployment:

Deployment Scenario SAP_COM_0223 successfully extracted.Deployment Scenario SAP_COM_0223 successfully extracted.

AIF Licensing

There has been some discussion in the community about whether AIF requires additional licensing. Based on my research, AIF services provided within the SAP namespace do not require extra licensing. In this case, the service falls under the /SDEDI namespace, so no separate licensing is necessary.

However, it is recommended to confirm this with the responsible person in your organization for complete assurance.

SOAP API Testing Using SE80 Object Navigator

A common method for testing API is sending requests to the SAP system using tools like Postman. This option mimics real interchange but requires additional effort to learn new tools and address potential infrastructure challenges such as connectivity and access. For processing a payload by the SAP S/4HANA system without infrastructure issues, a simpler option is testing directly within the system using SE80 Object Navigator.

Run t-code SE80 Object Navigator. If Enterprise Service Browser is unavailable, enable it: Utilities > Settings > Workbench (General) > Enterprise Services Browser.

Enabling Enterprise Services Browser in SE80 ABAP Workbench settings under Utilities > Settings.Enabling Enterprise Services Browser in SE80 ABAP Workbench settings under Utilities > Settings.

Please select Enterprise Services Browser and open the Web Service Definition ORDERREQUEST_IN.

SE80: Accessing ORDERREQUEST_IN in Enterprise Services Browser under Web Service Definition.SE80: Accessing ORDERREQUEST_IN in Enterprise Services Browser under Web Service Definition.

Press F8 to test.

SE80: Displaying OrderRequest_In service definition details for creating, changing, or deleting sales orders.SE80: Displaying OrderRequest_In service definition details for creating, changing, or deleting sales orders.

Notice: Another available option is to navigate through: Repository Browser > Package > LOG_EDI_INTEGRATION > Subpackages > LOG_EDI_SD > Subpackages > LOG_EDI_SD_IMPL_ORDER > Enterprise Services > Service Definitions > ORDERREQUEST_IN.

SE80: Detailed view of OrderRequest_In service definition within LOG_EDI_INTEGRATION package.SE80: Detailed view of OrderRequest_In service definition within LOG_EDI_INTEGRATION package.

Select Input Template

  1. Request template: informative but complex
  2. Template without payload: easy to paste your payload

SE80: Test Service Provider screen for ORDER_REQUEST_IN with options to generate a request template.SE80: Test Service Provider screen for ORDER_REQUEST_IN with options to generate a request template.

Example below is a template without payload. Switch to Editor (1) to paste or edit text, or Load an existing test file (2)

SE80: Test Service Provider: Display Request screen showing XML template for OrderRequest structure.SE80: Test Service Provider: Display Request screen showing XML template for OrderRequest structure.

It is also possible to save and open payloads using the Save variant and Get variant options.

SE80: Save variant and Get variant.SE80: Save variant and Get variant.

When Request is prepared by Editor or loaded, following features are helpful:

  1. Execute request
  2. Check XML
  3. Download the request for future use
  4. Adjust XML for better readability

SE80: XML Request editorSE80: XML Request editor

Run the request: M_Kalyabin_12-1731669673746.png F8 Execute. A notice indicates successful processing for this API, meaning that the sales order has been created.

Successful with empty result - commit may be required.Successful with empty result - commit may be required.

Run VA03 to find a created Sales Order. The last order created by the user will be used as the Order number. Alternatively, use VA05 to find created Orders. More monitoring options are in the next section. The error response below indicates a request with the same PO number was previously sent.

SE80: XML Response with Error DescriptionSE80: XML Response with Error Description

Basic Payload Example

When starting testing, I prefer to use a simple example based on an existing sales order in the system. Testing with a clear and straightforward case makes debugging easier, minimizing references to EDI-specific logic.

To create such an example:

  1. Identify an Existing Sales Order: Select a sales order already present in the system.
  2. Recreate It Manually: Ensure the settings and master data are valid by manually recreating the order.
  3. Generate Payload: Use a simple template to create the payload based on this verified sales order.

Below is an example of a basic order payload. This payload contains the minimal required data to create a sales order using system data directly, without any mapping. 

  • Message Header Data: Mandatory but can use any placeholder values for basic testing.
  • Order Data: Must be populated with relevant data, such as details from an existing sales order.

Additionally, I included comments within the payload. These comments can be excluded as needed. This example is particularly useful for training purposes or for simulating intercompany scenarios where both systems involved in the interchange use the same master data.

Order Request Payload

 

 

 

 

 

<n0:OrderRequest xmlns:n0="http://sap.com/xi/EDI">
 <MessageHeader>
  <ID>Message_Header_ID</ID>
  <CreationDateTime>2024-11-10T02:53:20Z</CreationDateTime>
  <SenderParty>
   <InternalID>DummyS</InternalID>
  </SenderParty>
 </MessageHeader>
 <Order>
  <PurchaseOrderID>B2B_API_test_1</PurchaseOrderID>
  <PurchaseOrderCreationDate>2024-10-23</PurchaseOrderCreationDate>
  <!-- Order type and Sales area-->
  <SalesDocumentType>ZOR</SalesDocumentType>
  <SalesOrganization>1000</SalesOrganization>
  <DistributionChannel>10</DistributionChannel>
  <OrganizationDivision>00</OrganizationDivision>
  <Party PartyType="SoldTo">
   <!-- SAP number of Sold-to party-->
   <SupplierPartyID>211</SupplierPartyID>
  </Party>
  <Party PartyType="ShipTo">
   <!-- SAP number of Ship-to party-->
   <SupplierPartyID>212</SupplierPartyID>
  </Party>
  <OrderItem>
   <PurchaseOrderItemID>10</PurchaseOrderItemID>
   <RequestedQuantity unitCode="PCE">1.0</RequestedQuantity>
   <Product>
    <!-- SAP number of material-->
    <SupplierProductID>1521</SupplierProductID>
   </Product>
  </OrderItem>
 </Order>
</n0:OrderRequest>

 

 

 

 

This basic example provides a minimal setup for creating a sales order while using direct system data. Feel free to adjust the values based on your specific scenario or testing needs.

Let’s test using SE80, as explained above: prepare an payload and Press F8 Execute:

Simple XML Order RequestSimple XML Order Request

Result:

Processing resultProcessing result

VA03 Display sales order: Highlighted fields, such as those populated from the payload data, including Sold-To Party, Ship-To Party, and Order Type, are displayed. Other fields, like Payment Terms, Incoterms, and Item Description, are automatically populated based on the system's master data and configuration settings.

VA03 Sales orderVA03 Sales order

It’s important to note that the master data must be sufficiently complete. For example, if Incoterms or Payment Terms are missing from the customer master record, an error may occur during processing. To address this issue, you can either update the master data to include the missing information or add the required data directly to the payload.

Extended Payload Example

This is another “simple” example that directly uses system data without relying on EDI-specific settings. However, it demonstrates several important EDI-related features:

  • OrderItemText: If provided, this field replaces the text from the material master data.
  • BuyerProductID: Even if not used for mapping, it is stored in the related item field and can be utilized for outputs.
  • ExpectedNetPrice: This value is mapped to the EDI1 price condition.
  • ExpectedNetAmount: This value is mapped to the EDI2 price condition.

 

 

 

 

<n0:OrderRequest xmlns:n0="http://sap.com/xi/EDI">
 <MessageHeader>
  <ID>Message_Header_ID</ID>
  <CreationDateTime>2020-04-10T02:53:20Z</CreationDateTime>
  <SenderParty>
   <InternalID>DummyS</InternalID>
  </SenderParty>
 </MessageHeader>
 <Order>
  <PurchaseOrderID>B2B_API_test_1.1</PurchaseOrderID>
  <PurchaseOrderCreationDate>2024-10-23</PurchaseOrderCreationDate>
  <SalesDocumentType>ZOR</SalesDocumentType>
  <SalesOrganization>1000</SalesOrganization>
  <DistributionChannel>10</DistributionChannel>
  <OrganizationDivision>00</OrganizationDivision>
  <Party PartyType="SoldTo">
   <SupplierPartyID>211</SupplierPartyID>
  </Party>
  <Party PartyType="ShipTo">
   <SupplierPartyID>212</SupplierPartyID>
  </Party>
  <OrderItem>
   <PurchaseOrderItemID>10</PurchaseOrderItemID>
   <OrderItemText>Customer Order item text</OrderItemText>
   <RequestedQuantity unitCode="PCE">10.0</RequestedQuantity>
   <Product>
    <SupplierProductID>1521</SupplierProductID>
    <BuyerProductID>CustMatID</BuyerProductID>
   </Product>
   <ExpectedNetPrice>
    <Amount currencyCode="NOK">11</Amount>
    <BaseQuantity unitCode="PCE">1</BaseQuantity>
   </ExpectedNetPrice>
   <ExpectedNetAmount currencyCode="NOK">110</ExpectedNetAmount>
  </OrderItem>
 </Order>
</n0:OrderRequest>

 

 

 

Sales order:

VA03 Sales Order: customer material informationVA03 Sales Order: customer material information

VA03: Sales order, Customer expected Price and ValueVA03: Sales order, Customer expected Price and Value

Monitoring of SOAP API Processing

Since SOAP API processing is based on the Application Interface Framework (AIF), AIF-related tools can be used for monitoring and error handling.

/AIF/ERR - Monitoring and Error Handling. To improve performance and reduce the volume of data displayed, apply the following filters on the selection screen:

  • Application: AIF
  • Namespace: /SDEDI

Additionally, adjust the status selection to include both error and successful messages to gain a comprehensive view of the processing result

/AIF/ERR - Monitoring and Error Handling: Selection screen/AIF/ERR - Monitoring and Error Handling: Selection screen

When you run the report, messages are displayed in a structured format, organized by Sender ID (from the message header) and PO number.

  • To view details, select a message from the list.
  • The log records will display information about either successful processing or error occurrences, providing clarity on the message status and any required actions.

/AIF/ERR - Monitoring and Error Handling: ALV screen/AIF/ERR - Monitoring and Error Handling: ALV screen

/AIF/LOG - Interface Logs. Another available option for monitoring. To narrow down the results and generate a focused report, select a relevant Subobject during the selection process.

/AIF/LOG - Interface Logs: Selection screen./AIF/LOG - Interface Logs: Selection screen.

Select message on the upper screen and find the log records on the lower screen.

/AIF/LOG - Interface Logs: ALV screen/AIF/LOG - Interface Logs: ALV screen

The transactions SRT_MONI (WS Message Monitor) and SRT_UTIL (Web Service Utilities) are frequently mentioned in the context of SOAP monitoring. However they are dedicated for lower transmission infrastructure level and not relevant for payload processing errors and monitoring of messages created by SE80 test technique.

Handling Errors

Successfully processing an inbound message on the first attempt is very rare. Typically, it requires an iterative process of running the message, adjusting the payload, and refining the system setup or master data.

SOAP API processing provides informative error messages as part of the response to help you identify and resolve issues. Below are some common errors and their possible causes.

Typical Errors and Their Causes

Class II_EDI_ORDER_REQUEST_IN is not a proxy class. This error appears if AIF deployment scenario hasn’t been extracted.

Error response: Class II_EDI_ORDER_REQUEST_IN is not a proxy class.Error response: Class II_EDI_ORDER_REQUEST_IN is not a proxy class.

The Source Party internal ID must be provided in the source data. Message header sender data is not complete.

Error response: The Source Party internal ID must be provided in the source data.Error response: The Source Party internal ID must be provided in the source data.

Sales area cannot be determined. This occurs when key parameters are missing: Sales Order Type, Sales Organization, Distribution Channel, or Division. Ensure these are provided or configured for determination by external data.

Error response: Sales area cannot be determined.Error response: Sales area cannot be determined.

Supplier Party ID 0000001111 is not found. This occurs when the provided Supplier Party ID does not match the system's master data. Ensure the ID is correct and exists in the system.

Error response: Supplier Party ID 0000001111 is not found.Error response: Supplier Party ID 0000001111 is not found.

Business partner for role Sold-to party cannot be determined. This occurs when Supplier party ID is missing, and Buyer party ID isn’t configured for external determination.

Error response: Business partner for role Sold-to party cannot be determined.Error response: Business partner for role Sold-to party cannot be determined.

Material 1521-00 is not defined for sales org.1000, distr.chan.10, language EN. This occurs when the provided Supplier Product ID does not match the system's master data.

Error response: Material 1521-00 is not defined for sales org. 1000, distr. chan. 10, language EN.Error response: Material 1521-00 is not defined for sales org. 1000, distr. chan. 10, language EN.

Acknowledgements and System Overview

I would like to thank my colleagues, Askar Timofeev and Vadim Vologzhanin, for helping me learn this topic. I also extend my gratitude to Capgemini for providing a sandbox system, which I used for investigations, creating test examples, and preparing screenshots. The sandbox was SAP S/4HANA 2022 (S/4HANA On-Premise Release 2022 SP 01, February 2023 FPS).

 

1 Comment
EuricoBorges
Participant
0 Kudos

Excelent blog @M_Kalyabin . This is a route that we are also taking, moving away from IDOC based EDI to Web Services based EDI. It has been an hard route since SAP documentation is still a bit scarse and we can't find a lot infomration on the full end-to-end process.

Have you had to add standard sales order fields to the Sales Order/Customer Return - Confirm Processing (B2B) -OrderRequest_In SOAP Web Service ?

For example, the standard Shipping Conditon field is not in the Sales Order/Customer Return - Confirm Processing (B2B) -OrderRequest_In SOAP Web Service but it is on Sales Order (A2X)-Sales Order Header POST /A_Order Odata Web Service and also on Sales Order (A2A) -SalesOrderBulkRequest_In SOAP Web Service .

 

Labels in this area