Guidelines for API Journal Entry – Post

Wesley · ‎09-06-2019

In this blog post series you will learn some constraints, help information about Journal Entry API in communication scenario Finance - Posting Integration (SAP_COM_0002) , as well as how to configure this communication scenario on S/4HANA Cloud system and test the Journal Entry APIs by the tool called SOAPUI.

Communication scenario Finance - Posting Integration (SAP_COM_0002) includes 4 main Journal Entry relevant APIs:

API Journal Entry – Post (Synchronous) enables synchronous posting of journal entries from external systems to your SAP S/4HANA Cloud system.

API Journal Entry – Post (Asynchronous) enables asynchronous posting of journal entries from external systems to your SAP S/4HANA Cloud system. To check the status of the posting, you can use the Application Interface Framework (AIF) monitor.

API Journal Entry – Change (Asynchronous) enables you to change part of the header or item information of existing journal entries through an asynchronous service.

API Journal Entry – Clearing (Asynchronous) enables you to clear journal entries from external systems to your SAP S/4HANA Cloud system through an asynchronous service.

API Journal Entry by Ledger - Post (Asynchronous) enables you to upload multiple journal entry documents in one payload with ledger group information on header level for each to create accounting documents in the SAP S/4HANA Cloud system.

This blog post is the first part of a blog series. I do not want to put all the content in this blog post as it would make it too long to read, so I’d like to separate the topics into several blog posts as following:

Guidelines for API Journal Entry – Post (Synchronous) and API Journal Entry – Post (Asynchronous).

Guidelines for API Journal Entry – Change (Asynchronous).

Guidelines for API Journal Entry – Clearing (Asynchronous).

Guidelines for Creating and Enabling Extension Field for Journal Entry API.

Guidelines for Configuring Communication Scenario Finance - Posting Integration (SAP_COM_0002) .

Guidelines for Testing Journal Entry API with SOAPUI and Checking Response Message

Then I'd like to start the first part with Guidelines for API Journal Entry – Post (Synchronous) and API Journal Entry – Post (Asynchronous)

1. Usage

Journal Entry Post API provides SOAP APIs which enable remote systems to post journal entries to the S4/HANA tenant.

The API has two types of SOAP inbound interfaces. One is the synchronous SOAP inbound interface "JournalEntryCreateRequestConfirmation_In". The other is asynchronous SOAP inbound interface "JournalEntryBulkCreationRequest_In".

To learn more about the information of importing parameters at SAP Help

Journal Entry – Post (Synchronized)

Journal Entry – Post (Asynchronized)

2. Prerequisite

In order to use these 2 APIs, you need to firstly configure communication arrangement for communication scenario Finance - Posting Integration (SAP_COM_0002).

Read more at Guidelines for Configuring Communication Scenario Finance - Posting Integration (SAP_COM_0002)

If you want to post with extension fields by these 2 APIs, you need to create extension fields and enable them for the APIs via Fiori App Custom Fields and Logic.

Read more at Guidelines for Creating and Enabling Extension Field for Journal Entry API

3. How to Test

These 2 APIs are SOAP service. I suggest to test them with SOAPUI.

Read more at Guidelines for Testing Journal Entry API with SOAPUI and Checking Response Message

4. How to Check Response Message

For API Journal Entry – Post (Synchronous), you can see the response message immediately in SOAPUI. But for API Journal Entry – Post (Asynchronous), you need to check the response message via Fiori App Message Dashboard.

Read more at Guidelines for Testing Journal Entry API with SOAPUI and Checking Response Message

Since CE2005, we provide Outbound API Journal Entry – Create Confirmation (Asynchronous), which is the outbound service of API Journal Entry – Post (Asynchronous). By means of this outbound service, the execution result can be sent to the sender system proactively.

Regarding how to enable outbound API in communication arrangement and how to fill in data request, please refer Guidelines for Enabling Outbound API Journal Entry – Change Confirmation (Asynchronous). This Guideline mainly introduce the procedure to use Outbound API Journal Entry – Change Confirmation (Asynchronous), which are the same as Outbound API Journal Entry – Create Confirmation (Asynchronous) .

5. Constraints and Consulting Questions

5.1 Constraints about Over 999 Line Items Posting

As of CE1905, Journal Entry Post API (Synchronous and Asynchronous) supports over 999 line items posting. But there are some limitations below to be complied.

If the document line item number is less than or equal 999, no compress will happen. The details are stored in both of Entry View and Ledger View.

If the document line item number is higher than 999 and the items exclude open item, cross company item and tax item, the items are only stored in the Ledger View without compress.

If the document line item number is higher than 999 and the items include open item, cross company item or tax item, the items will be compressed in Entry View. This is done by deleting the contents from the account assignment except for the function area. But the details are still stored in the Ledger View.But for the following cases, the items will not be compressed in Entry View:

a. CreditorItem or DebtorItem cannot be compressed.
b. The G/L Items with accounts which are open item management cannot be compressed if the G/L items are distinguished by assignment or account assignment or item text or any other value offered in the GL structure (besides amount fields). If there are no difference among G/L items besides amount fields, they will be compressed.
c. If items have unique document item text or assignment, these items cannot be compressed.

In case the document line item number is still higher than 999 after compress, the posting will fail as Entry View does not support over 999 line items.

5.2 Consulting about Extension field not displayed in Fiori App Manage Journal Entris

If extension field is totally missing in Fiori App Manage Journal Entry, please make sure the extension field is enabled for Manage Journal Entries when creating it in Fiori App Custom Fields and Logic.

If the value of extension field is missing, you need to switch to legal view to see its value in Fiori App Manage Journal Entry

5.3 Consulting about Payment Terms

If substructure DebtorItem-CashDiscountTerms or CreditorItem-CashDiscountTerms are filled with value in payload, cash discount is determined by CashDiscountTerms. Otherwise cash discount is determined by Payment Terms which is derived from Customer or Supplier’s master data.

If you want to fill CashDiscountTerms, you need to fill the following fields in order.

<DueCalculationBaseDate>?</DueCalculationBaseDate>

<CashDiscount1Days>?</CashDiscount1Days>

<CashDiscount1Percent>?</CashDiscount1Percent>

<CashDiscount2Days>?</CashDiscount2Days>

<CashDiscount2Percent>?</CashDiscount2Percent>

<NetPaymentDays>?</NetPaymentDays>

It is not allowed to have a gap in the payment terms. However, it is allowed to only fill NetPaymentDays. In this case, the NetPaymentDays will be shifted to CashDiscountDays1 with CashDiscountPercent1 = 0%. From business perspective this is equivalent.

Correct Example:

<CashDiscountTerms>

<DueCalculationBaseDate>2019-01-24</DueCalculationBaseDate>

<CashDiscount1Days>1</CashDiscount1Days>

<CashDiscount1Percent>5</CashDiscount1Percent>

<CashDiscount2Days>3</CashDiscount2Days>

<CashDiscount2Percent>2</CashDiscount2Percent>

<NetPaymentDays>5</NetPaymentDays>

</CashDiscountTerms>

Or

<CashDiscountTerms>

<DueCalculationBaseDate>2019-01-24</DueCalculationBaseDate>

<NetPaymentDays>5</NetPaymentDays>

</CashDiscountTerms>

Incorrect Example:

This example is incorrect because CashDiscount1Days and CashDiscount1Percent are not filled.

<CashDiscountTerms>

<DueCalculationBaseDate>2019-01-24</DueCalculationBaseDate>

<CashDiscount2Days>3</CashDiscount2Days>

<CashDiscount2Percent>2</CashDiscount2Percent>

<NetPaymentDays>5</NetPaymentDays>

</CashDiscountTerms>

</CreditorItem>

5.4 Consulting if Customer/Vender Payment is supported

The API does not support posting document for customer or vender payment. But if user wants to use, it can be posted but posting key is wrong. In additional, the API does not support clearing open item.

5.5 Consulting about Partner Bank Type

Partner bank type is not provided in the structure of JE Post API. However, it can be determined by country, vender, bank number and bank account. It means if you provide these fields in Substructure CreditorItem-PaymentDetails-PayeeBankAccount, partner bank type can be determined from vender master data and updated in accounting document.

Example is below.

<CreditorItem>
<ReferenceDocumentItem>1</ReferenceDocumentItem>
<Creditor>0010401010</Creditor>
<AmountInTransactionCurrency currencyCode="EUR">-100</AmountInTransactionCurrency>
<DebitCreditCode>H</DebitCreditCode>
<PaymentDetails>
<PayeeBankAccount>
<Country>DE</Country>
<BankNumber>50070010</BankNumber>
<BankAccount>50070010</BankAccount>
<IBAN>DE54500700100113369800</IBAN>
</PayeeBankAccount>
</PaymentDetails>
</CreditorItem>

Partner bank type is proposed in accounting document.

5.6 Consulting about Tax Caculation

JE Post API does not support calculating tax amount automatically based on tax code. Tax amount and other tax information need to be manually filled in substructure ProductTaxItem.

This is part of payload as example:

<Item>

<ReferenceDocumentItem>1</ReferenceDocumentItem>

<GLAccount>0063009000</GLAccount>

<AmountInTransactionCurrency currencyCode="IDR">91</AmountInTransactionCurrency>

<DebitCreditCode>S</DebitCreditCode>

<DocumentItemText>Test Item</DocumentItemText>

                  <Tax>

                     <TaxCode>V2</TaxCode>

                  </Tax>

<AccountAssignment>

<CostCenter>0051101101</CostCenter>

</AccountAssignment>

</Item>

<CreditorItem>

<ReferenceDocumentItem>2</ReferenceDocumentItem>

<Creditor>S5130003</Creditor>

<AmountInTransactionCurrency currencyCode="IDR">-100</AmountInTransactionCurrency>

<DebitCreditCode>H</DebitCreditCode>

<DocumentItemText>Vender item</DocumentItemText>

</CreditorItem>

               <ProductTaxItem>

                  <TaxCode>V2</TaxCode>

                  <TaxItemClassification>VST</TaxItemClassification>

                  <AmountInTransactionCurrency currencyCode="IDR">9</AmountInTransactionCurrency>

                  <DebitCreditCode>S</DebitCreditCode>

                  <TaxBaseAmountInTransCrcy currencyCode="IDR">91</TaxBaseAmountInTransCrcy>

               </ProductTaxItem>

5.7 Consulting about the Possible Reason of Data Missing

The data in payload would be missing if the spell is wrong in the masks of structure, like

<DocumentItemTest></DocumentItemTest>

or it does not comply Camel Case, like <DocumentItemtext></DocumentItemtext>.

If you find some data is missing though it is definitely filled in payload, please firstly make sure the spell is correct.

5.8 Consulting about the Determination of Posting Key

Firstly, Posting Keys are not filled manually in payload as they are automatically determined as per the following logic.

• For Item node, ProductTaxItem node, WithholdingTaxItem node

If it is Debit entry / amount is positive, then posting key is 40 Debit entry

If it is Credit entry / amount is negative, then posting key is 50 Credit entry

• For DebtorItem node
If it is Debit entry / amount is positive, then posting key is 01 Invoice

If it is Credit entry / amount is negative, then posting key is 11 Credit memo

• For CreditorItem node
If it is Debit entry / amount is positive, then posting key is 21 Credit memo

If it is Credit entry / amount is negative, then posting key is 31 Invoice

5.9 Consulting about Negative Posting

The JE Post API supports negative posting on header level. To enable negative posting, you must fill in the DebitCreditCode for all items. If the amount is positive, you must set DebitCreditCode to 'H'. If the amount is negative, you must set it to 'S', as illustrated in the sample codes below. The item is then marked as negative posting.

If you do this partially, an error message ‘D/C-Code does not fit to sign of amount in some items’ is issued.

Correct Example

            <JournalEntry>

               <OriginalReferenceDocumentType>BKPFF</OriginalReferenceDocumentType>

               <BusinessTransactionType>RFBU</BusinessTransactionType>

               <AccountingDocumentType>KR</AccountingDocumentType>

               <CompanyCode>2000</CompanyCode>

               <DocumentDate>2018-12-05</DocumentDate>

               <PostingDate>2018-12-05</PostingDate>



               <Item>

                  <ReferenceDocumentItem>1</ReferenceDocumentItem>

                  <GLAccount>0000473110</GLAccount>

                  <AmountInTransactionCurrency currencyCode="EUR">100</AmountInTransactionCurrency>

                  <DebitCreditCode>H</DebitCreditCode>

               </Item>

               <CreditorItem>

                  <ReferenceDocumentItem>2</ReferenceDocumentItem>

                  <Creditor>101115</Creditor>

                  <AmountInTransactionCurrency currencyCode="EUR">-90</AmountInTransactionCurrency>

                  <DebitCreditCode>S</DebitCreditCode>

               </CreditorItem>

            </JournalEntry>

6. Important New Features per Release

6.1 Since CE2008, the API supports reversing accounting document. The reversal has the following constraints:

Only journal entries posted with the API can be reversed. Reversal of journal entries posted with apps isn’t supported.

Journal entries that have triggered subsequent documents can’t be reversed, for example, eDocuments.

Reversal of already cleared or reversed postings is not supported.

Reversal of down payments requests is not supported.

The simulation functionality isn't supported.

See more at online help Journal Entry – Reverse

6.2 Since CE2108, the API supports VAT tax amount validation.

If the tax amount isn't filled correctly and the validation is enabled, the posting will be blocked.

To enable the validation, you need to fill 'true' in the field 'DoTaxAmountCheck' which is located in the structure 'JournalEntry'. If the field 'DoTaxAmountCheck' is filled with 'false' or empty, the validation is disabled.

7. Appendix

1. SAP Help Page

Journal Entry – Post (Synchronized)

Journal Entry – Post (Asynchronized)

2. SAP API Business Hub

Journal Entry - Post (synchronized)

Journal Entry - Post (asynchronized)

3. Payload Examples

In order to help you prepare the payload, I'd like to provide some payload examples. You could access them at Payload Examples for API Journal Entry – Post.