zhongwei/gh-secondsky-sap-skills-skills-sap-btp-master-data-integration
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-secondsky-sap-skills-ski…/references/soap-api-reference.md
Zhongwei Li 2bc6bda6b5 Initial commit
2025-11-30 08:55:12 +08:00

546 lines
18 KiB
Markdown
Raw Permalink Blame History

# SOAP API Reference
Complete reference for SOAP-based integrations with SAP Master Data Integration.
**Table of Contents**
- [Endpoint Base URL](#endpoint-base-url)
- [Authentication Methods](#authentication-methods)
- [Available Endpoints](#available-endpoints)
- [Business Partner Replication Service](#business-partner-replication-service)
- [Confirmation Services](#confirmation-services)
- [Business Partner Relationships](#business-partner-relationships)
- [Key Mapping](#key-mapping)
**Source**: [https://github.com/SAP-docs/sap-btp-master-data-integration/tree/main/docs/development](https://github.com/SAP-docs/sap-btp-master-data-integration/tree/main/docs/development)
## Endpoint Base URL
```
[https://one-mds.cfapps.{region}.hana.ondemand.com/businesspartner/v0/soap/](https://one-mds.cfapps.{region}.hana.ondemand.com/businesspartner/v0/soap/)
```
**Regions**: For the complete, current list of SAP BTP Cloud Foundry regions and API endpoints, see:
- [SAP Help: Regions and API Endpoints Available for the Cloud Foundry Environment](https://help.sap.com/docs/btp/sap-business-technology-platform/regions-and-api-endpoints-available-for-cloud-foundry-environment)
Note: New regions are added periodically (e.g., cn20 for China, additional AWS regions). Always consult SAP Help for the current list.
## Authentication Methods
### Basic Authentication
```
Username: clientid
Password: clientsecret
URL Param: ?tenantId=<identityzone>
```
Example:
```
[https://one-mds.cfapps.eu10.hana.ondemand.com:443/businesspartner/v0/soap/BusinessPartnerBulkReplicateRequestIn?tenantId=<identityzone>](https://one-mds.cfapps.eu10.hana.ondemand.com:443/businesspartner/v0/soap/BusinessPartnerBulkReplicateRequestIn?tenantId=<identityzone>)
```
### OAuth Authentication
Use bearer token from XSUAA service.
## Available Endpoints
All endpoints use HTTP POST:
| Endpoint | Purpose |
|----------|---------|
| BusinessPartnerBulkReplicateRequestIn | BP inbound replication |
| BusinessPartnerBulkReplicateRequestConfIn | BP confirmation inbound |
| BusinessPartnerRelationshipBulkReplicateRequestIn | BP relationship inbound |
| BusinessPartnerRelationshipBulkReplicateRequestConfirmIn | BP relationship confirmation |
| KeyMappingBulkReplicateRequestIn | Key mapping inbound |
| KeyMappingBulkReplicateRequestConfirmIn | Key mapping confirmation |
**HEAD Request Support**: SOAP endpoints support HEAD requests for connectivity verification with SOAMANAGER.
---
## Business Partner Replication Service
**Service Name**: `BusinessPartnerSUITEBulkReplicateRequest_In`
### Service Nodes
| Node | Description |
|------|-------------|
| BusinessPartner | Core partner identity and classification |
| Person | Natural person demographic details |
| Organization | Legal entity attributes |
| Identification | ID documents and credentials |
| BankDetails | Payment account information |
| TaxNumber | Tax identification records |
| Role | Functional business assignments |
| Business Partner Group | Multi-entity groupings |
| Address Data | Contact and location details |
| Customer | Sales and account parameters |
| Supplier | Procurement specifications |
### Key BusinessPartner Node Fields
| Field | Description |
|-------|-------------|
| UUID | System identifier in receiver (optional) |
| CategoryCode | Partner classification (organization/person/group) |
| BlockedIndicator | Central blocking status |
| ReleasedIndicator | Business process eligibility |
### Address Data Includes
- Postal addresses (street, city, postal code)
- Communication channels (phone, email, fax, web)
- Validity periods for each contact method
### Customer Information Contains
- Account group and corporate grouping
- Sales/billing/delivery blocking reasons
- Tax classifications and industry codes
- Condition groups (up to 5 variants)
### Mandatory Fields
- BankAccountID (bank details)
- ID (bank account identifier)
---
## Business Partner Relationship Service
**Service Name**: `BusinessPartnerRelationshipSUITEBulkReplicateRequest_In`
### Service Nodes
**BusinessPartnerRelationship**
- Role codes characterizing relationship features
- Validity periods
- UUID references
- Default indicators
**ContactPerson**
- Workplace addresses
- Communications
- Functional roles
### Supported Identifiers
| ID Type | Supported |
|---------|-----------|
| Business Partner UUID | Yes |
| Business Partner Internal ID | Yes |
| Relationship Business Partner UUID | Yes |
| Relationship Business Partner Internal ID | Yes |
| Receiver Business Partner UUID | Yes |
| Receiver Business Partner Internal ID | Yes |
| Receiver Relationship BP UUID | Yes |
| Receiver Relationship BP Internal ID | Yes |
| IAM ID | No |
| External ID | No |
---
## Key Mapping Service
**Service Name**: `KeyMappingBulkReplicateRequest_In`
### Key Parameters
| Parameter | Description |
|-----------|-------------|
| BusinessSystemID | Source system identifier |
| TypeCode | Business object type (147=BP, 197=material) |
| ObjectIdentifierSet | Collection of object identifiers |
| ObjectIdentifier | Type code + key value combination |
| DefiningSchemeCode | Object Identifier Type Code (OITC) |
| KeyValue | ID value defined in target system |
| changeOrdinalNumber | Sequencing for incremental updates |
| actionCode | create/change/remove operations |
### IAM ID Support
Use DefiningSchemaCode value `CDC_IAM_ID` for IAM ID.
---
## Confirmation Services
### Business Partner Confirmation
**Service Name**: `BusinessPartnerSUITEBulkReplicateConfirmation_In`
### Nodes
- **BusinessPartner**: UUID, InternalID, ReceiverUUID, ExternalID, ReceiverInternalID
- **Customer**: InternalID, ReceiverInternalID
- **Supplier**: InternalID, ReceiverInternalID
All parameters optional.
### BP Relationship Confirmation
**Service Name**: `BusinessPartnerRelationshipSUITEBulkReplicateConfirmation_In`
### Key Mapping Confirmation
**Service Name**: `KeyMappingBulkReplicateConfirmation_In`
**MappingGroup Parameters**: BusinessSystemID, TypeCode, ObjectIdentifierSet, ObjectIdentifier, DefiningSchemeCode, KeyValue
---
## Partial Data Handling
Prevents data loss during SOAP outbound processing to S/4HANA or MDG.
### Protected Scenarios
| Scenario | Protection |
|----------|------------|
| Limited Entity Support | Unsupported entities not overwritten |
| Reduced Attribute Scope | Partial attributes preserved |
| Incomplete Entity Instances | Missing instances not deleted |
| Unsupported Roles | Role-specific data preserved |
### Configuration Requirements
- Maintain exclude-filters on connected system
- Maintain include-filters on connected system
- Reference SAP Notes: 2659038, 2733112, 3087667
---
## Destination Configuration
### Naming Convention
For businessSystemId `SYSTEMID`:
| Destination Name | Purpose |
|-----------------|---------|
| SYSTEMID_BPOUTBOUND | Business Partner replication |
| SYSTEMID_BPCONFIRM | Business Partner confirmation |
| SYSTEMID_BPRELOUTBOUND | Relationship replication |
| SYSTEMID_BPRELCONFIRM | Relationship confirmation |
| SYSTEMID_KMOUTBOUND | Key Mapping replication |
| SYSTEMID_KEYMAPCONFIRM | Key Mapping confirmation |
### Destination Settings
| Property | Value |
|----------|-------|
| Type | HTTP |
| Authentication | OAuth2, Basic, or Client Certificate |
### URL Sources
**S/4HANA Cloud**: Inbound services URL from SAP_COM_0008 communication arrangement
**S/4HANA On-Premise**: Hostname + Calculated Access URL from SOAManager
### Limit
Maximum 6 destinations per unique client connection.
---
## SOAP Events (SAP Cloud ALM)
### Inbound Event (1)
| Code | Description |
|------|-------------|
| BuPaDuplicateAddressId | Business Partner with given Address ID already exists |
### Outbound Success Events (6)
| Code | Description |
|------|-------------|
| BuPaSent | BusinessPartner successfully sent to destination |
| BuPaRelSent | BusinessPartnerRelationship successfully sent |
| KmSent | KeyMapping successfully sent |
| BuPaConfirmationSent | BusinessPartner confirmation sent |
| BuPaRelConfirmationSent | BusinessPartnerRelationship confirmation sent |
| KmConfirmationSent | KeyMapping confirmation sent |
### Confirmation Received Events (3)
| Code | Description |
|------|-------------|
| BupaConfirmationReceivedSuccessful | BusinessPartner confirmation processed successfully |
| BuPaRelConfirmationReceivedSuccessful | BusinessPartnerRelationship confirmation processed |
| KmConfirmationReceivedSuccessful | KeyMapping confirmation processed |
### Send Failure Events (9)
| Code | Description |
|------|-------------|
| BuPaSendFailed | Failed BusinessPartner transmission |
| BuPaRelSendFailed | Failed BusinessPartnerRelationship transmission |
| KmSendFailed | Failed KeyMapping transmission |
| BuPaSendFailedDestinationNotFound | Destination not configured |
| BuPaRelSendFailedDestinationNotFound | Destination not configured |
| KmSendFailedDestinationNotFound | Destination not configured |
| BuPaSendFailedHttpsSchemeExpected | HTTPS required (Internet ProxyType) |
| BuPaRelSendFailedHttpsSchemeExpected | HTTPS required (Internet ProxyType) |
| KmSendFailedHttpsSchemeExpected | HTTPS required (Internet ProxyType) |
### Wrong Scheme Configuration Events (6)
| Code | Description |
|------|-------------|
| BuPaSendFailedWrongSchemeConfigured | HTTP/HTTPS required (OnPremise ProxyType) |
| BuPaRelSendFailedWrongSchemeConfigured | HTTP/HTTPS required (OnPremise ProxyType) |
| KmSendFailedWrongSchemeConfigured | HTTP/HTTPS required (OnPremise ProxyType) |
| BuPaConfirmationFailedWrongSchemeConfigured | Wrong scheme for confirmation |
| BuPaRelConfirmationFailedWrongSchemeConfigured | Wrong scheme for confirmation |
| KmConfirmationFailedWrongSchemeConfigured | Wrong scheme for confirmation |
### Confirmation Send Failure Events (6)
| Code | Description |
|------|-------------|
| BuPaConfirmationSendFailed | Failed to send confirmation |
| BuPaRelConfirmationSendFailed | Failed to send confirmation |
| KmConfirmationSendFailed | Failed to send confirmation |
| BuPaConfirmationSendFailedHttpsSchemeExpected | HTTPS required for confirmation |
| BuPaRelConfirmationSendFailedHttpsSchemeExpected | HTTPS required for confirmation |
| KmConfirmationSendFailedHttpsSchemeExpected | HTTPS required for confirmation |
---
## Distribution Model Configuration (SOAP)
### Constraints
- BP Relationship model requires active Business Partner model
- Cannot deactivate BP model if active BP Relationship model exists
### Configuration Steps
1. Navigate to Master Data Integration (Orchestration)
2. Access Fiori Launchpad → Manage Distribution Model
3. Create model: Provider = SAP Master Data Integration
4. Set consumer = businessSystemId
5. Select Business Object Type: `sap.odm.businesspartner.BusinessPartner`
6. Set Package Size (max recommended: 50)
7. Select API: `MDI_SOAP_BUSINESS_PARTNER`
8. Configure scheduling
### Available Filters
- Authorization groups
- Country codes
- Customer information
- Supplier details
---
## API Documentation
**SAP Business Accelerator Hub**: [https://api.sap.com](https://api.sap.com) (filter: SAP Master Data Integration)
Note: Hub specifications are not tenant-specific and exclude custom extensions.
---
## Detailed Business Partner Service Nodes
### 1. BusinessPartner Node (Core)
| Field | Description | Necessity |
|-------|-------------|-----------|
| UUID | System identifier in receiver (empty on first replication) | Optional |
| CategoryCode | Organization/Natural person/Group classification | Optional |
| BlockedIndicator | Central blocking status | Optional |
| ReleasedIndicator | Business process eligibility | Optional |
| AuthorizationGroup | Authorization group assignment | Optional |
| ContactPermission | Contact permission controls | Optional |
### 2. Person Node (Natural Persons)
**Demographics**:
- Gender, Nationality, BirthDate, BirthPlace, DeathDate
**Communication Preferences**:
- VerbalCommunicationLanguageCode, WrittenCommunicationLanguageCode
**Personal Details**:
- MaritalStatus, Employer, Occupation
**Name Components**:
- GivenName, FamilyName, MiddleName, NickName, BirthName
- AcademicTitle, Prefix, Suffix (multiple supported)
### 3. Organization Node (Legal Entities)
| Field | Description |
|-------|-------------|
| FoundationDate | Date of establishment |
| LiquidationDate | Date of dissolution |
| LegalFormCode | Legal form classification |
| GlobalLocationNumber | GLN identifier |
| Name1-4 | Multi-line name fields |
| IndustrySector | Industry with classification system codes |
### 4. Identification Node
| Field | Description | Necessity |
|-------|-------------|-----------|
| IDNumber | Identification number | Optional |
| IDTypeCode | Type classification | Optional |
| EntryDate | Date of entry | Optional |
| ValidityStartDate/EndDate | Validity period | Optional |
| CountryCode | Geographic validity | Optional |
| RegionCode | Regional validity | Optional |
| IssuingAuthority | Authority reference | Optional |
### 5. BankDetails Node
| Field | Description | Necessity |
|-------|-------------|-----------|
| BankAccountID | Bank account identifier | **Mandatory** |
| ID | Account ID | **Mandatory** |
| CountryCode | Bank country | Optional |
| BankRoutingID | Routing number | Optional |
| IBAN | International bank account number | Optional |
| AccountHolderName | Name on account | Optional |
| ValidityStartDate/EndDate | Validity period | Optional |
### 6. TaxNumber Node
| Field | Description |
|-------|-------------|
| TaxIDNumber | Tax identification number |
| TaxNumberTypeCode | Type categorization |
| Multiple tax numbers supported per entity |
### 7. Role Node
| Field | Description |
|-------|-------------|
| RoleCode | Business function assignment |
| ValidityStartDate | Role start date |
| ValidityEndDate | Role end date |
| Multiple concurrent roles supported |
### 8. Business Partner Group Node
| Field | Description |
|-------|-------------|
| GroupTypeCode | Group type classification |
| PrimaryGroupName | Primary group identifier |
| SecondaryGroupName | Secondary group identifier |
| FormOfAddress | Address form specification |
### 9. Address Data Node (Comprehensive)
**Communication Elements**:
| Element | Fields |
|---------|--------|
| Email | Address, ValidityStartDate/EndDate, DefaultIndicator |
| Phone | CountryCode, SubscriberID, Extension, SMSCapability |
| Fax | CountryCode, DialingCode, Number |
| Website | URI, URITypeCode |
| Preferences | CommunicationLanguageCode, CommunicationMedium |
**Postal Components**:
| Category | Fields |
|----------|--------|
| Street | StreetName, StreetPrefix, StreetSuffix |
| Building | HouseNumber, HouseNumberSupplement, Building, Floor, RoomNumber |
| Postal | PostalCode (Street), POBoxPostalCode |
| Location | City, Region, County, District, CountryCode |
| Additional | CareOfName, TimeZone, TaxJurisdiction, TransportationZone |
**PO Box Address**:
- POBox, POBoxDeviatingCity, POBoxDeviatingRegion
- POBoxDeviatingCountry, DeliveryServiceType
**Script Variants**:
- AddressRepresentationCode (different character sets)
**Priority Rule**: When both CompanyPostalCode and POBoxPostalCode exist, CompanyPostalCode takes precedence.
### 10. Customer Node (Sales & Distribution)
**Classification**:
| Field | Description |
|-------|-------------|
| AccountGroupCode | Customer account group |
| CustomerGroupCode | Customer grouping |
| NielsenRegionCode | Nielsen region |
| IndustryCode1-5 | Industry classifications (up to 5) |
| BusinessTypeCode | Business type designation |
**Business Controls**:
| Field | Description |
|-------|-------------|
| OrderBlockReasonCode | Order blocking reason |
| BillingBlockReasonCode | Billing blocking reason |
| DeliveryBlockReasonCode | Delivery blocking reason |
| SalesSupportBlockReasonCode | Sales support block |
| PostingBlockReasonCode | Posting block |
| CentralDeletionFlag | Central deletion indicator |
**Financial**:
| Field | Description |
|-------|-------------|
| TaxGroupCode | Tax classification |
| AnnualSalesVolume | Annual sales with currency |
| AnnualSalesVolumeYear | Reference year |
| VATLiabilityIndicator | VAT liability |
| EqualizationTaxRelevance | Equalization tax |
**Condition Groups**: ConditionGroup1-5 (pricing)
**Extension Fields**: ExtensionCode1-10 (custom codes)
**Sales Arrangements**:
| Field | Description |
|-------|-------------|
| Incoterms | Delivery terms |
| TransferLocation | Transfer point |
| PartialDeliveryControl | Partial delivery settings |
| CompleteDeliveryControl | Complete delivery settings |
| SalesOrganizationGrouping | Sales org grouping |
| PriceGroupCode | Price group |
| CurrencyCode | Transaction currency |
| SalesGroupCode | Sales group |
### 11. Supplier Node (Procurement)
Similar structure to Customer node with procurement-specific attributes:
- Purchasing organization assignments
- Vendor classification codes
- Payment terms and conditions
- Procurement blocking reasons
---
## BP Relationship Service Detail
### BusinessPartnerRelationship Node
| Field | Description | Necessity |
|-------|-------------|-----------|
| RoleCode | Relationship category | Optional |
| StartDate | Validity start | Optional |
| EndDate | Validity end | Optional |
| RelationshipBusinessPartnerUUID | Related partner UUID | Optional |
| DefaultIndicator | Default when multiple exist | Optional |
### ContactPerson Node
**Contact Details**:
- BusinessPartnerFunctionalAreaCode (department)
- ContactPersonNote (comments)
- VIPReasonCode (importance indicator)
- BusinessPartnerFunctionTypeCode (job function)
- PowerOfAttorneyTypeCode (authority level)
**Receiver IDs**:
- SupplierContactPersonID
- CustomerContactPersonID
**Workplace Address**:
- DepartmentName, FunctionalTitle
- Building, Floor, Room
- CorrespondenceShortName
**Communication** (same structure as Address Data):
- Email, Telephone, Facsimile, WebURL
---
## Documentation Links
- **SOAP APIs**: [https://help.sap.com/docs/master-data-integration/sap-master-data-integration/soap-apis-for-business-partners](https://help.sap.com/docs/master-data-integration/sap-master-data-integration/soap-apis-for-business-partners)
- **Endpoints**: [https://help.sap.com/docs/master-data-integration/sap-master-data-integration/endpoints-for-soap-replication](https://help.sap.com/docs/master-data-integration/sap-master-data-integration/endpoints-for-soap-replication)
- **Partial Data Handling**: [https://help.sap.com/docs/master-data-integration/sap-master-data-integration/support-for-partial-data-handling](https://help.sap.com/docs/master-data-integration/sap-master-data-integration/support-for-partial-data-handling)
Reference in New Issue View Git Blame Copy Permalink