0% found this document useful (0 votes)
7 views22 pages

SalesInventoryReport APISpecification Vnet

Uploaded by

rizwana Umar
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
7 views22 pages

SalesInventoryReport APISpecification Vnet

Uploaded by

rizwana Umar
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 22

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 vNet - Sample Sales Report Request .........................................................................................................5
3.4 vNet - Sample Inventory Report Request .................................................................................................6
3.4 Response Specification .............................................................................................................................7
The following are the response codes that the API can return..............................................................................7
3.5 Sample Response ......................................................................................................................................7
3.6 Error Handling ...........................................................................................................................................7
4. Authentication ...................................................................................................................................................8
5. Steps for AAD Authentication ............................................................................................................................9
5.1 Create AAD Partner Tenant.......................................................................................................................9
5.2 Invite Users to Manage the Tenant ....................................................................................................... 13
5.3 Adding Administrators to the Tenant .................................................................................................... 15
5.4 Create an Application ............................................................................................................................. 17
5.5 Getting the Bearer Token....................................................................................................................... 22
5.6 Whitelisting ............................................................................................................................................ 22
5.7 Client ID and Scope ................................................................................................................................ 22

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 endpoints Kothai Ramanathan 2023/08/14
1.2 Updated Sample Sales and Inventory Reports for vNet Kothai Ramanathan 2023/09/14
1.3 Updated Client ID and Scope in Section 5.7 Kothai Ramanathan 2023/09/15
1.4 Added partner type in headers Kothai Ramanathan 2023/09/19
1.5 Added Tenant id in the Whitelisting section Kothai Ramanathan 2023/09/25
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/salesreportapi/send https://int.microsoft.com/salesreportapi/send
Inventory https://test.int.microsoft.com/inventoryreportapi/send https://int.microsoft.com/inventoryreportapi/send
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’
PartnerType Type of partner Distributor
Retailer
TransactionType 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>":"<value11>",
"<name2>":"<value12>",

"<namen>":"<value1n>"
},
{
"<name1>":"<value21>",
"<name2>":"<value22>",

"<namen>":"<value2n>"
},

]
}
3.3 vNet - Sample Sales Report Request
Headers
TransactionType SalesReport
PartnerName SYNCHXS
PartnerType Distributor
Channel
Frequency Daily
ReportStartDate 20230614
ReportEndDate 20230614
Content-Type application/json

Body
{
"items": [
{
"partnerOrgId": " 5219778",
"parnterName": " Synnex Distributions (China) Ltd",
"resendIndicator":"O",
"reportEndDate": "20230614",

"microsoftPartNumber": " 8QF-00041",


"sourceProductDescription":" Lp pGo2 i5/8/256 SC English China Pla inum",
"upcEanNumber": "",

"invoiceDate":" 20230614",
"invoiceNumber": "",
"salesQuantity": "4",
"returnQuantity": "0",

"shipToName":"360buy",
"shipToTaxId":" 110192562134916",
"shipToExternalId":"",
"shipToAddress": "北京市北京经济技术开发区科创十一街18号院C座2层201室 010-89126954",
"shipToAddress2": "",
"shipToCity":"北京",
"shipToToState":"",
"shipToPostalCode":"",
"shipToCountry":"",

"sellFromId": "", // this is for the outlet id for retailers


"sellFromName": "Synnex Shanghai",
"sellFromAddress": "上海",
"sellFromState": "",
"sellFromCity": "上海",
"sellFromCountry": "CHN",
"sellFromPostalCode": "110000",
}
]
}

3.4 vNet - Sample Inventory Report Request


Headers
TransactionType InventoryReport
PartnerName SYNCHXS
PartnerType Distributor
Channel
Frequency Weekly (assumed)
ReportStartDate 20230821 (assumed)
ReportEndDate 20230614
Content-Type application/json

Body
{
"items": [
{
"partnerOrgId": " 5219778",
"parnterName": " Synnex Distributions (China) Ltd",
"resendIndicator":"O",
"reportEndDate": " 20230614",

"microsoftPartNumber": " 8QF-00041 ",


"sourceProductDescription": “Lptp Go2 i5/8/256 ",
"upcEanNumber": "",
"onHandQuantity": "30",

"sellFromId": "1020", // this is for the outlet id for retailers


"sellFromName": "Synnex Chengdu",
"sellFromAddress": "成都",
"sellFromCity": "成都",
"sellFromState": "",
"sellFromCountry": "CHN",
"sellFromPostalCode": "110000"
}
]
}
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 Error Retry the call to the endpoint, as per your org guidelines. If
error persists, send email to [email protected]

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 [email protected] 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, the Enterprise Application Object 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, tenant id and the 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 5e820647-9c6d-48d7-8f0f-d124609614c6 api://5e820647-9c6d-48d7-8f0f-d124609614c6
Production 18bd3a34-5df5-4fd9-95c6-7c30f7bcba8e api://18bd3a34-5df5-4fd9-95c6-7c30f7bcba8e

You might also like