Technical Articles
How to create ERS Invoices using ByD Web Service APIs
SAP Business ByDesign supports Supplier Invoice Processing using Evaluated Receipt Settlements (ERS Invoices).
In general you have three possibilities to create ERS invoices:
- You create a ERS purchase order and schedule an ERS run. As result ByD generates ERS invoices automatically.
- You create a “Manual ERS Invoice” via UI work center “Supplier Invoicing” and common task “New ERS Invoice“
- You create a “Manual ERS Invoice with External Application” (aka “External ERS Invoice“) using web service ManageSupplierInvoiceIn.
You find more details in the ByD Help Center document “Supplier Invoice Processing Using Evaluated Receipt Settlements“.
How to create ERS invoices using web service API ManageSupplierInvoiceIn?
Creating an ERS Invoice via web service API ManageSupplierInvoiceIn is almost the same as creating other external invoices: You just have to add element ManualEntryERSIndicator = true to the web service request.
Example web service request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">
<soapenv:Header/>
<soapenv:Body>
<glob:SupplierInvoiceBundleMaintainRequest_sync>
<BasicMessageHeader>
<!--<UUID></UUID> required for idem potency-->
</BasicMessageHeader>
<SupplierInvoice actionCode="01" itemListCompleteTransmissionIndicator="false">
<ObjectNodeSenderTechnicalID>H1</ObjectNodeSenderTechnicalID>
<!--<ChangeStateID></ChangeStateID>-->
<!--004 invoice | 005 credit memo-->
<BusinessTransactionDocumentTypeCode>005</BusinessTransactionDocumentTypeCode>
<!--<SupplierInvoiceID></SupplierInvoiceID> ERS invoice use internal number ranges-->
<MEDIUM_Name>Supplier CM with deviating bank account</MEDIUM_Name>
<Date>2018-06-21</Date>
<ReceiptDate>2018-06-21</ReceiptDate>
<TransactionDate>2018-06-21</TransactionDate>
<DocumentItemGrossAmountIndicator>false</DocumentItemGrossAmountIndicator>
<ManualEntryERSIndicator>true</ManualEntryERSIndicator>
<!--ERS invoices: Gross amount and tax amount are calculated by the system-->
<!--<GrossAmount currencyCode="EUR">119</GrossAmount>
<TaxAmount currencyCode="EUR">19</TaxAmount>-->
<Status>
<!--2 = save SIV | 3 = post SIV-->
<DataEntryProcessingStatusCode>3</DataEntryProcessingStatusCode>
</Status>
<!--ERS invoice: There is no customer invoice-->
<!--<CustomerInvoiceReference actionCode="04">
<BusinessTransactionDocumentReference>
<ID>...</ID>
<TypeCode>28</TypeCode>
</BusinessTransactionDocumentReference>
</CustomerInvoiceReference>-->
<BuyerParty actionCode="01">
<PartyKey>
<PartyTypeCode>200</PartyTypeCode>
<PartyID>MDEC10000</PartyID>
</PartyKey>
</BuyerParty>
<SellerParty actionCode="01">
<PartyKey>
<PartyTypeCode>147</PartyTypeCode>
<PartyID>MDEC7000</PartyID>
</PartyKey>
</SellerParty>
<CashDiscountTerms>
<Code>0002</Code>
</CashDiscountTerms>
<!--Deviating bank account or payment block-->
<PaymentControl ActionCode="04" BankTransferListCompleteTransmissionIndicator="false">
<!--Payment methods: 04 Direct Debit (SEPA), 13 Direct Debit (Authorization for Payer’s Bank), 05 Bank Transfer-->
<!--The visibility of the Deviating Bank Information tab in the UI is controlled by the Payment Form Code = 05-->
<PaymentFormCode>04</PaymentFormCode>
<PaymentBlock>
<!--Payment Blocking Reason: 2 Complaint, 3 Payment method changed, 4 Other reason, ...-->
<PaymentBlockingReasonCode>2</PaymentBlockingReasonCode>
<ExpirationDateTime/>
<CreationDateTime/>
</PaymentBlock>
<!--Note: Payment reason-->
<Note languageCode="EN">My Note transfered along with the payment</Note>
<BankTransfer ActionCode="01">
<BusinessPartnerBankDetailsKey>
<ID>0001</ID>
</BusinessPartnerBankDetailsKey>
</BankTransfer>
</PaymentControl>
<TextCollection ActionCode="01" TextListCompleteTransmissionIndicator="true">
<Text ActionCode="01">
<TypeCode>10015</TypeCode>
<LanguageCode>EN</LanguageCode>
<TextContent ActionCode="01">
<Text languageCode="EN">Text on header level</Text>
</TextContent>
</Text>
</TextCollection>
<!--Item: invoice item with product category-->
<Item actionCode="01">
<ObjectNodeSenderTechnicalID>H1-I1</ObjectNodeSenderTechnicalID>
<ItemID>1</ItemID>
<!--002 invoice item | 003 credit memo item-->
<BusinessTransactionDocumentItemTypeCode>002</BusinessTransactionDocumentItemTypeCode>
<SHORT_Description languageCode="EN">Item Description of prod. category item</SHORT_Description>
<Quantity unitCode="EA">1</Quantity>
<NetAmount currencyCode="EUR">100</NetAmount>
<!--<GrossAmount currencyCode="EUR">100</GrossAmount>-->
<DeliveryPeriod>
<StartDateTime timeZoneCode="CET">2018-06-20T00:00:00Z</StartDateTime>
<EndDateTime timeZoneCode="CET">2018-06-21T00:00:00Z</EndDateTime>
</DeliveryPeriod>
<Product actionCode="01">
<CashDiscountDeductibleIndicator>false</CashDiscountDeductibleIndicator>
<!--<ProductCategoryStandardID></ProductCategoryStandardID>-->
<ProductCategoryIDKey>
<ProductCategoryHierarchyID>ROOT</ProductCategoryHierarchyID>
<ProductCategoryInternalID>10-10</ProductCategoryInternalID>
</ProductCategoryIDKey>
<ProductKey>
<ProductTypeCode>2</ProductTypeCode>
<ProductIdentifierTypeCode>1</ProductIdentifierTypeCode>
</ProductKey>
</Product>
<AccountingCodingBlockDistribution AccountingCodingBlockAssignmentListCompleteTransmissionIndicator="true" ActionCode="01">
<AccountingCodingBlockAssignment ActionCode="01">
<!--ACC, CC-->
<AccountingCodingBlockTypeCode>CC</AccountingCodingBlockTypeCode>
<!--<GeneralLedgerAccountAliasCode>A-7420</GeneralLedgerAccountAliasCode>-->
<CostCentreID>MDEC46000</CostCentreID>
</AccountingCodingBlockAssignment>
</AccountingCodingBlockDistribution>
<ProductTax actionCode="01">
<!--1 non-taxable | 2 stanadard tax-->
<ProductTaxationCharacteristicsCode listID="21801">1</ProductTaxationCharacteristicsCode>
<CountryCode>DE</CountryCode>
</ProductTax>
<MaintenanceTextCollection TextListCompleteTransmissionIndicator="true" ActionCode="01">
<!--Internal comment in English-->
<Text ActionCode="01">
<!--10011 internal comment | 10015 remark from supplier-->
<TypeCode>10015</TypeCode>
<LanguageCode>EN</LanguageCode>
<TextContent ActionCode="01">
<Text languageCode="EN">23 My internal comment: Hello World</Text>
</TextContent>
</Text>
<!--Remark from supplier in English-->
<Text ActionCode="01">
<!--10011 internal comment | 10015 remark from supplier-->
<TypeCode>10015</TypeCode>
<LanguageCode>EN</LanguageCode>
<TextContent ActionCode="01">
<Text languageCode="EN">Hello World</Text>
</TextContent>
</Text>
</MaintenanceTextCollection>
</Item>
<!--Item: credit memo item as free text item-->
<Item actionCode="01">
<ObjectNodeSenderTechnicalID>H1-I3</ObjectNodeSenderTechnicalID>
<ItemID>2</ItemID>
<!--002 invoice item | 003 credit memo item-->
<BusinessTransactionDocumentItemTypeCode>003</BusinessTransactionDocumentItemTypeCode>
<SHORT_Description languageCode="EN">Item Description of free text item</SHORT_Description>
<Quantity unitCode="EA">1</Quantity>
<NetAmount currencyCode="EUR">250</NetAmount>
<!--<GrossAmount currencyCode="EUR">150</GrossAmount>-->
<AccountingCodingBlockDistribution AccountingCodingBlockAssignmentListCompleteTransmissionIndicator="true" ActionCode="01">
<AccountingCodingBlockAssignment ActionCode="01">
<!--ACC, CC-->
<AccountingCodingBlockTypeCode>ACC</AccountingCodingBlockTypeCode>
<GeneralLedgerAccountAliasCode>A-7420</GeneralLedgerAccountAliasCode>
<!--<CostCentreID>GCCH-1300</CostCentreID>-->
</AccountingCodingBlockAssignment>
</AccountingCodingBlockDistribution>
<ProductTax actionCode="01">
<!--1 non-taxable | 2 stanadard tax-->
<ProductTaxationCharacteristicsCode listID="21801">1</ProductTaxationCharacteristicsCode>
<CountryCode>DE</CountryCode>
</ProductTax>
</Item>
<!--Item: invoice item with service product-->
<Item actionCode="01">
<ObjectNodeSenderTechnicalID>H1-I2</ObjectNodeSenderTechnicalID>
<ItemID>3</ItemID>
<!--002 invoice item | 003 credit memo item-->
<BusinessTransactionDocumentItemTypeCode>002</BusinessTransactionDocumentItemTypeCode>
<!--<SHORT_Description languageCode="EN">Item Description of product item</SHORT_Description>-->
<Quantity unitCode="HUR">1</Quantity>
<NetAmount currencyCode="EUR">50</NetAmount>
<!--<GrossAmount currencyCode="EUR">119</GrossAmount>-->
<Product actionCode="01">
<CashDiscountDeductibleIndicator>false</CashDiscountDeductibleIndicator>
<ProductKey>
<ProductTypeCode>2</ProductTypeCode>
<ProductIdentifierTypeCode>1</ProductIdentifierTypeCode>
<ProductID>MDECD-0004</ProductID>
</ProductKey>
</Product>
<AccountingCodingBlockDistribution AccountingCodingBlockAssignmentListCompleteTransmissionIndicator="true" ActionCode="01">
<AccountingCodingBlockAssignment ActionCode="01">
<!--ACC, CC-->
<AccountingCodingBlockTypeCode>CC</AccountingCodingBlockTypeCode>
<!--<GeneralLedgerAccountAliasCode>A-7420</GeneralLedgerAccountAliasCode>-->
<CostCentreID>MDEC46000</CostCentreID>
</AccountingCodingBlockAssignment>
</AccountingCodingBlockDistribution>
<!--Tax code will be derived from product-->
<ProductTax actionCode="01">
<ProductTaxationCharacteristicsCode listID="21801">1</ProductTaxationCharacteristicsCode>
<CountryCode>DE</CountryCode>
</ProductTax>
</Item>
</SupplierInvoice>
</glob:SupplierInvoiceBundleMaintainRequest_sync>
</soapenv:Body>
</soapenv:Envelope>
Some Remarks:
- The resulting entry method of ERS invoices created via web service API is “ERS with External Application“.
- ByD calculates the total gross/net amount and tax amount of ERS invoices automatically it the corresponding elements are not submitted with the web service request.
-
In a manual and external ERS invoices you cannot enter a reference to a ERS purchase order.
-
ERS invoices are always using the standard internal number range defined by SAP and hence do not provide element SupplierInvoiceID in the web service request.
-
The approval of manual and external ERS invoices is supported by the ByD approval app – just like any other invoice as well.
-
The supplier invoice web service API supports contract references in supplier invoice items.
If you use purchasing contracts with manual/external ERS invoices, then the following settings in the contract items are the right ones:
-
Goods receipt expected: true (The GR expected indicator need to be set due to a check in the contract, but has no impact in this case)
- Evaluated Receipt Settlement: true
- Invoice Expected: false
-
Knut Heusermann
Thanks for the informative blog. I am currently trying to use the same web service to create credit memo without purchase order. I have modified your payload for that sake and yet I am having some errors.
The payload I used is :
And the set of errors are:
Would you please advise?
Thanks in advance,
Mousa
Hi Mousa,
the error message related to the product is definitely because of your xml is not well-formed in the item-product section.
The other error messages are very likely follow-up issue related to the buyer party. Is T001 a valid company ID in ByD?
Best regards,
Knut
Thanks Knut Heusermann I was able to get it right 🙂
Hi,
is it possible to post a supplier invoice with payment status "blocked" ? how to do so?
thanks
Hi Maxime,
you can set the payment block by providing a payment blocking reason code in node SupplierInvoice.PaymentControl.PaymentBlock.
Best regards,
Knut
Thanks for your reply, I got it working in the end 🙂
Dear Knut,
Thanks for this interesting blog post.
We are trying to use ByD Web Service API to create supplier invoices that distributes costs among others invoices. Do you have any code sample dealing with this case please ?
We tried to use SupplierInvoiceReference > BusinessTransactionDocumentReference "node" but without success
Thanks
Hi Solène,
the cost distribution is currently only available via user interface and cannot be achieved via web service. Can you please create an improvement request for the same?
Thanks and best regards,
Stefan
Hi Stefan.
I'm developing a CBO that Create Supplier Invoice.
Cost distribution in the same supplier invoice..
I wnat to add a Cost Distribution line, but I can't....
How to create Cost Distribution of Supplier Invoice with CBO ?
If it is impossible to Cost Distribution by CBO, is it possible by API?
Hi Yeseul,
this is the information I got from my development counterpart. The action “Add assignment” ( Add row in Cost Distribution tab ) could be used to create internal items. The action itself along with parameters was PSM released.
Maybe you can try out this approach.
Best Regards,
Stefan
Dear Knut,
We have similar problem with Solene, do you have any suggestions?
We definitely need this to accommodate large numbers of Invoice Items.
Best Regards,
Hi Knut,
Can it possible to post a Suppllier Invoice throgh API with "In Approval" status?
Thanks,
Rajesh.
Hi Rajesh.
if the supplier invoice is in approval, it will also not be possible to post the invoice via API - first the approval has to be done, and then the invoice should automatically be posted.
In case you talk about trying to post an invoice, using a technical user from the communication arrangement, we are not able to determine approvers, and therefore we forbit to post those invoices
Hope that answers your question.
Regards,
Stefan
Is it possible to create an Invoice and let SAP generate its BaseBusinessTransactionDocumentID as if you were creating it manually from the UI?
I do not want to take on the responsibility of managing Invoice ID's myself.
Thanks in advance.
Hi Yan,
for supplier invoices just omit the element "SupplierInvoiceID" and the system will use the next free ID from the internal number range.
For customer invoice requests the BaseBusinessTransactionDocumentID is mandatory, because the web service creates "external invoice requests", assuming that the invoice requests refers to a preceding document in an external system - the BaseBusinessTransactionDocumentID is the ID of this preceding document.
Unfortuately it is currently not possible to create "manual invoices" via web service API or Custom OData APIs.
Best regards,
Knut
Hi Knut,
I'm developing a CBO that Create Supplier Invoice.
I wnat to add a Cost Distribution line, but I can't....
How to create Cost Distribution of Supplier Invoice with CBO ?
If it is impossible to Cost Distribution by CBO, is it possible by API?