Skip to Content
Technical Articles
Author's profile photo Lijun Yin

Guidelines for API Journal Entry – Post

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:

 

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

  1. 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.
  2. 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:

  1. Only journal entries posted with the API can be reversed. Reversal of journal entries posted with apps isn’t supported.
  2. Journal entries that have triggered subsequent documents can’t be reversed, for example, eDocuments.
  3. Reversal of already cleared or reversed postings is not supported.
  4. Reversal of down payments requests is not supported.
  5. 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.

Assigned Tags

      9 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Harsh Bhalla
      Harsh Bhalla

      Thank you Wesley for this rich article,

      Is there any API for Journal Entry in SAP ECC ,and can we use the above API for S4/HANA

      On-premise.

       

      Thank you,

      Author's profile photo Ellen Yeo
      Ellen Yeo

      This is great, Wesley!

      Author's profile photo venky v
      venky v

      Hi Wesley Yin,

      is there any API available to read entire FI document data? (similar to FI_DOCUMENT_READ Function module)

      I was searched in SAP API Hub and as well as in SAP Help portals but i couldn't find any such API.do  you have any information?

      Author's profile photo Lijun Yin
      Lijun Yin
      Blog Post Author

      Hi Venky V

      Have you tried Accounting Document - Read?

      Overview | Accounting Document - Read | SAP Business Accelerator Hub

      BR,

      Wesley

      Author's profile photo Ahamed Kalikul Jaman
      Ahamed Kalikul Jaman

      Hi Wesley,

      Is there any REST API for Posting?

      Thanks,

      Ahamed

      Author's profile photo Qiang Xu
      Qiang Xu

      Hi Wesley Yin,

      When detailing the API Journal Entry - Post (Synchronous) parameters below, I noticed that the TaxDeterminationDate parameter becomes required after TDT activation.

      https://help.sap.com/docs/SAP_S4HANA_CLOUD/b978f98fc5884ff2aeb10c8fdeb8a43b/92fed0579212c525e10000000a4450e5.html?locale=en-US#parameters

      Does this mean that the necessity of the parameter TaxDeterminationDate will change from Optional to Mandatory?

      Author's profile photo Ken Diep
      Ken Diep

      Hi Wesley,

      Is constraint 5.1, over 999 lines, still exist in newer version?

      Ken

      Author's profile photo shashank sk
      shashank sk

      Hi @wesley.yin2

      I am trying to post the Journal entry using SOAP Synchronous API when i try to clear the
      system generated  "Billing Doc Transfer "(RV) which gets generated when an invoice is created

      I am here trying to clear this "Billing Doc Transfer "(RV) by customer payment DZ from SOAP synchronous API
      so here i am facing issue of missing some mandatory fields in the SOAP payload.

      <?xml version="1.0" encoding="UTF-8"?>
      <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sfin="http://sap.com/xi/SAPSCORE/SFIN">
         <soapenv:Header/>
         <soapenv:Body>
            <sfin:JournalEntryBulkCreateRequest>
               <MessageHeader>
                  <CreationDateTime>2023-09-15T09:00:00Z</CreationDateTime>
               </MessageHeader>
               <JournalEntryCreateRequest>
                  <MessageHeader>
                     <CreationDateTime>2023-09-15T09:00:00Z</CreationDateTime>
                  </MessageHeader>
                  <JournalEntry>
                     <OriginalReferenceDocumentType>BKPFF</OriginalReferenceDocumentType>
                     <BusinessTransactionType>RFBU</BusinessTransactionType>
                     <AccountingDocumentType>DZ</AccountingDocumentType>
                     <CompanyCode>1810</CompanyCode>
                     <DocumentDate>2023-09-29</DocumentDate>
                     <PostingDate>2023-09-29</PostingDate>
                     <CreatedByUser>CB9980000041</CreatedByUser>
                      <Item>
                        <ReferenceDocumentItem>1</ReferenceDocumentItem>
                        <GLAccount>10010000</GLAccount>
                        <AmountInTransactionCurrency currencyCode="INR">100</AmountInTransactionCurrency>
                        <DebitCreditCode>D</DebitCreditCode>
                       <AccountAssignment>
                           <SalesOrder>0000196</SalesOrder>
                           <SalesOrderItem>10</SalesOrderItem>
                        </AccountAssignment>
                     </Item>
                     <CreditorItem>
                        <ReferenceDocumentItem>2</ReferenceDocumentItem>
                        <Creditor>18100003</Creditor>
                        <AmountInTransactionCurrency currencyCode="INR">-100</AmountInTransactionCurrency>
                         <PaymentDetails>
                          <PaymentReference>9400000082</PaymentReference>
                        </PaymentDetails>
                     </CreditorItem>
                  </JournalEntry>
              </JournalEntryCreateRequest>
            </sfin:JournalEntryBulkCreateRequest>
         </soapenv:Body>
      </soapenv:Envelope>
      Author's profile photo Jorge Calderon
      Jorge Calderon

      Hello,

      Is there any possibility of having this API in CPI API management? I mean , we want to use CPI in the middle between S4( on premise ) and third parties, can we do it? how?

      Thanks

      Regards,