建立收益導出要求

發行項
11/13/2024

使用此 API 將新的收益和基礎交易/付款數據匯出要求排入佇列，並搭配選擇性篩選來切割收益和交易數據。它會傳回 202 HTTP 狀態和要求標識碼，可用來輪詢以檢查佇列交易導出要求的狀態。

將 POST 要求提交至 API 端點，以將交易/ 收益的新匯出要求排入佇列。

REST 要求

方法	要求 URI
POST	`https://api.partner.microsoft.com/v1.0/payouts/transactionhistory?$filter={$filter}&fileformat=csv`

要求參數

名稱	位於	必要	類型	描述
$filter	查詢	No	String	雖然它是選擇性篩選，但我們強烈建議使用篩選來加快效能，並限制匯出數據，而不是導出過去三年的數據。如需一組完整的$filter選項，請參閱下表。
fileFormat	查詢	No	String	支援的值為 .csv/.tsv。如果未提供任何值，則預設為 .csv。

$filter查詢參數是建立匯出作業的選擇性參數。不過，強烈建議使用 $filters，以提升導出報表的效能和更快的可用性。以下是一些可做為匯出作業一部分的索引鍵屬性篩選：

名稱	描述	類型	範例
`enrollmentParticipantId`	組織的已註冊 MPN 識別碼。	int	{baseUrl}`/v1.0/payouts/transactionhistory?$filter= enrollmentParticipantId=12345`
`EarningForDate`	匯出作業的收益期間日期。	Datetime	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=earningForDate ge 2023-03-01 and earningForDate le 2023-04-12`
`transactionAmount`	交易金額。	雙重	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=transactionAmount ge 2000 and transactionAmount le 5000`
`earningAmount`	以交易貨幣賺取金額。	雙重	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=earningAmount ge 2000 and earningAmount le 5000`
`engagementName`	僅適用於 Microsoft Commerce 獎勵。範例值 - `'Azure CSP motion incentives - Indirect Provider'`。	String	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=engagementName=’Azure CSP motion incentives’`
`payableSubType`	依收益類型進行篩選。範例值 - `'REBATE'`、、`'COOP'`、 `'FEE''SELL'`	String	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=payableSubType=’REBATE’ or payableSubType=’FEE’`
`payoutStatus`	依支付狀態篩選交易。範例值 - `'SENT'`、 `'UPCOMING'`、 `'IN PROGRESS'`	String	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=payoutStatus=’IN PROGRESS’`

具有多個要求參數的交易歷程記錄篩選範例：

”?$filter=earningForDate ge 2019-01-27T23:16:31.009Z and earningForDate le 2019-09-25T23:16:31.009Z and (enrollmentParticipantId eq 'XXXXXXX') and (programName eq ‘Microsoft Commerce Incentives’) and (payableSubType eq 'REBATE') and (paymentId eq '000000000000') and (engagementName eq 'Azure Enterprise and Self-Service Incentive' or engagementName eq 'Azure CSP motion incentives - Indirect Provider') and (leverCode eq ‘Azure Enterprise and Self-Service Motion’) and (payoutStatus eq 'SENT')”

要求標頭

名稱	必要	類型	描述
授權	Yes	String	授權持有人令牌。
ms-correlationid	No	String	內部要求追蹤器。每個要求都會產生新的追蹤器（GUID）。
ms-requestid	No	String	要求等冪標識碼。

若要深入瞭解，請參閱合作夥伴中心 REST 標頭

要求本文

N/A。

API 回應

HTTP/1.1 202 Accepted

API 回應承載會傳回下列屬性：

名稱	選擇性	描述
值	false	如需可能的值和動作，請參閱下表。

可能的值和動作

值	用戶端動作
requestId	匯出要求的要求標識碼
requestDateTime	匯出要求的起始日期時間
requestPath	匯出要求的查詢路徑。
requestQueryString	做為匯出要求的一部分使用的篩選。
blobLocation	匯出檔案就緒時具有令牌的 Blob 資源
狀態	匯出作業狀態。如需狀態，請參閱下列可能值的清單。

狀態的可能值

已排入佇列：匯出作業尚未啟動
處理：匯出作業正在進行中
失敗：重試之後匯出作業失敗，請嘗試將新要求排入佇列
已完成：匯出作業已完成，且導出檔案已準備好下載。

範例回覆

{
    "value": [
        {
            "requestId": "93c2b3cf-c6d8-4e7e-ade1-007768a6eba4",
            "requestDateTime": "2023-05-25T21:20:46.3727561Z",
            "requestPath": "/v1.0/payouts/transactionhistory",
            "requestQueryString": "earningForDate ge 2023-03-01 and earningForDate le 2023-04-12",
            "blobLocation": "",
            "status": "Queued"
        }
    ],
    "nextLink": null,
    "totalCount": 1
}

API 會傳回 HTTP 狀態 202。

名稱	描述
202 已接受	已接受要求。查詢要求狀態的 GET 要求 URL。

根據要求，API 可以傳回其他標準狀態：

名稱	描述
400 不正確的要求	數據遺失或不正確。
401 未經授權	呼叫端未通過驗證，且必須先向合作夥伴 API 服務進行驗證，才能進行第一次呼叫。
403 禁止	呼叫端無權提出要求。
500 內部伺服器錯誤	API 或其其中一個相依性無法滿足要求。請稍後再試一次。
404 找不到	輸入參數無法使用資源。
429 速率限制	相同類型的要求太多。請稍後再試一次。

共用方式為