SAP S/4HANA On-Premise API Integration Research

Date: 2026-03-31 Target: SAP S/4HANA On-Premise (ERP system) Purpose: Evaluate API capabilities for Orcha integration (AP automation, invoice processing)

1. Summary — Capability Matrix

Bottom line: SAP S/4HANA On-Premise has a comprehensive, well-documented API surface covering all core Orcha integration needs. The primary invoice creation API (API_SUPPLIERINVOICE_PROCESS_SRV) supports deep insert (header + line items + tax in one call), document attachment, and status tracking. Write access is available for all critical transactional and master data objects. The main gaps are: GL account creation (BAPI only, no OData), no native webhooks on-premise (polling required), and approval workflows being heavily customer-specific.

2. API Landscape

Central Documentation

API Protocols

Migration note: SAP is actively migrating V2 to V4 (e.g., Purchase Order API). BAPIs are being deprecated per "Clean Core" initiative (Q3 2025 modernization recommendations). However, some functionality is still BAPI-only.

Authentication Methods

CSRF Token requirement: All write operations (POST/PATCH/DELETE) require a fresh CSRF token:

1. GET request with header X-CSRF-Token: Fetch → receive token + session cookies
2. Include token + cookies in subsequent write request
3. Token is session-bound — reuse within same HTTP session

Pagination & Rate Limits

• On-Premise: No formal rate limits at API level (unlike cloud). Configurable via SAP Gateway / Web Dispatcher.
• Pagination: OData $top, $skip, server-driven paging via $skiptoken. Default page size typically 100-1,000 records.
• Batch: $batch endpoint available for combining multiple operations. Supports atomic changesets.

3. Write Verification — Evidence for Write Capability

Confirmed Write Operations

Notable Write Gaps

4. iPaaS & Middleware Findings

Platform Comparison

Key iPaaS Insights

1. All 6 enterprise iPaaS platforms confirm full write capability to S/4HANA On-Premise — this is a well-established integration pattern.
2. On-Premise connectivity is solved via lightweight agents (Workato OPA, Boomi Atom, Celigo Agent, SAP Cloud Connector). Agents create outbound tunnels — no inbound firewall rules needed.
3. SAP BTP Integration Suite is the gold standard with 2,000+ pre-built integration flows, but requires SAP ecosystem investment.
4. Boomi and Celigo offer best cost-to-capability ratio for SAP specifically.
5. iPaaS as discovery tool: iPaaS connectors revealing Import/Action operations confirmed that write endpoints exist even where SAP's public docs are unclear.

SAP BTP Integration Suite (Recommended iPaaS if Middleware Needed)

• First-party SAP product — deepest integration, 2,000+ pre-built flows
• Pre-built content for: Finance (Journal Entries, GL Posting), Procurement (PO, Invoices), Master Data (Business Partners, Cost Centers)
• Connectivity via SAP Cloud Connector (lightweight on-prem agent, X.509 cert auth, principal propagation)
• Integration flows expose HTTP endpoints callable from any external system (including Orcha)
• Licensed under SAP BTP — subscription or pay-as-you-go based on message volume

5. Alternative Channels

Recommended Channel Strategy

• Primary: Direct OData API calls via HTTPS (simplest, most maintainable)
• Fallback for GL accounts: RFC/BAPI via SAP JCo or through iPaaS
• Status monitoring: OData polling with date-based filters
• High-volume scenarios: Consider IDoc or batch file exchange
• If customer has SAP BTP: Leverage Cloud Connector + Integration Suite

6. Licensing & Access Requirements

API Access — Included or Extra Cost?

CRITICAL: SAP Digital Access / Indirect Access Licensing

This is the most important licensing consideration and a well-known cost trap:

What it is: SAP charges for "digital access" when third-party systems (like Orcha) create or read documents in SAP. This was historically called "indirect access" and was the subject of major lawsuits (notably SAP vs. Diageo, 2017).

Current model (since 2018): SAP offers a Document-Based Pricing model:

• Charges are based on the number of documents created in SAP by external systems per year
• Document types are categorized (e.g., "Order to Cash," "Procure to Pay," "Finance")
• Supplier invoices created via API count as "Procure to Pay" documents
• Pricing tiers vary — typically starting at several thousand EUR for document packages
• Existing SAP customers can choose to adopt the new model or stay on their existing licensing

Impact for Orcha customers:

• Every supplier invoice Orcha creates in SAP via API may incur a per-document digital access fee
• The customer MUST clarify their SAP licensing model and digital access entitlement before going live
• Some customers may already have digital access included in their enterprise agreement
• Others may need to purchase document packages from SAP

What Orcha should include in customer-facing materials:

"Please confirm with your SAP account manager whether your S/4HANA license includes Digital Access entitlement for Procure-to-Pay documents. If your license predates 2018, you may need to adopt SAP's Digital Access pricing model or purchase document packages before enabling third-party invoice creation via API."

Customer Setup Checklist

The following steps must be completed by the customer's SAP Basis administrator before Orcha can connect:

OData Services to Activate

Required Authorization Objects

Ongoing Costs for Customer

7. Orcha-Specific Deep Dive

7a. Create Supplier Invoice (AP Invoice) — PRIMARY INTEGRATION POINT

Service: API_SUPPLIERINVOICE_PROCESS_SRV (OData v2) Available from: S/4HANA 1610+ Endpoint: POST /sap/opu/odata/sap/API_SUPPLIERINVOICE_PROCESS_SRV/A_SupplierInvoice

Supports deep insert — create header + GL line items + tax items in a single POST:

{
  "CompanyCode": "1000",
  "DocumentDate": "/Date(1711843200000)/",
  "PostingDate": "/Date(1711843200000)/",
  "SupplierInvoiceIDByInvoicingParty": "INV-2026-001",
  "InvoicingParty": "0000001000",
  "DocumentCurrency": "EUR",
  "InvoiceGrossAmount": "1190.00",
  "TaxIsCalculatedAutomatically": true,
  "DocumentHeaderText": "Orcha processed invoice",
  "PaymentTerms": "0001",
  "to_SupplierInvoiceItemGLAcct": [
    {
      "GLAccount": "0000400000",
      "SupplierInvoiceItemAmount": "1000.00",
      "TaxCode": "V1",
      "CostCenter": "0000010000",
      "DocumentItemText": "Office supplies"
    }
  ],
  "to_SupplierInvoiceItemTax": [
    {
      "TaxCode": "V1",
      "TaxAmount": "190.00",
      "TaxBaseAmountInTransCrcy": "1000.00"
    }
  ]
}

Navigation properties for deep insert:

• to_SupplierInvoiceItemGLAcct — GL account line items (non-PO invoices)
• to_SupplierInvoiceItemPurOrd — PO-based line items (3-way matching)
• to_SupplierInvoiceItemTax — tax line items
• to_SuplrInvcItemAcctAssgmt — account assignment details

Key fields (header): CompanyCode, DocumentDate, PostingDate, InvoicingParty (vendor), DocumentCurrency, InvoiceGrossAmount, SupplierInvoiceIDByInvoicingParty (vendor's invoice number), PaymentTerms, SupplierInvoiceStatus (5 = park), PaymentBlockingReason

Key fields (line items): GLAccount, SupplierInvoiceItemAmount, TaxCode, CostCenter, ProfitCenter, WBSElement, InternalOrder, DocumentItemText, DebitCreditCode

Credit notes: Same API with SupplierInvoiceType = "KG" (credit memo) or "KR" (vendor credit note).

Response: Returns SupplierInvoice (document number), FiscalYear, CompanyCode as keys.

BAPI alternative: BAPI_INCOMINGINVOICE_CREATE via RFC — older, stable, same capability.

Confidence: VERY HIGH

7b. Attach Invoice PDF

Service: API_CV_ATTACHMENT_SRV (OData v2) Available from: S/4HANA 1709+ Endpoint: POST /sap/opu/odata/sap/API_CV_ATTACHMENT_SRV/AttachmentContentSet

How it works:

• POST with binary file content as body
• Set Content-Type to file MIME type (e.g., application/pdf)
• Required URL parameters / headers:
  • BusinessObjectTypeName = "BUS2081" (supplier invoice)
  • LinkedSAPObjectKey = "<CompanyCode><InvoiceDocNumber><FiscalYear>" (padded: 4+10+4 chars)
  • Slug = "invoice_12345.pdf" (filename)
• Supports: PDF, JPEG, PNG, TIFF, XLSX, DOCX — any binary format
• Max file size: configurable on SAP Gateway (typically 50-100 MB)

Workflow: Create invoice first → get document number → upload attachment using document key.

Confidence: HIGH

7c. Sync Reference Data (Read from SAP)

All support OData $filter, $select, $top, $skip for efficient querying and pagination.

Confidence: VERY HIGH

7d. Write Reference Data (Into SAP)

Confidence: HIGH (except GL accounts via OData — LOW for write)

7e. Approval Workflow Management

Pattern: Park → Approve → Post

1. Park invoice: Create with SupplierInvoiceStatus = "5" (parked, not posted)
2. Read workflow tasks: GET /sap/opu/odata/sap/API_TASK_SRV/TaskCollection — lists pending approval items
3. Approve/Reject: POST /sap/opu/odata/sap/API_TASK_SRV/Decision with DecisionKey (e.g., "0001" = approve, "0002" = reject)
4. Post parked invoice: Post action on the parked document after approval

Important caveats:

• Approval workflows are heavily customer-specific — configured per customer via SWU3 / PFTC
• No universal "approve this invoice" endpoint — depends on customer's workflow definition
• Safest Orcha approach: park invoices, then either let SAP handle approval internally, or query API_TASK_SRV to drive approvals if customer exposes their workflow
• Some customers use SAP's Flexible Workflow, others use classic Business Workflow, others use custom ABAP

Confidence: MEDIUM (API exists, but behavior varies per customer)

7f. Invoice Status & Payment Tracking

Invoice status: Read from API_SUPPLIERINVOICE_PROCESS_SRV

• SupplierInvoiceStatus — posted vs. parked
• PaymentBlockingReason — blank = not blocked
• IsReversed / ReversedDocument

Payment status: Read from API_JOURNALENTRYITEMBASIC_SRV

• Query: $filter=SupplierInvoice eq '...' and CompanyCode eq '...'
• ClearingDocument — if populated, invoice has been paid/cleared
• ClearingDate — date of payment
• IsCleared — boolean
• OpenItemAmount — remaining unpaid amount (partial payments)
• NetDueDate — payment due date

Delta monitoring: No native webhooks on-premise. Use polling:

• GET .../A_SupplierInvoice?$filter=LastChangeDate gt datetime'2026-03-30T00:00:00'
• Configurable polling interval per customer (recommend 5-15 minutes)

Confidence: HIGH

Orcha Integration Capability Summary

8. Recommended Path Forward

Architecture Recommendation: Direct OData API Integration

For Orcha's use case, direct OData API integration is the recommended approach — no iPaaS middleware needed.

Rationale:

• SAP S/4HANA On-Premise has well-documented, stable OData APIs for all core Orcha needs
• The APIs are included in the base S/4HANA license (no additional API module cost)
• Direct integration gives Orcha full control over the integration logic, error handling, and retry behavior
• Avoids iPaaS subscription costs ($10K-200K+/yr) for the customer
• OData v2 over HTTPS is a standard REST-like protocol — no special SDK needed

When iPaaS makes sense instead:

• Customer already has SAP BTP Integration Suite — leverage existing investment
• Customer requires IDoc-based integration (legacy processes)
• Customer's network policy prohibits direct HTTPS access to SAP — iPaaS agent as bridge
• GL account creation is critical — iPaaS can handle RFC/BAPI calls that direct OData cannot

Phased Integration Plan

Phase 1: Reference Data Sync (Read from SAP)

• Sync suppliers/vendors (API_BUSINESS_PARTNER)
• Sync cost centers (API_COSTCENTER_SRV)
• Sync GL accounts (API_GLACCOUNTINCHARTOFACCOUNTS_SRV)
• Sync company codes, tax codes
• Establish polling-based delta sync

Phase 2: Invoice Push (Write to SAP)

• Create supplier invoices via API_SUPPLIERINVOICE_PROCESS_SRV (deep insert)
• Create credit notes (same API, type KG)
• Attach original PDF via API_CV_ATTACHMENT_SRV
• Implement CSRF token handling and error management

Phase 3: Status Tracking & Lifecycle

• Poll for invoice status changes
• Track payment/clearing status via API_JOURNALENTRYITEMBASIC_SRV
• Build status sync back to Orcha (posted → approved → paid → cleared)

Phase 4: Approval Integration (Optional)

• Park invoices instead of posting directly
• Integrate with customer's approval workflow via API_TASK_SRV
• Note: highly customer-specific — may need per-customer configuration

Architecture Decision Matrix

Technical Considerations

9. Sources

Official SAP Documentation

• SAP Business Accelerator Hub — S/4HANA APIs: https://api.sap.com/products/SAPS4HANA/apis/packages
• SAP S/4HANA OData V2 API Package: https://api.sap.com/package/S4HANAOPAPI/odata
• SAP S/4HANA OData V4 APIs: https://api.sap.com/products/SAPS4HANA/apis/ODATAV4
• Supplier Invoice API: https://api.sap.com/api/API_SUPPLIERINVOICE_PROCESS_SRV/overview
• SAP Help Portal (On-Premise): https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE
• APIs on SAP Business Accelerator Hub: https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/8308e6d301d54584a33cd04a9861bc52/1e60f14bdc224c2c975c8fa8bcfd7f3f.html

Community & Guides

• Complete Guide to SAP S/4HANA APIs (Apideck): https://www.apideck.com/blog/guide-to-sap-4-hana-rest-and-soap-api
• SAP S/4HANA API Essentials (Rollout): https://rollout.com/integration-guides/sap/api-essentials
• Using Postman to test OData API in OnPrem system: https://community.sap.com/t5/enterprise-resource-planning-blog-posts-by-sap/using-postman-to-test-odata-api-in-onprem-system/ba-p/13547065
• Modernizing RFC/BAPI-based Integrations for Clean Core: https://community.sap.com/t5/technology-blog-posts-by-sap/modernizing-rfc-bapi-based-integrations-for-a-clean-core-with-sap/ba-p/14240582
• APIs for Journal Entries Collection: https://community.sap.com/t5/technology-blog-posts-by-sap/apis-for-journal-entries-the-collection-updated-july-2025/ba-p/13565258
• Cost Center APIs Practical Guide: https://community.sap.com/t5/enterprise-resource-planning-blog-posts-by-sap/a-practical-guide-to-cost-center-apis-in-sap-s-4hana-cloud/ba-p/14229337
• OAuth 2.0 with S/4HANA OData Services: https://community.sap.com/t5/technology-blog-posts-by-sap/step-by-step-calling-s-4hana-standard-odata-apis-with-oauth-2-0-from-client/ba-p/14346113

Licensing

• SAP Digital Access Licensing: https://www.sap.com/products/erp/digital-access.html
• SAP Indirect Access / Digital Access FAQ: SAP community discussions and analyst coverage (Gartner, Forrester)

iPaaS Platforms

• Celigo SAP Connector documentation
• Workato SAP Connector (On-Premise Agent)
• Boomi SAP Connector (Atom deployment)
• SAP BTP Integration Suite (Cloud Platform Integration)
• MuleSoft SAP Connector (Anypoint Exchange)
• Tray.io SAP Connector

API Specifications

• OData $metadata: Available per service at https://<host>/sap/opu/odata/sap/<SERVICE>/$metadata
• OpenAPI/YAML/JSON specs: Downloadable from SAP Business Accelerator Hub (login required)
• SAP Cloud SDK specification download: https://sap.github.io/cloud-sdk/docs/js/guides/api-business-hub-download-specification