Sales Order Web Service APIs

knutheusermann · ‎2017 Aug 10

SAP Business ByDesign (ByD) provides web services to create ByD Sales Orders in context of three main use cases:

Manage ByD sales orders from a remote ordering system: Using web service APIs you can create and change ByD sales orders similar to manual sales orders that can be created via ByD UI.

eCommerce/webshop integration: Using the same web service APIs you can create and released provisional internet orders and request real-time information, such as availability, prices, tax and freight from ByD.

B2B collaboration: Using the B2B inbound interface for sales orders you can receive sales orders from your customers automatically via xml messages.

This blog post provides you with an overview on ByD web services used for those 3 use cases and considers some frequently asked questions related to sales order integration scenarios.

Additionally to the web services that are subject of this blog post, ByD offers 2 OData APIs for ByD sales orders:

OData for Analytics can be used to access ByD sales order reports; you find a detailed description in our ByD Community: OData for SAP Business ByDesign Analytics.

The work center view OData Servicescan be used to assemble your own custom OData services to access ByD sales orders. This API is designed for UI-like remote applications that interactively query, read, create, update or perform actions on ByD sales orders.

However, ByD OData capabilities might be subject of some other blog post in the future.

Sales Order Web Service APIs

SAP Business ByDesign provides 2 web service APIs for read and write access to ByD sales orders:

The web service API QuerySalesOrderIn can be used to search and read ByD sales orders. The sales orders are returned in a deeply structured xml that contains all relevant sales order data.

The web service API ManageSalesOrderIn is designed to create and change sales orders. However, this service can be used to release or delete sales orders as well.

You find a detailed documentation with examples for all web service APIs on SAP Help > Integration > Web Service APIs.
Please check as well the general ByD web service documentation that is linked in the API documentation in chapter "General Information".

In the following I consider some special use cases:

Create Sales Orders and change the Item Price

Using web service ManageSalesOrderIn item prices are calculated by the system based on the ByD price and tax determination. However you can change the item price in a second web service call and overwrite the calculated price components.

The steps to be performed are basically:

Create order with all data except prices

Update the order item price

Depending on your detailed requirements 3 web service choreographies make sense:

Update the item main price:

Create SO

Update SO item main price

Update price component using the price component key:

Create SO

Query SO and get price component UUID

Update SO price component with the given price component UUID from step 2.

Update price component using the price component type:

Create SO

Update SO price component with the given price component type code.

Example xml to create a sales order:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">

	<soapenv:Header/>

	<soapenv:Body>

		<glob:SalesOrderBundleMaintainRequest_sync>

			<BasicMessageHeader>

			</BasicMessageHeader>

			<SalesOrder actionCode="01">

				<ReleaseAllItemsToExecution>false</ReleaseAllItemsToExecution>

				<SalesUnitParty actionCode="04">

					<PartyID>S1121</PartyID>

				</SalesUnitParty>

				<AccountParty actionCode="04">

					<PartyID>CS200125</PartyID>

				</AccountParty>

				<PricingTerms actionCode="04">

					<CurrencyCode>USD</CurrencyCode>

					<PriceDateTime timeZoneCode="UTC">2017-05-07T13:58:00Z</PriceDateTime>

					<GrossAmountIndicator>false</GrossAmountIndicator>

				</PricingTerms>        

				<Item actionCode="04">

					<ID>10</ID>

					<ProcessingTypeCode>TPTM</ProcessingTypeCode>

					<ReleaseToExecute>false</ReleaseToExecute>

					<ItemProduct actionCode="04">

						<ProductInternalID>S200102</ProductInternalID>

					</ItemProduct>

					<ItemScheduleLine actionCode="04">

						<ID>1</ID>

						<TypeCode>1</TypeCode>

						<Quantity unitCode="HUR">5.0</Quantity>

					</ItemScheduleLine>

				</Item>

			</SalesOrder>

		</glob:SalesOrderBundleMaintainRequest_sync>

	</soapenv:Body>

</soapenv:Envelope>

Example xml to update the sales order item main price:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">

	<soapenv:Header/>

	<soapenv:Body>

		<glob:SalesOrderBundleMaintainRequest_sync>

			<BasicMessageHeader>

			</BasicMessageHeader>

			<SalesOrder actionCode="04">

				<ID>5346</ID>

				<ReleaseAllItemsToExecution>true</ReleaseAllItemsToExecution>

				<Item actionCode="04">

					<ID>10</ID>

					<ReleaseToExecute>true</ReleaseToExecute>

					<PriceAndTaxCalculationItem actionCode="04">

						<ItemMainPrice actionCode="04">

							<Rate>

								<DecimalValue>28.0</DecimalValue>

								<CurrencyCode>USD</CurrencyCode>

								<BaseDecimalValue>5.0</BaseDecimalValue>

								<BaseMeasureUnitCode>HUR</BaseMeasureUnitCode>

							</Rate>

						</ItemMainPrice>

					</PriceAndTaxCalculationItem>

				</Item>

			</SalesOrder>

		</glob:SalesOrderBundleMaintainRequest_sync>

	</soapenv:Body>

</soapenv:Envelope>

Since ByD release 1805 you can create a sales order with price components (using main price and main discount or price components) and released the sales order in one single web service call:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">

   <soapenv:Header/>

   <soapenv:Body>

      <glob:SalesOrderBundleMaintainRequest_sync>

         <BasicMessageHeader>

         </BasicMessageHeader>

         <SalesOrder actionCode="01">

            <ObjectNodeSenderTechnicalID>S1</ObjectNodeSenderTechnicalID>         

            <ReleaseAllItemsToExecution>true</ReleaseAllItemsToExecution>

            <SalesUnitParty actionCode="04">

               <PartyID>S1121</PartyID>

            </SalesUnitParty>

            <AccountParty actionCode="04">

               <PartyID>CS200125</PartyID>

            </AccountParty>

            <PricingTerms actionCode="04">

               <CurrencyCode>USD</CurrencyCode>

               <PriceDateTime timeZoneCode="UTC">2018-12-21T10:58:00Z</PriceDateTime>

               <GrossAmountIndicator>false</GrossAmountIndicator>

            </PricingTerms>        

            <Item actionCode="04">

            	<ObjectNodeSenderTechnicalID>S1-I1</ObjectNodeSenderTechnicalID>         

               <ID>10</ID>

               <ProcessingTypeCode>TAS</ProcessingTypeCode>

               <ItemProduct actionCode="04">

                  <ProductInternalID>S200102</ProductInternalID>

               </ItemProduct>

               <ItemScheduleLine actionCode="04">

                  <ID>1</ID>

                  <TypeCode>1</TypeCode>

                  <Quantity unitCode="HUR">5.0</Quantity>

               </ItemScheduleLine>

               <PriceAndTaxCalculationItem actionCode="04">

                  <ItemMainPrice actionCode="04">

                     <Rate>

                        <DecimalValue>123.0</DecimalValue>

                        <CurrencyCode>USD</CurrencyCode>

                        <BaseDecimalValue>1.0</BaseDecimalValue>

                        <BaseMeasureUnitCode>HUR</BaseMeasureUnitCode>

                     </Rate>

                  </ItemMainPrice>

               </PriceAndTaxCalculationItem>               

            </Item>

         </SalesOrder>

      </glob:SalesOrderBundleMaintainRequest_sync>

   </soapenv:Body>

</soapenv:Envelope>

Internet Orders / eCommerce Integration

Using web shop integration capabilities and web service ManageSalesOrderIn you create internet orders (sales orders of type "Internet Order") provisionally in ByD. These internet orders are not visible in the ByD Sales Order work list, but can be used for price determination, credit limit checks and ATP checks. These real-time information can be requested via web service QuerySalesOrderIn and displayed in the eCommerce/webshop application.

Note: Use xml element OriginTypeCode = 4 to create internet orders.

After completing the checkout process in the webshop, the provisional internet order in ByD can be released and added to the order processing worklist or automatically submitted for order processing. This is done by a second web service call that updates the provisional internet order using xml element ReleaseCustomerRequest = true. As result the internet order is visible in the ByD sales order work list. Typically this step is performed when the web shop shopping cart has been released.

Provisional internet orders that are not released can be deleted periodically using Internet Order Deletion Runs. You find a detailed documentation in the ByD Help Center searching for "Internet Order Deletion Runs".

You can configure the eCommerce/Web Shop integration in the ByD Business Configuration in step 4 - Questions of your implementation project in scoping element:
Sales > Selling Products and Services > E-Selling.

If you answer the question "Would you like your employees to control the release of sales orders that originate from an E-Shop in order to initiate order processing?" with

No, then releasing the provisional internet order results in a sales order in status "Open".

Yes (in scope), then releasing the provisional internet order results in a sales order in status "In preparation" and can be released manually via the ByD UI.

Sales orders with error messages are indicated as inconsistent and remain in status "In preparation".

Delete Sales Orders

Sales orders in status "In preparation" can be deleted using web service ManageSalesOrderIn by applying the sales order action codes 03 (delete) or 05 (remove).

Example:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">

	   <soapenv:Header/>

	   <soapenv:Body>

	      <glob:SalesOrderBundleMaintainRequest_sync>

	         <BasicMessageHeader>

	         </BasicMessageHeader>

	         <SalesOrder actionCode="03">

	            <ID>3135</ID>

	            <!-- <UUID>?</UUID> -->

	         </SalesOrder>

	      </glob:SalesOrderBundleMaintainRequest_sync>

	   </soapenv:Body>

</soapenv:Envelope>

Provisional internet orders that are not released can be deleted periodically using Internet Order Deletion Runs.

Calculate Prices and Check Availability w/o Sales Order

Using web service ManageSalesOrderIn to create sales orders, the ByD system calculates item prices and taxes based on the ByD price and tax determination.

However, the web service APIs CalculatePriceIn and ProductAvailabilityDeterminationIn can be helpful to calculate prices and check the product availability without creating a sales order as well.

The web service CalculatePriceIn can be used to calculate prices for multiple accounts or products. The web service creates sales orders in memory (the sales order will not be saved) with one sales order item for each item in the web service request to run a qualified price and tax determination.

To understand how the web service works it could be helpful to create a sales order via UI and check the resulting prices per item.

Example request

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">

   <soap:Header/>

   <soap:Body>

      <glob:CalculatePricesRequest_sync>

         <CalculatePricesRequest>

            <!-- Application: 1 Procurement, 2 Sales -->

            <Application>2</Application>

            <CurrencyCode>USD</CurrencyCode>

            <!-- false: use net price lists, true: use gross price lists -->

            <GrossPricingIndicator>false</GrossPricingIndicator>

            <PricingDate>2016-12-13</PricingDate>

            <AccountID>MC9785</AccountID>

            <Item>

               <ID>1</ID>

               <ProductID>MCF-0002</ProductID>

               <ProductTypeCode>1</ProductTypeCode>

            </Item>

            <Item>

               <ID>2</ID>

               <ProductID>MCF-0036</ProductID>

               <ProductTypeCode>1</ProductTypeCode>

            </Item>

         </CalculatePricesRequest>

      </glob:CalculatePricesRequest_sync>

   </soap:Body>

</soap:Envelope>

Remarks:

The Item/ID must be unique.

Code for element Application: 1 - Procurement, 2 - Sales

GrossPricingIndicator: false => use net price lists, true => use gross price lists

External Payments

The payment method “External payment” can be used for external sales orders created via web service.

You find the payment method in the web service request message types as element "SalesOrder/PaymentControl/PaymentFormCode". Additional to the payment method you have to provide the details for External Payment: "…/PaymentControl/ExternalPayment".

Payment Form Code for external payments: 20 - External Payment.

Payment Reference Type Code: 5 - Transaction Reference Number of externally paid e-commerce order

Example xml to release a sales order with external payment:

<?xml version="1.0" encoding="utf-8" ?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

	<soap:Body>

		<ns5:SalesOrderBundleMaintainRequest_sync xmlns:ns4="http://sap.com/xi/AP/Common/Global" xmlns:ns5="http://sap.com/xi/SAPGlobal20/Global">

			<SalesOrder actionCode="02">

				<ID>123</ID>

				<ReleaseCustomerRequest>true</ReleaseCustomerRequest>

				<PaymentControl>

					<PaymentProcessingCompanyID>Seller company</PaymentProcessingCompanyID>

					<PropertyMovementDirectionCode>2</PropertyMovementDirectionCode>

					<PaymentFormCode>20</PaymentFormCode>

					<PaymentReferenceID>Ref ID/transaction ID of payment provider</PaymentReferenceID>

					<PaymentReferenceTypeCode>5</PaymentReferenceTypeCode>

					<ExternalPayment actionCode="01">

						<HouseBankAccountKeyInternalID>Bank account in ByD for the payment provider</HouseBankAccountKeyInternalID>

						<PaymentTransactionReferenceID>Ref ID/transaction ID of payment provider</PaymentTransactionReferenceID>

						<DocumentDate>2014-03-31</DocumentDate>

						<ValueDate>2014-03-31</ValueDate>

						<Amount currencyCode="EUR">9.95</Amount>

					</ExternalPayment>

				</PaymentControl>

			</SalesOrder>

		</ns5:SalesOrderBundleMaintainRequest_sync>

	</soap:Body>

</soap:Envelope>

Sales Order with reference to marketing campaigns

You can create ByD sales orders with reference to marketing campaigns by adding the marketing campaign as BusinessTransactionDocumentReference with TypeCode "764" (764 is the object type code for business object "Marketing Campaign") to the sales order web service request.

The following example creates internet sales order with reference to marketing campaign "CAMP-123":

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">

   <soapenv:Header/>

   <soapenv:Body>

      <glob:SalesOrderBundleMaintainRequest_sync>

         <BasicMessageHeader>

         </BasicMessageHeader>

         <SalesOrder actionCode="01">

            <Name languageCode="EN">My Sales Order with Marketing Campaign 123</Name>

            <!-- DataOriginTypeCode: 4 = Internet order -->

            <DataOriginTypeCode>4</DataOriginTypeCode>

<!--        <ReleaseCustomerRequest>true</ReleaseCustomerRequest> -->

            <ReleaseAllItemsToExecution>false</ReleaseAllItemsToExecution>

            <BusinessTransactionDocumentReference actionCode="01">

               <BusinessTransactionDocumentReference>

                  <!-- You can use the ID or UUID of the marketing campaign -->

                  <ID>CAMP-123</ID> <!-- campaign ID -->

                  <!-- <UUID></UUID> -->

                  <!-- Type code 764 refers to object "Marketing Campaign" -->

                  <TypeCode>764</TypeCode> 

               </BusinessTransactionDocumentReference>

  <BusinessTransactionDocumentRelationshipRoleCode>1</BusinessTransactionDocumentRelationshipRoleCode>

               <DataProviderIndicator>true</DataProviderIndicator>

            </BusinessTransactionDocumentReference>

            <SalesUnitParty actionCode="04">

               <PartyID>S1121</PartyID>

            </SalesUnitParty>

            <AccountParty actionCode="04">

               <PartyID>CS200125</PartyID>

            </AccountParty>

            <PricingTerms actionCode="04">

               <CurrencyCode>USD</CurrencyCode>

               <PriceDateTime timeZoneCode="UTC">2015-05-07T13:58:00Z</PriceDateTime>

               <GrossAmountIndicator>false</GrossAmountIndicator>

            </PricingTerms>        

            <Item actionCode="04">

               <ID>10</ID>

               <ProcessingTypeCode>TPTM</ProcessingTypeCode>

               <ReleaseToExecute>false</ReleaseToExecute>

               <ItemProduct actionCode="04">

                  <ProductInternalID>S200102</ProductInternalID>

               </ItemProduct>

               <ItemScheduleLine actionCode="04">

                  <ID>1</ID>

                  <TypeCode>1</TypeCode>

                  <Quantity unitCode="HUR">5.0</Quantity>

               </ItemScheduleLine>

            </Item>

         </SalesOrder>

      </glob:SalesOrderBundleMaintainRequest_sync>

   </soapenv:Body>

</soapenv:Envelope>

B2B Collaboration for Sales Orders

Using B2B integration scenarios you can replace mail or e-mail based communication with your business partners by an automated message-based business document exchange.

B2B communication scenarios can be configured in work center view “Communication Arrangements”. Using B2B messages as output channel can be configured in the corresponding business partner master (for work center Business Partner Data, work center view Accounts) on page “Communication”. This means you can decide which output channel shall be used per business partner and business document.

SAP Business ByDesign B2B inbound channels and B2B outbound channels are aligned, such that B2B communication scenarios can be easily configured with mapping or development efforts, if both communication parties (buyer and seller) use SAP Business ByDesign.

You find more information about integration scenarios on SAP Help > Integration > Integration Scenarios.

In context of sales scenarios the following communications might be interesting:

		Seller side:		Buyer side:
Communication Partner:	Business Document Flow:	ByD Interface:	ByD Communication Scenario:	ByD Interface:	ByD Communication Scenario:
Buyer business partner >> Seller Company in ByD	Purchase Order >> Sales Order	Sales Order Inbound (SAP ESD)	Sales Order Integration	Purchase Order	Purchase Order Integration
Seller Company in ByD >> Buyer business partner	Sales Order Confirmation >> Purchase Order Acknowledge-ment	Sales Order Confirmation Outbound (SAP ESD)	Sales Order Integration	Purchase Order Acknowledge-ment	Purchase Order Integration
Seller Company in ByD >> Buyer business partner	Advanced Shipping Notification (ASN) >> Advanced Shipping Notification (ASN)	Outbound advanced shipping notification (SAP ESD)	Output of Advanced Shipping Notification	Inbound advanced shipping notification (SAP ESD)	Input of Advanced Shipping Notification
Seller Company in ByD >> Buyer business partner	Customer Invoice >> Supplier Invoice	Customer Invoice Outbound (SAP ESD)	Output of Customer Invoices	Supplier Invoice (SAP ESD)	Input of Supplier Invoices

Most B2B interfaces support 2 application protocols: SAP NetWeaver XI 3.0 and Web Service (Plain Soap). You can choose the application protocol in the technical data of the ByD communication arrangement: Enter ‘1’ for SAP NetWeaver XI 3.0 or enter ‘5’ for Web Service (Plain Soap) in field “Application Protocol”.

Please note: SAP NetWeaver XI 3.0 and Web Service use different endpoints. Please make sure the protocol selected fits to the endpoint used.

If you use the protocol Web Service (Plain Soap) you can use message ID and queue ID in order to archive exactly once in order processing (EOIO). Message ID and queue ID can be transferred as Soap header fields according the WS Addressing standard or as parameter in the web service URL.

You find a detailed description how to setup the B2B communication scenario "Sales Order Integration" in blog post Setup B2B Sales Order Integration with SAP Business ByDesign.

For example:
https://my338338.sapbydesign.com/sap/bc/srt/scs/sap/salesorderprocessingorderingi1?MessageId=989C6E5C-4672-2CC1-11CA-A044-08002B1BB4F5&QueueId=MyQueue123

Example for a B2B message to receive a sales order (Sales Order Inbound):

Business partner in ByD representing the Buyer (sender of the message):

Business partner ID: BAUS

GLN: 898989

Company in ByD representing the Seller (recipient of the message):

Company ID: 1000

Business partner ID (of company): 1000000

GLN: 767676

Sample xml request:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">

	<soap:Header/>

	<soap:Body>

		<glob:PurchaseOrderRequest>

			<MessageHeader>

				<!-- Unique message ID provided by the sender -->

				<ID>KH123</ID>

				<ReferenceID schemeAgencyID="898989" schemeAgencySchemeAgencyID="9" schemeID="ORDER">ABC0100</ReferenceID>

				<!-- Sender date time in UTC, ISO format -->

				<CreationDateTime>2017-12-11T10:06:00.440117Z</CreationDateTime>

				<!-- Sender party refering to the business partner representing the sender (here: the buyer) -->

				<!-- Must be the same as used in the communication arrangement -->

				<SenderParty>

					<!-- Standard ID (GLN) of ByD business partner acting as buyer -->

					<!-- Scheme agency IDs: 9 GLN, 16 DUNS -->

					<StandardID schemeAgencyID="9">898989</StandardID>

				</SenderParty>

				<!-- Receiver party refering to the business partner representing the receiver (here: the seller) -->

				<!-- Must be the same as used in the communication arrangement -->

				<RecipientParty>

					<!-- Standard ID (GLN) of ByD company acting as seller -->

					<!-- Scheme agency IDs: 9 GLN, 16 DUNS -->

					<StandardID schemeAgencyID="9">767676</StandardID>

				</RecipientParty>

				<!-- Business Scope Type Code: 2 sending process, 3 receiving process -->

				<!-- Business Scope ID: 97 Purchase Order Processing at Customer, 7 Sales Order Processing -->

				<BusinessScope>

					<TypeCode listID="25201" listAgencyID="310">2</TypeCode>

					<ID schemeID="10555" schemeAgencyID="310">97</ID>

				</BusinessScope>

				<BusinessScope>

					<TypeCode listID="25201" listAgencyID="310">3</TypeCode>

					<ID schemeID="10555" schemeAgencyID="310">7</ID>

				</BusinessScope>

			</MessageHeader>

			<PurchaseOrder reconciliationPeriodCounterValue="1" itemListCompleteTransmissionIndicator="true">

				<ID>KH-11</ID>

				<BuyerParty>

					<!-- Buyer IDs: Business Partner Internal ID: BAUS, GLN: 898989, DUNS: <n.a.> -->

					<StandardID schemeAgencyID="9">898989</StandardID>

					<!-- <SellerID>BAUS</SellerID> -->

					<!-- Type codes: 147 Business Partner, 154 Company, 159 Account, 167 Employee, 200 Organizational Unit, 251 Sales Unit, 266 Supplier -->

					<TypeCode>147</TypeCode>

				</BuyerParty>

				<SellerParty>

					<!-- Seller IDs: Company ID: 1000, GLN: 767676, DUNS: <n.a.> -->

					<StandardID schemeAgencyID="9">767676</StandardID>

					<!-- <SellerID>1000</SellerID> -->

					<TypeCode>154</TypeCode>

				</SellerParty>

				<TextCollection actionCode="01">

					<Text actionCode="01">

						<TypeCode>10024</TypeCode>

						<ContentText languageCode="EN">Customer Info: Sales Order created via B2B message</ContentText>

					</Text>

				</TextCollection>

				<Item actionCode="01">

					<ID>1</ID>

					<Product>

						<BuyerID>S200112</BuyerID>

						<SellerID>S200112</SellerID>

						<TypeCode>2</TypeCode>

					</Product>

					<ScheduleLine>

						<ID>1</ID>

						<DeliveryPeriod>

							<StartDateTime timeZoneCode="EST">2017-12-11T04:00:00Z</StartDateTime>

							<EndDateTime timeZoneCode="EST">2017-12-12T04:00:00Z</EndDateTime>

						</DeliveryPeriod>

						<Quantity unitCode="EA">1</Quantity>

					</ScheduleLine>

				</Item>

			</PurchaseOrder>

		</glob:PurchaseOrderRequest>

	</soap:Body>

</soap:Envelope>

Create ByD Sales Orders using Web Services

Sales Order Web Service APIs

Create Sales Orders and change the Item Price

Internet Orders / eCommerce Integration

Delete Sales Orders

Calculate Prices and Check Availability w/o Sales Order

External Payments

Sales Order with reference to marketing campaigns

B2B Collaboration for Sales Orders

Useful documents on SCN

Evolution of ABAP

Analytics in S/4HANA - real shape of embedded analytics and beyond embedded analytics