Sales & Inventory Report API Specification

Azure Integration Services (AIS)

Contents
1. Overview .............................................................................................................................................. 3
2. API Endpoint ......................................................................................................................................... 3
3. API Specification ................................................................................................................................... 4
3.1 Request Header ........................................................................................................................... 4
3.2 Request Specification .................................................................................................................. 4
3.3 Sample Request ........................................................................................................................... 5
4.3 Sample Response ......................................................................................................................... 6
4.4 Error Handling.............................................................................................................................. 6
4. Authentication...................................................................................................................................... 7
5. Steps for AAD Authentication .............................................................................................................. 8
5.1 Create AAD Partner Tenant ......................................................................................................... 8
5.2 Invite Users to Manage the Tenant ........................................................................................... 12
5.3 Adding Administrators to the Tenant ........................................................................................ 14
5.4 Create an Application ................................................................................................................ 16
5.5 Getting the Bearer Token .......................................................................................................... 21
5.6 Whitelisting................................................................................................................................ 21
5.7 Client ID and Scope .................................................................................................................... 21

Change History

Version Change Description Author Date

1.0 Initial Write Kothai Ramanathan 2023/07/21
1.1 Updated Sample requests, Error codes, Retries and end points Kothai Ramanathan 2023/08/14
Sales and Inventory Report Integration API
1. Overview
External Partners, who are either Resellers or Distributors, report their Sales and Inventory numbers to
Microsoft. This will include the sales and return quantities made, and the stock of the inventory at the
Partner end. These sales and inventory reports are processed by the Microsoft Sales Team, to enable
Partner incentive and Microsoft seller’s compensation payments.
Azure Integration Services (AIS) is the Integration Layer that will receive the reports from the Partners. It
performs the required validations, data mapping and conversion to Microsoft Sales file format before
posting the data to Microsoft Sales.

For this purpose, Sales and Inventory Report APIs are exposed by AIS. Partners can post their
sales/inventory numbers by calling these APIs.

2. API Endpoint
The following are the endpoints to which a sales report will be posted.

Type Pre-Production Production

Sales Report https://test.int.microsoft.com/api/salesreport https://int.microsoft.com/api/salesreport
Inventory https://test.int.microsoft.com/api/inventoryreport https://int.microsoft.com/api/inventoryreport
Report
3. API Specification
3.1 Request Header
Attribute Description Comments Accepted Values
PartnerName Name of the partner who is calling Mandatory
the API
Channel Additional channel specification – say Mandatory; if not
country, subsidiary, etc. applicable, say
‘None’
Type Type of report that is sent Mandatory SalesReport
InventoryReport
Frequency Frequency in which the report is sent Mandatory Daily
Weekly
Monthly
Quarterly
HalfYearly
Yearly
ReportStartDate Report Start Date YYYYMMDD
ReportEndDate Report End Date YYYYMMDD
Authentication Bearer Token for the AAD Client Bearer <bearer token>

3.2 Request Specification

The request body will be a Json. This will be in the format shown below. If any field is null, still
mention the field, and provide empty value for it.

{
"items": [
{
"<name1>":"<value1>",
"<name2>":"<value2>",
…
"<namen>":"<valuen>"
},
{
"<name1>":"<value1>",
"<name2>":"<value2>",
…
"<namen>":"<valuen>"
},
…
]
}
3.3 Sample Request
Headers

TransactionType SalesReport
PartnerName Bango
Channel US
Frequency Weekly
ReportStartDate 20030401
ReportEndDate 20030407
Content-Type application/json

Body
{
"items": [
{
"resendIndicator":"",
"partnerOrgId": "",
"parnterName": "Bango US",
"microsoftPartNumber": "3ZI-00001",
"upcEanNumber": "",
"sourceProductDescription":"",
"resellerTaxId":"",
"resellerName":"USA_VERIZON",
"resellerAddress": "1 Verizon Way",
"resellerAddress2": "Basking Ridge",
"resellerCity":"",
"resellerState":"New Jersey",
"resellerPostalCode":"O7920",
"resellerCountry":"United States",
"invoiceDate":"01-04-2023",
"invoiceNumber": "",
"salesQuantity": "1508",
"returnQuantity": "0"
},
{
"resendIndicator":"",
"partnerOrgId": "",
"parnterName": "Bango US",
"microsoftPartNumber": "41A-00003",
"upcEanNumber": "",
"sourceProductDescription":"",
"resellerTaxId":"",
"resellerName":"USA_VERIZON",
"resellerAddress": "1 Verizon Way",
"resellerAddress2": "Basking Ridge",
"resellerCity":"",
"resellerState":"New Jersey",
 "resellerPostalCode":"O7920",
"resellerCountry":"United States",
"invoiceDate":"02-04-2023",
"invoiceNumber": "",
"salesQuantity": "377",
"returnQuantity": "0"
}
]
}

3.4 Response Specification

The following are the response codes that the API can return.

Response Code Description Action Needed

202 Accepted None
400 Bad request Correct the JSON content sent to the API.
401 Unauthorized Check and send the right bearer token in the header.
500 Internal Server Retry the call to the endpoint, as per your org
Error guidelines. If error persists, send an email to
aisdri@microsoft.com

3.5 Sample Response

202 Accepted
{"InterchangeId":"<guid>"}

The processing of the report is asynchronous. 202 Response only means that the request is
accepted. This guid reference can be used for any tracking purposes.

3.6 Error Handling

For any queries or failure issues, email EDMHelp@microsoft.com for support.
4. Authentication
Microsoft recommends Azure Active Directory (AAD) authentication for the Partners to call Microsoft API
end points. Below are the high-level steps that would be required from Partners to set up AAD
Authentication. For detailed instructions, see the next Section “Steps for AAD Authentication”.

1. Create an AAD Tenant (if not already available).

2. Invite Users to Manage the Tenant.
3. Create an application in that AAD Tenant.
4. Generate an OAuth bearer-token for that application.
5. Provide that bearer-token in the Authentication header when calling the API.
6. Share the AAD Tenant id, App id, and the IP Address from which the API calls will be made. This
will be used for whitelisting the same at Microsoft end.
5. Steps for AAD Authentication
5.1 Create AAD Partner Tenant
This step can be skipped if an AAD Tenant is already available at the Partner end. If it is not available,
below are the steps to be followed, which do not incur any cost. To start off, this requires a Microsoft
Account (MSA Account like Outlook account, Live account, or Hotmail account). However, once the
AAD Tenant is created, there need not be any dependency on this MSA account, as Users from the
Partner’s Org can be invited to join and manage this account.

1. Log in to Microsoft Azure portal using the MSA account.

2. Search for AAD in the Top Search Bar. Click on ‘Azure Active Directory’.

3. Click on Manage Tenants as shown below.

4. Create a Tenant

5. For tenant type, leave the default value of “Azure Active Directory” and click Next.
6. Provide Organization Name, Domain Name and Location as appropriate, and click Next.

7. Review the details and say “Create”.

8. The Tenant would be created, which could take a few minutes.

9. Once the tenant is created, navigate to the new tenant.

10. You should be able to see the Tenant AAD like the below.
5.2 Invite Users to Manage the Tenant
1. Click on Users under the Tenant.

2. In the Users page, the user who created the Tenant is listed by default.
3. Here click on New User -> Invite External User

4. Provide the required details as appropriate and click Review+Invite, Invite. Here the user could
be the user from the Partner Organization, who can manage the Tenant.
5. The person invited will get an email in their Inbox. Accept the Invitation.

6. Now the User would be listed under AAD->Users.

7. Repeat this for as many Users as needed.
5.3 Adding Administrators to the Tenant
6. Choose “Roles and administrators” in the Tenant.

7. Filter for “global” and choose “Global Administrators”

8. Click on “Add Assignment” as shown below. And select the user who should be Administrators for
the Tenant. Repeat this to add all required users who would be Administrators.

9. The Global Administrator Users can now login to the Azure Portal to the Tenant created for the
Organization. They will be able to add further Users to the Azure Active Directory.

10. Manage the Users and their roles by adding / removing them accordingly. Assignments can be
removed or downgraded by using the following.
5.4 Create an Application
1. Click on App Registrations
2. Click on New registration.

3. Provide any appropriate name for the application and say Register.

4. Wait till the application is created.

5. Note the Client ID of the application.
6. Click on Certificates & Secrets

7. Click on “New Client Secret”

8. Provide a name and expiry as appropriate and say Add.

9. Copy the value of the secret and store it in an appropriate storage as per your Organization’s
guidelines. This value will not be retrievable later. This is the Client Secret.
10. Add an Application ID. Provide an appropriate name and say Save.
11. Define the Scope of the API. Provide details as appropriate to your Organization.
12. Authorize Client Application, as shown in the below snapshot. The Client IDs to be provided are
shown in section “5.7 Client Id and Scope”.

13. Note the endpoint from which the bearer token needs to be generated.
5.5 Getting the Bearer Token
When calling the AIS API to send the report, in the header pass the Bearer Token. Below are the details
for getting the bearer token.

End point from where the token has to be got: As mentioned in step 5.4.13. Below are the parameters
to be sent in the body:

Body: grant_type client_credentials

Body: client_id As got in step 5.4.5
Body: client_secret As got in step 5.4.9
Body: scope As provided in table 5.7

5.6 Whitelisting
Share the application id and IP address from which the API call will be made. These are required for
whitelisting them at Microsoft end.

5.7 Client ID and Scope

Environment Client ID Scope
Test 02a17ff5-24f1-4777-85ad-17e8c9200fb2 https://www.microsoft.com/AISPublicAPIAADAppTest
Production 5fde1c9c-b0eb-490a-8077-11acde75ab34 https://www.microsoft.com/AISPublicAPIAADAppProd