SOAP API Invocation of Billable Item Creation and Provider Contract Creation

[gary_yao]

Purpose

SAP Billing and Revenue Innovation Management solution is the solution with capabilities of the revenue management and recurring billing used to monetize subscription and usage-based business models, extensively used by customers around the world at Cloud. Considering the variant customer-owned-system and variant scenario can be seamlessly integrate with SAP Billing and Revenue Innovation Management solution at SAP S/4HANA Cloud. SAP offers a wide range of APIs to enable the data replication / scenario extension between SAP System & SAP System and SAP System & Non-SAP System.

In this blog post, it will demonstrate the way on how to consume the communication arrangement inbound service of SAP S/4HANA Cloud by invoking the SOAP API through SoapUI to create Billable Item and Provider Contract.

Preparation

Before we start to consume the SAP SOAP API, please make sure the communication user, the communication system and Communication Arrangement are well configured. You may follow the blog post https://blogs.sap.com/2017/11/09/setting-up-communication-management-in-sap-s4hana-cloud/ to make it step by step. In our case, the communication scenario of SAP_COM_0165 and SAP_COM_0167 are used.

SAP API Business HUB http://api.sap.com is the place for API storage. You can search out the details of the SOAP API you want to consume.

1. Launch the SAP API Business HUB from http://api.sap.com

2. Search SOAP API of Billable Item

3. Click the link Convergent Invoicing Billable Items - Create - Request (Single) to retrieve the details of the SOAP API

Similarly enter  SAP_COM_0167 as the search keyword, and you can locate the SOAP API of Provider Contract - Manage

Billable Item Creation

1. Login the SAP S/4HANA Cloud as Administrator and open the communization arrangement of communication scenario SAP_COM_0165 to download the WSDL file of SOAP API Convergent Invoicing Billable Items - Create - Request (Single)

2. Create Project based on the WSDL file at SoapUI

3. Maintain the authorization and security related configuration based on the communication user of SAP_COM_0165.

4. Maintain the message id to consume asynchronous processing

5. Maintain the value as below to simulate the SOAP API

BillableItemBasicCreate

Elements	Description	Sample Value	Comments
CABllbleItmSourceTransType	Source Transaction Type	01           External Assignment of Source Transaction ID 02              Internal Assignment of Source Transaction ID	If fill 01, the source transaction id will be automatically assigned by system.
CABllbleItmSourceTransId	Source Transaction ID	Eg: 56789
CABllbleItmClass	Billable Item Class	0SAP
CABillgSubprocess	Subprocess of Billing	Eg: Y001
BusinessPartner	Business Partner Number for Billing and Invoicing	Business Partner Number	Please refer to Test Script 2AR Contract Accounting - Master Data and Basic Functions for more details
ContractAccount	Contract Account Number for Billing and Invoicing	Contract Account Number	Please refer to Test Script 2AR Contract Accounting - Master Data and Basic Functions for more details
CABllbleItmAmount	Amount of Billable Item	Eg: currencyCode: EUR CABllbleItmAmount: 12

Provider Contract Creation

1. Login the SAP S/4HANA Cloud as Administrator and open the communization arrangement of communication scenario SAP_COM_0167 to download the WSDL file of SOAP API Provider Contract - Manage

2. Open your tool for API testing, e.g. SoapUI and import the WSDL file and create a new project.

3. Maintain the authorization and security related configuration based on the communication user of communication arrangement for SAP_COM_0167

4. Fill the values in the editor. Below are some explanations of the elements and sample values.

 

MessageHeader

Element	Description	Sample Value	Comment
CreationDateTime	the date and time for the provider contract creation	2019-12-03T02:53:45Z

ProviderContract

Element	Description	Sample Value	Comment
SenderTechnicalID	the technical id for the API sender	SenderOne

 

Header

Element	Element	Description	Sample Value	Comment
Identification	InternalID	the provider contract id. The number range is defined in S/4 system.	API1575341697069	Should be unique in the system.
BusinessPartner	InternalID	the business partner used in the provider contract which should be available in S/4 before API testing	BP_DE_T1
CAProviderContractName		the name of the provider contract	Basic Provider Contract
CAPrvdrContrStartDateTime		the start date and time for the provider contract	2018-01-01T00:00:00Z	timeZoneCode needs to be filled, e.g. UTC
CAPrvdrContrEndDateTime		the end date and time for the provider contract	9999-12-31T00:00:00Z	timeZoneCode needs to be filled, e.g. UTC
CAPrvdrContrActivationDateTime		the activation date and time for the provider contract, usually the same as the start date	2018-01-01T00:00:00Z	timeZoneCode needs to be filled, e.g. UTC
CAPrvdrContrChangedDateTime		the changed date and time for the provider contract, usually used in Provider Contract change process	2018-01-01T00:00:00Z	timeZoneCode needs to be filled, e.g. UTC
IsMarkedForDeletion		the flag for deletion, 1 means deleted	0

ProviderContractItem

Element	Element	Description	Sample Value	Comment
CAProviderContractItemUUID		a 32-bit hexadecimal number (UUID) for the provider contract item which should be unique	A3BB2221288D4FFCB9C29F2DF541095D
CAPrvdrContrItmValidToDateTime		the valid-to date and time for the provider contract item	9999-12-31T00:00:00Z	timeZoneCode needs to be filled, e.g. UTC
CAProviderContractItemText		a description text for the provider contract item	provider contract demo
CAPrvdrContrItmChangeReason		the reason for provider contract item change, not used for the creation step.		Empty for the provider contract creation
SalesOrganisation		the sales organization used in the provider contract	1010	The value should be available in S/4.
DistributionChannelCode		the distribution channel used in the provider contract	10	The value should be available in S/4.
Product		the provider used in the provider contract item	CBPTS001	The value should be available in S/4.
CABillgCycle		the billing cycle to determine the billing date for the items in steps afterwards	Y001	The value should be available in S/4.
ServiceRecipient	InternalID	the partner who receives the goods, works or services specified in the provider contract	BP_DE_T1
ContractAccount	InternalID	the contract account id	CA_DE_T1	The value should be available in S/4.

Elements for Revenue Accounting Integration



Below elements are mandatory if Revenue accounting integration is activated.

Element	Description	Sample Value	Comment
RevenueAccountingRefType	the reference type for Revenue Accounting	PO	Provider Order
RevenueAccountingReference	the reference ID for Revenue Accounting	API1575341697069	The same as the provider contract id
StandAloneSellingPrice	the standalone selling price for each recurring period	200	currencyCode needs to be filled, e.g. EUR
TransactionPrice	the transaction price for each recurring period	100	currencyCode needs to be filled, e.g. EUR
TransacPriceRcrrcPerdTimeUnit	the time unit for the recurring period of the transaction price	MONTH
TransacPriceRcrrcPerdDuration	the duration of each recurring period for the transaction price	1
SSPriceRecurrencePerdTimeUnit	the time unit for the recurring period of the standalone selling price	MONTH
SSPriceRecurrencePerdDuration	the duration of each recurring period for the standalone selling price	1
EndOfDurationDateTime	the end date of the recurring period	2020-12-31T00:00:00Z	timeZoneCode needs to be filled, e.g. UTC

Optional: Elements for Billing Plan

These elements are optional. They are only used if billing plan is needed in the provider contract.

BillingPlanHeader

Element	Description	Sample Value	Comment
CABillgPlnExtRef	the external reference text of the billing plan assigned to current provider contract	BIP01
CABillgPlnType	the billing plan type, need to be checked in S/4	SPL01
CABillgPlnDescription	the description text for the billing plan	API test

 

BillingPlanItem

Element	Description	Sample Value	Comment
CABillgPlnItmType	the billing plan item type, need to be checked in S/4	YRECU	The value should be available in S/4.
CABillgPlnItmTxt	the description text for the billing plan item	Recurring Item
CABillgPlnItemExtRef	the external reference text of the billing plan item	1
CABillgPlnItemAmount	the amount to be billed for the billing plan item	30	currencyCode needs to be filled, e.g. EUR
IsTaxIncluded	the flag whether tax is already included in the amount	0
CATaxDeterminationCode	the tax determination code, need to be checked in S/4
TaxCode	the tax code, need to be checked in S/4	A1	The value should be available in S/4.
CompanyCode	the company code, need to be checked in S/4	1010	The value should be available in S/4.
Segment	the segment, need to be checked in S/4	1000_A	The value should be available in S/4.
CAMainTransaction	the main transaction for the item to be billed	Y600	The value should be available in S/4.
CASubTransaction	the subtransaction for the item to be billed	0020	The value should be available in S/4.
CAAccountDeterminationCode	the account determination code	01
CABillgPlnItemServiceType	the service type for the billing plan item		The value should be available in S/4.

Optional: Elements for configurable products

These elements are optional. They are only used if the product used is a configurable product.

ProductConfigurationHeader

Element	Description	Sample Value	Comment
Configuration	the id for the product configuration header	000001
ConfigurationRootInstance	the id for the configuration root instance	00000001

ProductConfigurationInstance

Element	Description	Sample Value	Comment
Configuration	the id for the product configuration header	000001	Fill the identical value as the Configuration in ProductConfigurationHeader.
ConfigurationInstance	the id for the configuration instance	00000001
ClassType	the class type for the configuration product, can be found in material master	300	The value should be available in S/4.
Product	the material number for the product	CBPTS001	The value should be available in S/4.
ProductQuantity	the quantity of the product	1

ProductConfigurationValue

Element	Description	Sample Value	Comment
Configuration	the id for the product configuration header	000001	Fill the identical value as the Configuration in ProductConfigurationHeader and ProductConfigurationInstance
ConfigurationInstance	the id for configuration instance	00000001	Fill the identical value as the ConfigurationInstance in ProductConfigurationInstance

 

Now the Billable Item and Provider Contract can be created successfully through SOAP API Convergent Invoicing Billable Items - Create - Request (Single) and Provider Contract - Manage.