Description | Query Accounts |
Name | QueryCustomerIn |
Namespace | http://sap.com/xi/A1S/Global |
Process Component Description | Business Partner Data Management |
Process Component Name | BusinessPartnerDataManagement |
Process Component Namespace | http://sap.com/xi/AP/FO/BusinessPartner/Global |
Deployment Unit Description | Foundation |
Endpoint Activation | By Scoping of Process Component | Operations |
Release Status | Released |
An interface to query customer master data.
The web service interface Query Customer In enables you to connect external applications to your solution and to query and read accounts and their assigned contacts in your system. The web service interface Query Customer In is relevant if your company wants to access and manage business partner data from external applications.
The web service interface Query Customer In offers the operations Find By Identification, Find By Communication Data, and Find By Elements.
Here is an example of a simple web service request, which seeks for all customers with an Email address matching "*customer.com".
<n0:CustomerByCommunicationDataQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <CustomerSelectionByCommunicationData> <SelectionByEmailURI> <InclusionExclusionCode>I</InclusionExclusionCode> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <LowerBoundaryEmailURI>*customer.com</LowerBoundaryEmailURI> </SelectionByEmailURI> </CustomerSelectionByCommunicationData> <ProcessingConditions> <!--<QueryHitsMaximumNumberValue>10</QueryHitsMaximumNumberValue>--> <QueryHitsUnlimitedIndicator>true</QueryHitsUnlimitedIndicator> </ProcessingConditions> </n0:CustomerByCommunicationDataQuery_sync>
Here is an excerpt of the response of the request above including one of 10 customer records returned by the query:
<nm:CustomerByCommunicationDataResponse_sync xmlns:nm="http://sap.com/xi/SAPGlobal20/Global"> <Customer> <ChangeStateID>20100702104427.3216490</ChangeStateID> <UUID>00300571-cc0f-02db-b8c6-6cc9735cc23a</UUID> <InternalID>MS2400</InternalID> ... <Organisation> <FirstLineName>Customer Company</FirstLineName> </Organisation> <LegalCompetenceIndicator>true</LegalCompetenceIndicator> <DunAndBradstreetNumberID>101002400</DunAndBradstreetNumberID> <AddressInformation> ... <Address> <EmailURI>info@customer.com</EmailURI> ... </Address> </AddressInformation> <ContactPerson> <BusinessPartnerContactUUID>00300571-ce9b-1ded-89de-403b12aa5ec4</BusinessPartnerContactUUID> <BusinessPartnerContactInternalID>MSP2400</BusinessPartnerContactInternalID> <FormOfAddressCode>0002</FormOfAddressCode> <GivenName>Peter M.</GivenName> <FamilyName>Greene</FamilyName> ... </ContactPerson> ... </Customer> ... <ProcessingConditions> <ReturnedQueryHitsNumberValue>10</ReturnedQueryHitsNumberValue> <MoreHitsAvailableIndicator>false</MoreHitsAvailableIndicator> <LastReturnedObjectID>00300571CC0F02DBB8C79C6E3F1E8020</LastReturnedObjectID> </ProcessingConditions> </nm:CustomerByCommunicationDataResponse_sync>
All data (complete response):
Expected result:
<Customer> <full response... /> <Customer>
Request:
<RequestedElements customerTransmissionRequestCode='1'>
or (default is '1')
<RequestedElements />
or just omit it (default is all)
... empty ...
Return everything except address information:
Expected result:
<Customer> <all... except address information node /> </Customer>
Request:
<RequestedElements customerRequestCode='2'> <Customer addressInformationTransmissionRequestCode='4' /> </RequestedElements>
Return customer general data, address information and bank details:
Expected result:
<Customer> <InternalID>MCF-0001-SOS</InternalID> <…/> <AddressInformation> <…/> </AddressInformation> <BankDetails> <…/> </BankDetails> </Customer>
Request:
<RequestedElements customerTransmissionRequestCode='2'> <Customer addressInformationTransmissionRequestCode='2' bankDetailsTransmissionRequestCode='2' /> </RequestedElements>
Return customer general data, bank details, and all address information nodes:
Expected result:
<Customer> <InternalID>MCF-0001-SOS</InternalID> <…/> <BankDetails> <…/> </BankDetails> <AddressInformation> <…/> <Telephone> <…/> </Telephone> <PersonalAddress> <…/> </PersonalAddress> </AddressInformation> </Customer>
Request:
<RequestedElements customerTransmissionRequestCode='2'> <Material bankDetailsTransmissionRequestCode='2' addressInformationTransmissionRequestCode='1' /> </RequestedElements>
Return address information only:
Expected result:
<Customer> <InternalID>MCF-0001-SOS</InternalID> <AddressInformation> <…/> <PersonalAddress> <…/> </PersonalAddress> <Telephone> <…/> </Telephone> </AddressInformation> </Customer>
Request:
<RequestedElements customerTransmissionRequestCode='2'> <Material addressInformationTransmissionRequestCode='1' /> </RequestedElements>
You can find general information about Web services, their structure and consumption in the Web Services documentation.
The following example scenario can be carried out using requested elements.
E-Commerce Integration
The following example request returns all accounts with an e-mail address ending with "customer.com" including general data, contact person information, and sales arrangements.
<n0:CustomerByCommunicationDataQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <CustomerSelectionByCommunicationData> <SelectionByEmailURI> <InclusionExclusionCode>I</InclusionExclusionCode> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <LowerBoundaryEmailURI>*customer.com</LowerBoundaryEmailURI> </SelectionByEmailURI> </CustomerSelectionByCommunicationData> <ProcessingConditions> <QueryHitsUnlimitedIndicator>true</QueryHitsUnlimitedIndicator> </ProcessingConditions> <RequestedElements customerTransmissionRequestCode="2"> <Customer contactPersonTransmissionRequestCode="1" salesArrangementTransmissionRequestCode="1" personTransmissionRequestCode="1" organisationTransmissionRequestCode="1"/> </RequestedElements> </n0:CustomerByCommunicationDataQuery_sync>
The following example requests returns all accounts for which the given employee is responsible.
<n0:CustomerByElementsQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <CustomerSelectionByElements> <SelectionByResponsibleEmployeeUUID> <InclusionExclusionCode>I</InclusionExclusionCode> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <LowerBoundaryUUID>00163e03-390f-1ed2-a391-b1a36530b88f</LowerBoundaryUUID> </SelectionByResponsibleEmployeeUUID> </CustomerSelectionByElements> <ProcessingConditions> <QueryHitsUnlimitedIndicator>true</QueryHitsUnlimitedIndicator> </ProcessingConditions> </n0:CustomerByElementsQuery_sync>
Description | Find accounts using identification data |
Name | FindByIdentification |
Synchronous | yes |
Release Status | Released |
To find customer data by identification.
The request message of the operation FindByIdentification contains the CustomerSelectionByIdentification node that groups all possible selection parameters.
This node groups all selection parameters. The selection parameters are:
Selection Parameter | Remark |
---|---|
SelectionByInternalID | Selection by internal ID (Account ID) |
SelectionByUUID | Selection by UUID |
SelectionByCategoryCode | Selection by category code:1 Person (Private Account)2 Organization (Corporate Account) |
SelectionBusinessCharacterCode | Selection by business character code:Only prospect is available for Customer: BUP002 Prospect |
SelectionByBusinessPartnerID | Selection by business partner ID Should be used together with selection by party identifier type code. |
SelectionByPartyIdentifierTypeCode | Selection by party identifier type code Valid values for customer: BUP001 Dun & Bradstreet number BUP005 Global Location Number |
SelectionByBusinessPartnerName | Selection by business partner name:For Persons (Private Accounts): Last Name For Organizations (Corporate Accounts): Account Name |
SelectionByBusinessPartnerAdditionalName | Selection by business partner additional name:For Persons (Private Accounts): First Name For Organizations (Corporate Accounts):Additional name |
SelectionBySortingFormattedName | Selection by sorting formatted name |
SelectionByLifeCycleStatusCode | Selection by life cycle status code:1 In Preparation 2 Active 3 Blocked 4 Obsolete |
SelectionBySearchText | Selection by search text (basic search) |
The response contains the list of found accounts, log items, and processing conditions.
In this node, all found accounts are contained, including their account data according to the RequestedElements provided in the query request. This includes the ChangeStateID that may be needed for subsequent change requests via web services as well.
For each address of customers and contact persons the address UUID and the most current address snapshot UUID is returned by this service. Note that the address snapshot UUID is not available for customers and contact persons with status In Preparation.
If you want to change or display address data of business partners, use the AddressInformationUUID element.
In all other cases use the current address snapshot UUID (CurrentAddressSnapshotUUID and CurrentWorkplaceAddressSnapshotUUID elements) representing an address snapshot of this business partner address with the currently valid data. This applies particularly to all usages of the address within business processes or business transaction documents, such as sales orders, purchasing orders, outbound deliveries, or invoices.
The address snapshot contains exactly the same data as the business partner address, but it cannot be changed: If the business partner’s address changes, the address snapshot does not change, but a new address snapshot is created for each change of the business partner address instead.
Example: A business partner has an address in Paris. A sales order is created with a ship-to party using the currently valid address snapshot AddressSnapshotUUID_1. Then the business partner address is changed to Marseille. A new address snapshot AddressSnapshotUUID_2 with the address "Marseille" is created. However, the sales order is still referring to the older address snapshot with the address in Paris. This is intended behavior from a business point of view, since, for example, taxes and prices have been determined for Paris. However, if goods ordered now have to be delivered to Marseille instead, then the sales order needs to be updated with the new address referring to AddressSnapshotUUID_2.
Note that for all SAP-delivered business transaction documents, you must use the address snapshot UUID; you cannot use the address UUID.
Release | Change Description | Details |
1902 | Supporting MultiChannel for Document Output | The Customer node of the response structure was enhanced with node CommunicationArrangementMultiChannel and sub node CommunicationChannel |
1911 | Supporting Japan Invoice Summary Data | The Customer node of the response structure was enhanced with the elements InvoiceSummaryRoleCode and ClosingDatePatternID |
2002 | Supporting TransformationID for E-Invoicing | The CommunicationArrangement node and the CommunicationChannel node of the response structure were enhanced with the element TransformationID. |
Description | Find accounts using communication data |
Name | FindByCommunicationData |
Synchronous | yes |
Release Status | Released |
To find customer data by communication data.
The request message of the operation FindByCommunicationData contains the CustomerSelectionByCommunication node that groups all possible selection parameters.
This node groups all selection parameters. The selection parameters are as follows:
Selection Parameter | Remark |
---|---|
SelectionByNormalisedTelephoneNumber | Selection by normalized telephone number |
SelectionByNormalisedFacsimileNumber | Selection by normalized facsimile number |
SelectionByEmailURI | Selection by Email URI. The following Email addresses are considered by this parameter: Account Email addresses, related Contact Persons Email addresses, related Service Performers Email addresses and Employees Workplace Email addresses. |
SelectionByInternalID | Selection by internal ID (Account ID) |
SelectionByUUID | Selection by UUID |
SelectionByCategoryCode | Selection by category code:1 Person (Private Account) 2 Organization (Corporate Account) |
SelectionBusinessCharacterCode | Selection by business character code:Only prospect is available for Customer: BUP002 Prospect |
SelectionByBusinessPartnerName | Selection by Business Partner Name:For Persons (Private Accounts): Last Name For Organizations (Corporate Accounts): Account Name |
SelectionByBusinessPartnerAdditionalName | Selection by Business Partner Additional Name:For Persons (Private Accounts): First Name For Organizations (Corporate Accounts): Additional Name |
SelectionBySortingFormattedName | Selection by sorting formatted name |
SelectionByLifeCycleStatusCode | Selection by life cycle status code:1 In Preparation 2 Active 3 Blocked 4 Obsolete |
SelectionBySearchText | Selection by search text (Basic Search) |
The response of the Find By Communication Data operation is the same as for the Find By Identification operation.
Release | Change Description | Details |
1902 | Supporting MultiChannel for Document Output | The Customer node of the response structure was enhanced with node CommunicationArrangementMultiChannel and sub node CommunicationChannel |
1911 | Supporting Japan Invoice Summary Data | The Customer node of the response structure was enhanced with the elements InvoiceSummaryRoleCode and ClosingDatePatternID |
2005 | Supporting Mexico UseOfCFDI field | The Customer node of the response structure was enhanced with the element MXUseofCFDICode |
Description | Find accounts |
Name | FindByElements |
Synchronous | yes |
Release Status | Released |
To find customer data by elements.
The request message of the operation FindByElements contains the CustomerSelectionByElements node that groups all possible selection parameters.
This node groups all selection parameters. The selection parameters are as follows:
Selection Parameter | Remark |
---|---|
SelectionByInternalID | Selection by internal ID (Account ID) |
SelectionByUUID | Selection by UUID |
SelectionByCategoryCode | Selection by category code:1 Person (Private Account); 2 Organization |
SelectionByBusinessPartnerRoleCode | Selection by business partner role code:Only prospect is available for Customer: BUP002 Prospect |
SelectionByBusinessPartnerName | Selection by business partner name:For Persons (Private Accounts): Last Name For Organizations (Corporate Accounts): Account Name |
SelectionByBusinessPartnerAdditionalName | Selection by business partner additional name:For Persons (Private Accounts): First Name For Organizations (Corporate Accounts): Additional Name |
SelectionBySortingFormattedName | Selection by sorting formatted name |
SelectionByContactPersonWorkplaceEmailURI | Selection by contact person workplace e-mail address |
SelectionByLegalCompetenceIndicator | Selection by legal competence indicator specifying whether the customer is legally competent. |
SelectionBySelectionByAddressDefaultIndicator | Selection by default address indicator. |
SelectionByPostalAdressCityName | Selection by a city in the postal address, for example, "Walldorf" |
SelectionByPostalAddressStreetPostalCode | Selection by a postal code in a postal address, for example, "69124" in the case of "Heidelberg" |
SelectionByPostalAddressCountryCode | Selection by country code in a postal address, for example, "DE" for "Germany" |
SelectionByPostalAddressRegionCode | Selection by region code in a postal address which are specific for countries, for example, with List ID "DE" the value "08" would stand for "Baden-Wuerttemberg" |
SelectionByABCClassificationCode | Selection by ABC classification code:A A-Account B B-Account C C-Account |
SelectionByIndustrialSectorCode | Selection by industrial sector code |
SelectionByContactPersonInternalID | Selection by contact person internal ID |
SelectionByContactPersonUUID | Selection by UUID |
SelectionByContactPersonFamilyName | Selection by contact person family name |
SelectionByContactPersonGivenName | Selection by contact person given name |
SelectionByContactPersonSortingFormattedName | Selection by contact person sorting formatted name |
SelectionBySalesArrangementSalesOrganisationID | Selection by sales arrangement sales organization ID |
SelectionByCreatedSinceDate | Selection of all accounts that were created since the specified date |
SelectionByChangedSinceDate | Selection of all accounts that were changed since the specified date. The "changed since" date does not take into account changes of the response nodes ContactPerson, Relationship, CommunicationArrangement, DirectResponsibility, SalesArrangement, and PaymentData. |
SelectionByCreatedSinceDateTime | Selection of all accounts that were created since the specified point in time. |
SelectionByLastChangeSinceDateTime | Selection of all accounts that were changed since the specified point in time. The "changed since" date and time do not take into account changes of the response nodes ContactPerson, Relationship, CommunicationArrangement, DirectResponsibility, SalesArrangement, and PaymentData. |
SelectionByCreationDateTime | Selection of all accounts that were created during the specified time range. |
SelectionByCreationIdentityID | Selection by the ID of the identity that created the account. |
SelectionByLastChangeIdentityID | Selection by the ID of the identity that changed the account data at last. |
SelectionByLifeCycleStatusCode | Selection by life cycle status code:1 In Preparation 2 Active 3 Blocked 4 Obsolete |
SelectionBySearchText | Selection by search text (Basic Search) |
SelectionByResponsibleEmployeeUUID | Selection by employee responsible UUID |
SelectionByLastChangeDateTime | Selection of all accounts that were changed during the specified time range. |
The response of the FindByElements operation is the same as for the FindByIdentification operation.
Release | Change Description | Details |
1902 | Supporting MultiChannel for Document Output | The Customer node of the response structure was enhanced with node CommunicationArrangementMultiChannel and sub node CommunicationChannel |
1908 | Selection parameter SelectionByLastChangeDateTime is added | A range specification for last change is now possible |
1911 | Supporting Japan Invoice Summary Data | The Customer node of the response structure was enhanced with the elements InvoiceSummaryRoleCode and ClosingDatePatternID |
2005 | Supporting Mexico UseOfCFDI field | The Customer node of the response structure was enhanced with the element MXUseofCFDICode |