| name | sap-s4hana-sales |
| description | SAP S/4HANA On-Premise Sales API integration guide covering ~119 APIs across OData V2, OData V4, and SOAP protocols. Use when building integrations with SAP S/4HANA Sales — including sales orders, sales quotations, sales contracts, scheduling agreements, billing documents, customer returns, credit/debit memo requests, leads, opportunities, appointments, phone calls, tasks, pricing condition records, customer materials, and solution quotations. Triggers on: "SAP", "S/4HANA", "S4HANA", "OData", "SOAP A2A", "sales order", "sales quotation", "billing document", "customer return", "credit memo", "debit memo", "lead API", "opportunity API", "pricing condition", "scheduling agreement", "sales contract", "deep insert", "SAP API", "SAP integration", "API_SalesOrder", "API_LEAD", "API_OPPORTUNITY", "API_BILLING_DOCUMENT_SRV".
|
SAP S/4HANA Sales APIs
Source: SAP Help Portal — APIs for Sales
Version: SAP S/4HANA 2025 FPS01 (Feb 2026)
Protocol Quick Reference
| Protocol | Version | Communication | Use Case |
|---|
| OData | V2 | Synchronous | Standard CRUD, real-time integration |
| OData | V4 | Synchronous + Async | Next-gen APIs (RAP), lightweight JSON, deep insert with full response |
| SOAP | — | Asynchronous | Bulk processing, A2A/B2B integration, reliable messaging |
Communication Types
| Type | Protocol | Execution | Use Case |
|---|
| A2X | OData | Synchronous | Connect SAP with external systems via HTTP |
| A2A | SOAP | Asynchronous | Internal system-to-system. Monitor via AIF (/AIF/ERR) or SRT_MONI |
| B2B | SOAP | Asynchronous | Cross-company/external landscape connectivity |
OData V2 vs V4
| Feature | OData V2 | OData V4 |
|---|
| Response format | XML/JSON | Lightweight JSON |
| Async mode | No | Yes (prefer: respond-async) |
| Minimal response | No | Yes (prefer: return=minimal) |
| Deep insert response | Key only | Full entity tree |
| Subentity filtering | Limited | Supported |
| Pricing in response | Limited | Complete (incl. subtotals) |
| ETag | Varies | Consistent (If-Match header) |
| Architecture | Classic SAP Gateway | RAP (ABAP RESTful Application Programming Model) |
Only 3 APIs have V4 versions: Sales Order, Sales Contract, Customer Return. Prefer V4 when available.
API Selection Guide
By Task
By Protocol Choice
- Real-time CRUD on single documents → OData (V4 preferred if available)
- Bulk/batch processing → SOAP A2A
- Cross-company B2B → SOAP B2B
- Simulation (no save) → OData Simulation APIs
- Read-only master data → OData A2X (Read)
Authentication
| Method | OData V2 | OData V4 | SOAP |
|---|
| Basic (User ID/Password) | Yes | Yes | Yes (Username Token) |
| X.509 Certificate | — | Yes | Yes (X509 Token) |
| OAuth 2.0 | — | Yes | — |
Common Authorization Objects
| Object | Description |
|---|
S_SERVICE | Check at Start of External Services (required by all APIs) |
V_VBAK_AAT | Sales Document: Authorization for Sales Document Types |
V_VBAK_VKO | Sales Document: Authorization for Sales Areas |
V_VBAK_APM | Sales Document: Approval Management |
V_VBRK_FKA | Billing: Authorization for Billing Types |
V_VBRK_VKO | Billing: Authorization for Sales Organizations |
V_KONH_VKO | Condition: Authorization for Sales Organizations |
/AIF/PROC | AIF Interface Processing (SOAP A2A APIs) |
Common Implementation Patterns
Service Activation
OData APIs: Activate via transaction for maintaining services on SAP Gateway hub system.
SOAP A2A APIs: ICF service is inactive by default. Activate via SICF: Select service → Menu Service/Host → Activate.
Deep Insert (Required by Most Sales APIs)
POST /sap/opu/odata/SAP/<SERVICE>/<HeaderEntity>
Content-Type: application/json
{
"HeaderField1": "value",
"to_Item": [
{
"ItemField1": "value",
"to_Partner": [...]
}
],
"to_Partner": [...],
"to_PricingElement": [...],
"to_Text": [...]
}
$batch Request Pattern
POST /sap/opu/odata/SAP/<SERVICE>/$batch
Content-Type: multipart/mixed; boundary=batch
--batch
Content-Type: multipart/mixed; boundary=changeset
--changeset
Content-Type: application/http
Content-Transfer-Encoding: binary
<individual request>
--changeset--
--batch--
Universal constraint: No multiple documents in a single changeset.
ETag Handling (Optimistic Concurrency)
OData V4 (Sales Order, Sales Contract): If-Match header required for all change operations. ETag = LastChangeDateTime.
OData V2 (Customer Return): GET → retrieve LastChangeDateTime → $batch changeset with MERGE (If-Match) as first op, then payload.
Pricing APIs: ETag in every entity; retrieve via GET, include in If-Match.
Async Mode (OData V4 Only)
Set prefer: respond-async header. Response returns 202 Accepted with location header containing a polling URL.
Error Monitoring
| Protocol | Tool | Transaction |
|---|
| OData | SAP Gateway Error Log | — |
| SOAP A2A | SAP Application Interface Framework (AIF) | /AIF/ERR |
| SOAP A2A | SOAP Monitoring | SRT_MONI |
BAdI Integration Points
Available for Sales Orders, Customer Returns, Scheduling Agreements, Credit/Debit Memos:
- Sales Document Check Before Save BAdI — Cancel without saving on error
- Sales Header Check BAdI — Continue and save
- Sales Item Check BAdI — Continue and save
Reference Files
Read the relevant reference file when working with a specific API domain:
| File | When to Read |
|---|
| sales-force-support.md | Working with Lead, Opportunity, Appointment, Phone Call, or Task APIs |
| order-contract-management.md | Working with Sales Orders, Quotations, Contracts, or Scheduling Agreements |
| pricing-and-master-data.md | Working with Pricing Condition Records, Customer Materials, or Sales Org master data |
| billing.md | Working with Billing Documents or Billing Requests |
| returns-and-claims.md | Working with Customer Returns, Credit/Debit Memos, or Sales Orders Without Charge |
| solution-business-and-index.md | Working with Solution Quotations, or looking up an API by technical name |
