Show full documentation

 Show full documentation

Definition

An interface to migrate or create a Over the counter sales transactions from a source system or file.

Business Context and Use

The web service interface Manage Over-the-Counter sales Request In enables you to connect external applications to your SAP Business By Design system and to create and edit Over-the-counter sales transactions in your system.

The web service interface Manage Over-the-Counter sale trnasactions In offers the operation MaintainBundle.

Here is an example of a simple web service request:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">
<soapenv:Header />
<soapenv:Body>
<glob:OvertheCounterSalesRequestBundleMaintainRequest_sync>
 <BusinessDocumentBasicMessageHeader>
  <ID schemeID="" schemeAgencyID="" schemeAgencySchemeAgencyID=""> 123456789</ID>
 </BusinessDocumentBasicMessageHeader>
 <OverTheCounterSaleRequest>
  <BaseBusinessTransactionDocumentID>OTC ID</BaseBusinessTransactionDocumentID>
  <BuyerParty>
   <InternalID>MC9785</InternalID>
  </BuyerParty>
  <SalesUnitParty>
   <InternalID>MC42111</InternalID>
  </SalesUnitParty>
  <SalesAndServiceBusinessArea>
   <DistributionChannelCode>02</DistributionChannelCode>
  </SalesAndServiceBusinessArea>
  <EmployeeResponsibleParty>
   <InternalID>MC2471</InternalID>
  </EmployeeResponsibleParty>
  <ShipFromLocation>
   <InternalID>MC64920</InternalID>
  </ShipFromLocation>
  <PricingTerms>
   <PricingProcedureCode>PPSTD1</PricingProcedureCode>
   <CurrencyCode>USD</CurrencyCode>
  </PricingTerms>
  <Item>
   <BaseBusinessTransactionDocumentItemID>10</BaseBusinessTransactionDocumentItemID>
   <BaseBusinessTransactionDocumentItemTypeCode>002</BaseBusinessTransactionDocumentItemTypeCode>
   <SettlementRelevanceIndicator>true</SettlementRelevanceIndicator>
   <BaseItemCancelledIndicator>false</BaseItemCancelledIndicator>
   <ReceivablesPropertyMovementDirectionCode>2</ReceivablesPropertyMovementDirectionCode>
   <Product>
    <InternalID>MCF-0001</InternalID>
    <TypeCode>1</TypeCode>
   </Product>
   <CashDiscountDeductibleIndicator>true</CashDiscountDeductibleIndicator>
   <Quantity unitCode="EA">1</Quantity>
   <QuantityTypeCode>EA</QuantityTypeCode>
   <PriceAndTax>
    <PriceComponent>
     <TypeCode>7PR1</TypeCode>
     <Rate>
      <DecimalValue>500</DecimalValue>
      <CurrencyCode>USD</CurrencyCode>
      <BaseDecimalValue>1</BaseDecimalValue>
      <BaseMeasureUnitCode>EA</BaseMeasureUnitCode>
     </Rate>
    </PriceComponent>
   </PriceAndTax>
  </Item>
 </OverTheCounterSaleRequest>
 <glob:OvertheCounterSalesRequestBundleMaintainRequest_sync>
</soapenv:Body>
</soapenv:Envelope>

Prerequisites

Existence of referenced business documents:

The following business entities are only referenced and will not be created by the service operations. They must already exist in the system when the web service is called up. If not, the created Over-the-Counter Sales request will show inconsistencies:

Organisational Data (Parties, SalesUnit)

Products

Constraints and Integrity Conditions

The operation MaintainBundle supports exactly one execution (idem potency). To ensure exactly one execution of web service requests, the web service consumer has to provide unique values for the elements ID or UUID of the MessageHeader and BasicMessageHeader node element.

More Information

General Information

You can find general information about Web services, their structure and consumption in the Web Services documentation.

Scenarios

Possible scenarios include the following:

create or update Over-the-Counter sale requests.

The operation MaintainBundle is used to create or update Over-the-Counter Sale requests.

The key is the BaseBusinessTransactionDocumentID and the system reads the existing data. If a Over-the-Counter sale requests for this ID exits, the entry will be updated, otherwise the system creates a new Over-the-Counter sale request for this BaseBusinessTransactionDocumentID.

 Show full documentation

 Show full documentation

Definition

To check if Over-the-Counter Sales requests can be created updated, or cancelled without errors

Business Context and Use

The web service request and response message types for the CheckMaintainOTCBundle operation are the same as those of the MaintainOTCBundle operation. The explanations given can therefore also be applied to the CheckMaintainOTCBundle operation.

 Show full documentation

 Show full documentation

Definition

To create, update, or cancel Over the counter sales request in the SAP Business ByDesign System.

Business Context and Use

The request message of the operation MaintainBundle contains a BasicMessageHeader node element as well as a OvertheCounterSale request node element that can occur multiple times. That is multiple Over-the-Counter-Sales requests can be created and updated with a single web service request. The OvertheCounterSales node element contains the Over-the-Counter-Sales data to be created or updated. The detailed structure of the Over-the-Counter-Sales request node will be explained in the following sub-chapters.

Structure

The structure of the request message has the following nodes and elements:

OvertheCounterSalesRequest

The OvertheCounterSalesRequest node element contains all general information, such as BaseBusinessTransactionDocumentID which is the keyfield.

• Name

  The attribute Name corresponds to the UI Field Description.

• SettlementBlockedIndicator

  The SettlementBlockedIndicator indicates whether the Over-the-Counter Sales request has to be blocked. If it is set to true, all items will be blocked for invoicing.

• BaseCancelledIndicator

  The BaseCancelledIndicator indicates whether the Over-the-Counter Sales Request has to be cancelled. If it is set to true, all items will be cancelled.

• SettlementPriorityCode

  By setting the settlement priority code the creation of a customer invoice is triggered for the Over-the-Counter Sales request.

Code Value	Description
1	Immediate - create the customer invoice if the Over-the-Counter Sale request can be invoiced

• ProposedInvoiceDate

  The attribute ProposedInvoiceDate will define the InvoiceDate and is set to current date if no value is passed. During the creation of the customer invoice the invoice date can be overwritten.

• ProposedDeviatingPostingDate

  This date is used for a deviating posting date in financials. The default posting date is the ProposedInvoiceDate

Organisational Data

• BuyerParty (mandatory)

  A party (Customer) that purchases goods or services.

• ProductRecipientParty (optional)

  A party (Customer) that receives goods or services.

• BillToParty (optional)

  A party (Customer) that receives the invoice for goods or services.

• BillFromParty (mandatory)

  A party (Company) that carries out the billing process.

• SalesUnitParty (mandatory)

  A party (Functional Unit) that is responsible for the customer invoice request.

• PayerParty (optional)

  A party (Customer) that is requested to pay the payables from the delivery of goods or the provision of services or that is the recipient of a credit memo.

• EmployeeResponsibleParty (optional)

  A party (Employee) that is responsible for the Over-the-Counter Sales request.

• SalesAndServiceBusinessArea

  • DistributionChannelCode

    A distribution channel is a channel through which goods or services reaches the customer.

Code Value	Description
01	Direct sales
02	Indirect sales

• ShipFromLocation(mandatory)

  A Location that is to deliver the products from supplier.

Price and Financial Data

• CashDiscountTerms

  CashDiscountTerms are an agreement of cash discounts for a payment.

  • Code

    A user-specific code list is assigned to the CashDiscountTermsCode. A user defines the codes in the code list.

• PaymentControl

  • PaymentFormCode

Code Value	Description
04	Direct Debit
02	Credit Card
09	Cash
20	External Payment

• PricingTerms

  Pricing Terms are agreements in the sales process, which are required exclusively to determine the net value of the Over-the-Counter Sales request.

  • CurrencyCode

    A coded representation of the currency in which the invoice is issued (invoice currency).

  • ProvisionDate

    The provision date is the pricing and taxation relevant date when goods are delivered or services provided.

  • PricingProcedureCode

    A coded representation of the procedure how price components are supposed to be calculated in the Over-the-Counter Sales request.

    The following pricing procedure was delivered by SAP:

Code Value	Description
PPSTD1	Standard Procedure
PPGP02	Standard Gross Procedure

Text

The TextCollection node element can be used to maintain customer information and internal comments.

Possible text type codes includes the following:

Type code	Description
10011	Internal Comment
10024	Customer Information

Item

The item node element contains all general information on OvertheCounterSalesRequest items, such as BaseBusinessTransactionDocumentItemID which is the keyfield.

General Data on Item Level

• BaseItemCancelledIndicator

  If the indicator is set to true or the BaseCancelledIndicator on OvertheCounterSalesRequest Node is set to true, the item will be cancelled. If both indicators are set to false and the item is cancelled, the cancellation will be revoked.

• SettlementBlockedIndicator

  If the indicator is set to true or the SettlementBlockedIndicator on OvertheCounterSalesRequest node is set to true, the item will be blocked. If both indicators are set to false and the item is blocked, the system triggers an unblock.

• BaseItemInvoicingBlockingReasonCode

  A coded representation of the reason why invoicing has been blocked by the underlying business document.

Code Value	Description
01	Calculation missing
02	Confirmation still open
03	Pricing incomplete

• CancellationReasonCode

  A coded representation of the reason why the item has been cancelled.

Code Value	Description
01	Delivery too late
02	Quality issues
03	Too expensive
04	Competitor cheaper
05	Competitor better quality
06	Customer to receive replacement
07	Warranty
08	Other reason

• Description

  Description of the item

• CashDiscountDeductibleIndicator

  Indicator that the cash discount may be deducted for this item.

• Product

  • InternalID

    Identification of the product.

  • TypeCode

    A coded representation of a product type, such as a material.

  • SerialID

    A serial number identifies a particular item that enables you to distinguish between individual pieces.

    The quantity of item will get updated based on serial number Ids for the product which have serial number profile enabled.

  • Identified Stock ID

    An identified stock ID is a unique identifier to separate quantities of a product that are produced at the same time, with the same production parameters, and with the same characteristics.

• Quantity

  The total quantity of goods or services to be invoiced. The quantity consists of a unitCode and the content.

• QuantityTypeCode

  A unit is not sufficient to define the type of a quantity, because a unit can be used in multiple types. For example, the unit 'kg' can be used in quantity types for gross weight or net weight. On the other hand, the multiple units are valid for one quantity type. The quantity type gross weight can be expressed with units such as 'kg' or 'gram'. The quantity type is therefore needed in addition to the unit to define a quantity completely.

Price and Tax Data on Item Level

The price and tax data, such as price, discounts, surcharges, tax codes or the tax date can be set from the external system. If no values are provided, the system uses the values that are set from the internal price and tax calculation.

If an item is cancelled, you cannot maintain the price and tax data. As for an item with status 'cancelled', the price and tax data must not be changed.

Node PriceAndTax

The node PriceAndTax contains the node PriceComponent and TaxCountryCode.

TaxCountryCode can be spcified if the tax country is to be overriden by a value other than the country determined by the system

  <TaxCountryCode>DE</TaxCountryCode>
 

A PriceComponent consists of a Rate and a TypeCode.

The TypeCode is the specification of a price, a discount, or a surcharge and depends on the PricingProcedureCode.

The description depends on the entries that are set in the fine-tuning activity. The following descriptions are the defaulted values from SAP:

PricingProcedureCode	Code Value	Description
PPSTD1	7PR1	List Price
PPSTD1	7PR2	Surcharge (%)
PPSTD1	7PR3	Surcharge
PPSTD1	7PR6	Product Discount (%)
PPGP02	8PR1	Gross List Price
PPGP02	8PR2	Gross Surcharge (%)
PPGP02	8PR3	Gross Surcharge
PPGP02	8PR6	Gross Discount (%)

The type of the rate depends on the price component and can be an amount for the list price or a percent value for the product discount. For the price components with type 'percent' you cannot maintain the currency.

In the Update Scenario only the active price components were updated. If a price component is

inactive. For example, due to errors in currency or quantity conversion, a new price component will be created.

If there are several price components for a specific type code, the exceeding price components will be deleted and the document will contain the price components that are set in the external system.

If a type code is not set from the external system, the internal calculated price components will remain unchanged.

Below is an example for a gross list price and a discount for pricing procedure PPGP02:

    <PriceAndTax>
     <PriceComponent>
      <TypeCode>8PR1</TypeCode>
      <Rate>
       <DecimalValue>100</DecimalValue>
       <CurrencyCode>USD</CurrencyCode>
       <BaseDecimalValue>1</BaseDecimalValue>
       <BaseMeasureUnitCode>EA</BaseMeasureUnitCode>
      </Rate>
     </PriceComponent>
     <PriceComponent>
      <TypeCode>8PR6</TypeCode>
      <Rate>
       <DecimalValue>25</DecimalValue>
      </Rate>
     </PriceComponent>
    </PriceAndTax>

Node ProductTaxDetails

The node ProductTaxDetails contain the TaxationCharacteristicsCode that is determined internally but can be changed externally.

The tax code depends on the country and represents the tax event, tax type and tax rate type. The tax event controls how taxes are posted in the tax return.

The common tax codes for Country US and DE are:

ListID	Code Value	Description
DE	500	Non-Taxable Sale
DE	501	Domestic Supply (Standard Rate)
DE	502	Domestic Supply (Reduced Rate)
DE	503	Domestic Supply (Exempt)
DE	504	Export of Service, Reverse Charge
DE	507	Intra-Community Supply
DE	508	Export to Third Country
DE	514	Non-Taxable Sale Within Tax Reporting Group
DE	530	EU Sale of Services, Reverse Charge
US	500	Non-Taxable Sales (Out of Scope of Law)
US	501	Sales Tax - Standard Rate
US	502	Sales Tax - Exempt
US	503	Sales Tax (Special Rate: Food)
US	504	Sales Tax (Special Rate: Health Care)
US	505	Sales Tax (Special Rate: Clothing)
US	506	Sales Tax (Special Rate: Other)
US	507	Non-Taxable Sales Under Nexus Rules
US	514	Exempt Sale by Other Reason
US	515	Export
US	522	Non-Taxable Sale Within Tax Reporting Group

Node TaxationTerms

The node TaxationTerms contains the tax date. This date is used for tax rate determination and calculation and defaults the date for exchange rate determination and the tax due date. If the tax date is not supplied, the invoice date is used as the tax date.

Organisational Data on Item Level

• ProductRecipientParty (optional)

  A party (Customer) that receives a good or a service.

Text on Item Level

The TextCollection node element can be used to maintain customer information and internal comments on item level.

Possible text type codes include the following:

Type code	Description
10011	Internal Comment
10024	Customer Information

Product Data on Item Level

The Product data, such as Internal ID (Product ID), Serial ID and Identified Stock ID can be set from the external system.

IdentifiedStockID

The node Identified Stock ID, is not mandatory always. If a product does not have a specific Identified Stock Type maintained in the system, an external update on this node is not allowed. Sales kit headers are not applicable to Identified Stock Types, which means an external update on IdentifiedStockID is not allowed for them too.

If a product's Identified Stock Type is batch or mandatory, an update of the Identified Stock ID for that product is mandatory.

Below is an example for maintaining Identified Stock ID of a product: -

    <Product>
        <InternalID>xyz</InternalID>
        <IdentifiedStockID>123</IdentifiedStockID>
    </Product>

When Over-the-Counter-Sales requests are created for Sales Kits, the Identified Stock IDs for Sales Kit sub-items (as sales kit headers are not applicable to Identified Stock) are not meant to be set, during creation. They can be updated later, by calling an update on the existing Over-the-Counter-Sale request document. It is mandatory to specify the item id, product internal id and the identified stock id (as per the identified stock type of the product) for such an update.

Below is an example for updating Identified Stock ID of a sales kit sub-item: -

<Item actionCode="04">
               <BaseBusinessTransactionDocumentItemID>20</BaseBusinessTransactionDocumentItemID>
   <Product>
       <InternalID>MCF-0001-PAL</InternalID>
       <IdentifiedStockID></IdentifiedStockID>
   </Product>
   <CashDiscountDeductibleIndicator>true</CashDiscountDeductibleIndicator>
   <Quantity unitCode="EA">5</Quantity>
   <QuantityTypeCode>EA</QuantityTypeCode>
   <AccountingCodingBlockAssignment>
    <AccountingCodingBlock>
     <GeneralLedgerAccountAliasCode>A-1600</GeneralLedgerAccountAliasCode>
    </AccountingCodingBlock>
   </AccountingCodingBlockAssignment>
  </Item>

Revenue Assignment on Item Level

The revenue assignment can be set from the external system by filling the Node AccountingCodingBlock that is a SubNode of AccountingCodingBlockAssignment.

• GeneralLedgerAccountAliasCode

  The GeneralLedgerAccountAliasCode is a coded representation of an alias for a General Ledger account.

OvertheCounterSalesRequestResponse

Over-the-Counter Sales Request ID and UUID

Change State ID and Sender Techinical ID

Log: Containing the error messages from the processing of the request.