Creare una richiesta di esportazione degli utili

Articolo
03/11/2025

Utilizzare questa API per accodare nuove richieste di esportazione dei dati relativi agli utili e alle transazioni/pagamenti sottostanti, utilizzando filtri facoltativi per analizzare e segmentare i dati sugli utili e sulle transazioni. Restituisce uno stato HTTP 202 e un ID richiesta, che può essere usato per eseguire il pollback per controllare lo stato della richiesta di esportazione delle transazioni in coda.

Inviare una richiesta POST all'endpoint API per mettere in coda una nuova richiesta di esportazione di transazioni/guadagni.

Richiesta REST

Metodo	URI della richiesta
POST	`https://api.partner.microsoft.com/v1.0/payouts/transactionhistory?$filter={$filter}&fileformat=csv`

Parametri della richiesta

Nome	In	Obbligatorio	Digitare	Descrizione
$filter	Quesito	No	Stringa	Anche se si tratta di un filtro facoltativo, è consigliabile usare filtri per prestazioni più veloci e limitare i dati di esportazione anziché esportare gli ultimi tre anni di dati. Per un set completo di opzioni di $filter, vedere la tabella seguente.
fileFormat	Quesito	No	Stringa	I valori supportati sono .csv/.tsv. L'impostazione predefinita è .csv se non viene specificato alcun valore.

Il parametro della query $filter è un parametro facoltativo per la creazione di un'operazione di esportazione. È tuttavia consigliabile usare $filters per ottenere prestazioni migliori e una maggiore disponibilità del report di esportazione. Di seguito sono riportati alcuni dei filtri dell'attributo chiave che possono essere usati come parte dell'operazione di esportazione:

Nome	Descrizione	Digitare	Campione
`enrollmentParticipantId`	ID MPN registrato dell'organizzazione.	Int	{baseUrl}`/v1.0/payouts/transactionhistory?$filter= enrollmentParticipantId=12345`
`EarningForDate`	Data del periodo di guadagno per l'operazione di esportazione.	Data e Ora	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=earningForDate ge 2023-03-01 and earningForDate le 2023-04-12`
`transactionAmount`	Importo della transazione.	Doppio	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=transactionAmount ge 2000 and transactionAmount le 5000`
`earningAmount`	Importo degli utili nella valuta delle transazioni.	Doppio	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=earningAmount ge 2000 and earningAmount le 5000`
`engagementName`	Applicabile solo per gli incentivi per il commercio Microsoft. Valori di esempio: `'Azure CSP motion incentives - Indirect Provider'`.	Stringa	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=engagementName=’Azure CSP motion incentives’`
`payableSubType`	Filtra in base al tipo di guadagno. Valori di esempio: `'REBATE'`, `'COOP'`, `'FEE'`, `'SELL'`	Stringa	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=payableSubType=’REBATE’ or payableSubType=’FEE’`
`payoutStatus`	Filtrare le transazioni in base allo stato dei proventi. Valori di esempio: `'SENT'`, `'UPCOMING'`, `'IN PROGRESS'`.	Stringa	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=payoutStatus=’IN PROGRESS’`

Filtro della cronologia delle transazioni di esempio con più parametri di richiesta:

”?$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')”

Intestazione della richiesta

Nome	Obbligatorio	Digitare	Descrizione
Autorizzazione	Sì	Stringa	Token di autorizzazione tipo bearer.
ms-correlationid	No	Stringa	Strumento di rilevamento delle richieste interno. Ogni richiesta genera un nuovo tracker (GUID).
ms-requestid	No	Stringa	ID di idempotenza della richiesta.

Per ulteriori informazioni, vedere intestazioni REST del Partner Center

Corpo della richiesta

N/D.

Risposta API

HTTP/1.1 202 Accepted

Il payload della risposta API restituisce gli attributi seguenti:

Nome	Opzionale	Descrizione
Valore	falso	Per i valori e le azioni possibili, vedere la tabella seguente.

Valori e azioni possibili

Valore	Azione cliente
ID richiesta	ID della richiesta di esportazione
requestDateTime	Data/ora di avvio della richiesta di esportazione
percorso della richiesta	Percorso della richiesta di esportazione.
requestQueryString	Filtro utilizzato come parte della richiesta di esportazione.
posizione del blob	Risorsa BLOB con token quando il file di esportazione è pronto
Stato	Stato dell'operazione di esportazione. Vedere l'elenco seguente dei valori possibili per lo stato.

Valori possibili per lo stato

in coda: l'operazione di esportazione non è stata avviata
elaborazione: l'operazione di esportazione è in corso
Non riuscito: l'operazione di esportazione è fallita dopo alcuni tentativi, prova ad accodare una nuova richiesta
Completato: operazione di esportazione completata e il file di esportazione è pronto per il download.

Risposta di esempio

{
    "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
}

L'API restituisce lo stato HTTP 202.

Nome	Descrizione
202 Accettato	La richiesta è stata accettata. Eseguire una query sull'URL della richiesta GET per ottenere lo stato della richiesta.

A seconda della richiesta, l'API può restituire altri stati standard:

Nome	Descrizione
400 Richiesta non valida	Dati mancanti o non corretti.
401 Non autorizzato	Il chiamante non è autenticato e deve eseguire l'autenticazione con il servizio API partner prima di effettuare la prima chiamata.
403 Vietato	Il chiamante non è autorizzato a effettuare la richiesta.
500 Errore interno del server	L'API o una delle relative dipendenze non è in grado di soddisfare la richiesta. Riprovare più tardi.
404 Non trovato	Risorsa non disponibile con i parametri di input.
429 Limitazione della frequenza	Troppe richieste dello stesso tipo. Prova dopo qualche minuto.

Condividi tramite