SAP S4HANA Billing Outbound

SAP S/4HANA Billing Outbound — Pushing Bills to SAP Finance

When HMIS bills are finalized, they can be pushed to SAP S/4HANA Cloud Finance (FI) as accounting journal entries. This creates an accounts-receivable record in SAP that matches the HMIS bill.

---

How It Works

1. A bill is finalized (completed) in HMIS.
2. An administrator or an automated process calls the HMIS SAP billing API for that bill.
3. HMIS sends a journal entry to SAP with:
   • A debit line on the AR (accounts-receivable) account for the bill's net total.
   • A credit line on the revenue account for each line item on the bill.
4. SAP creates an accounting document and returns the document number.
5. HMIS stores the SAP document number against the bill. If the same bill is pushed again, HMIS returns the previously recorded result rather than creating a duplicate entry in SAP.

---

Configuration Required

The following keys must be set before pushing bills. See SAP S/4HANA Cloud Integration — Overview for how to set them.

Key	Description
SAP Integration - Enabled	Must be true
SAP Integration - Base URL	SAP tenant URL
SAP Integration - Token URL	OAuth token endpoint
SAP Integration - Client ID	OAuth client ID
SAP Integration - Client Secret	OAuth client secret
SAP Integration - Company Code	SAP company code
SAP Integration - AR Account	G/L account for the AR debit line
SAP Integration - Revenue Account	G/L account for revenue credit lines
SAP Integration - Currency	ISO currency code (default LKR)

---

API Reference

Push a Bill

Request

POST /api/sap/billing/push/{billId}
Finance: <api-key>

Success Response

{
  "status": "success",
  "code": 200,
  "data": {
    "billId": 12345,
    "billReference": "HMIS-2024-001234",
    "sapDocumentNumber": "0100000042",
    "companyCode": "1710",
    "fiscalYear": "2024"
  }
}

If already pushed (idempotent — safe to call multiple times)

{
  "status": "success",
  "code": 200,
  "data": {
    "status": "already_pushed",
    "pushRecord": "{\"sapDocNumber\":\"0100000042\",\"fiscalYear\":\"2024\",\"sentAt\":\"2024-03-15 14:30:00\"}"
  }
}

Check Push Status

Request

GET /api/sap/billing/status/{billId}
Finance: <api-key>

Returns the stored push record, or a 404 if the bill has not been pushed yet.

---

Requirements for a Bill to Be Pushed

A bill can only be pushed when:

• It exists and is not deleted (retired).
• It has not been cancelled.
• It is completed (finalized). Incomplete or in-progress bills cannot be pushed.

If any condition is not met, the API returns an error with a descriptive message.

---

Troubleshooting

Problem	What to check
SAP integration is disabled	Set SAP Integration - Enabled = true in Application Configuration
Bill not found	Verify the bill ID is correct and the bill has not been deleted
Bill is not yet completed	The bill must be finalized before it can be sent to SAP
SAP integration config key is not set	One of the required config keys (company code, AR account, etc.) is blank
HTTP 502 error	SAP returned an error — check the Payara server log for the SAP error message

---

Related Pages

• SAP S/4HANA Cloud Integration — Overview
• SAP S/4HANA Billing Inbound