Skip to Content

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 change the item price in a second web service call and overwrite the calculated price components.

The steps to be performed are basically:

  1. Create order with all data except prices
  2. Update the order item price

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

Update the item main price:

  1. Create SO
  2. Update SO item main price

Update price component using the price component key:

  1. Create SO
  2. Query SO and get price component UUID
  3. Update SO price component with the given price component UUID from step 2.

Update price component using the price component type:

  1. Create SO
  2. 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>

 

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

  • Yes (in scope), then releasing the provisional internet order results in a sales order in status “Open“.
  • No, 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>

 

 

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:

Communication Partner: Business Document Flow: ByD Interface on seller side: ByD Communication Scenario on seller side: ByD Interface on buyer side: ByD Communication Scenario on buyer side:
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 Acknowledgement Sales Order Confirmation Outbound (SAP ESD) Sales Order Integration Purchase Order Acknowledgement Purchase Order Integration
Seller Company in ByD >> Buyer business partner 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.

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:

  • Business partner name: ExternalBupa
  • Business partner ID: 100000021
  • GLN: 1111111111

Company in ByD representing the Seller:

  • Company name: MyCompany
  • Company ID: MYCOMP
  • Business partner ID (of company): 2000000000
  • GLN: 2222222222

Sample xml request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://www.w3.org/2005/08/addressing">
	<soapenv:Header>
		<wsa:MessageID>uuid:14ad265f-e44a-44b2-bafb-0324d6ab3c40</wsa:MessageID>
	</soapenv:Header>
	<soapenv:Body>
		<ns0:PurchaseOrderRequest xmlns:ns0="http://sap.com/xi/SAPGlobal20/Global">
			<MessageHeader>
				<ID>1234</ID>
				<ReferenceID schemeAgencyID="1111111111" schemeAgencySchemeAgencyID="9" schemeID="ORDER">ABC0100</ReferenceID>
				<CreationDateTime>2013-01-16T18:52:00Z</CreationDateTime>
				<SenderParty>                                
					<!-- Business partner in ByD representing ExternalBupa -->
					<!-- <InternalID schemeAgencyID="310" schemeID="CommunicationPartyID">100000021</InternalID> -->
					<StandardID schemeAgencyID="9">1111111111</StandardID>
				</SenderParty>
				<RecipientParty> 
					<!-- Company in ByD representing MyCompany -->
					<!-- Standard ID schemeAgencyID: 009 GLN, 016 DUNS -->
					<StandardID schemeAgencyID="9">2222222222</StandardID>
				</RecipientParty>
				<!-- Type Code: 2 sending process, 3 receiving process -->
				<!-- ID: 97 Purchase Order Processing at Customer, 7 Sales Order Processing -->
				<BusinessScope>
					<TypeCode listAgencyID="310" listID="25201">2</TypeCode>
					<ID schemeAgencyID="310" schemeID="10555">97</ID>
				</BusinessScope>
				<BusinessScope>
					<TypeCode listAgencyID="310" listID="25201">3</TypeCode>
					<ID schemeAgencyID="310" schemeID="10555">7</ID>
				</BusinessScope>
			</MessageHeader>
			<PurchaseOrder itemListCompleteTransmissionIndicator="true" reconciliationPeriodCounterValue="01">
				<ID>ABC0100</ID>
				<BuyerParty>
					<SellerID>2000000000</SellerID>
					<TypeCode>154</TypeCode>
				</BuyerParty>
				<SellerParty>
					<StandardID schemeAgencyID="16">1111111111</StandardID>
					<TypeCode>154</TypeCode>
				</SellerParty>
				<TextCollection>
					<Text>
						<TypeCode>10011</TypeCode>
						<ContentText>Test: create Sales Order via web service</ContentText>
					</Text>
				</TextCollection>
				<Item actionCode="1">
					<ID>000001</ID>
					<Product>
						<SellerID>P1001</SellerID>
						<TypeCode>1</TypeCode>
					</Product>
					<Price>
						<NetAmount currencyCode="EUR">1234.50</NetAmount>
					</Price>
					<!--
					<ProductRequirementSpecification>
						<InternalID>PRS-1000-0001</InternalID>
					</ProductRequirementSpecification>
					-->
					<ScheduleLine>
						<ID>1</ID>
						<DeliveryPeriod>
							<StartDateTime timeZoneCode="UTC">2013-01-22T00:00:00Z</StartDateTime>
							<EndDateTime timeZoneCode="UTC">2013-01-27T00:00:00Z</EndDateTime>
						</DeliveryPeriod>
						<Quantity unitCode="EA">16.000</Quantity>
					</ScheduleLine>
				</Item>
			</PurchaseOrder>
		</ns0:PurchaseOrderRequest>
	</soapenv:Body>
</soapenv:Envelope>

 

To report this post you need to login first.

Be the first to leave a comment

You must be Logged on to comment or reply to a post.

Leave a Reply