Creare una richiesta di esportazione degli utili

Articolo
11/13/2024

Usare questa API per accodare nuovi utili e richieste di esportazione dei dati di pagamento/transazioni sottostanti con filtri facoltativi per filtrare e indezionare 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 accodare una nuova richiesta di esportazione per transazioni/utili.

Richiesta REST

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

Parametri della richiesta

Nome	Tra	Obbligatorio	Type	Descrizione
$filter	Query	No	String	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	Query	No	String	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	Tipo	Esempio
`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/Ora	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=earningForDate ge 2023-03-01 and earningForDate le 2023-04-12`
`transactionAmount`	Importo della transazione.	Double	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=transactionAmount ge 2000 and transactionAmount le 5000`
`earningAmount`	Importo degli utili nella valuta delle transazioni.	Double	{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'`.	String	{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'`	String	{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'`.	String	{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	Type	Descrizione
Autorizzazione	Sì	String	Token di connessione dell'autorizzazione.
ms-correlationid	No	String	Strumento di rilevamento delle richieste interno. Ogni richiesta genera un nuovo tracker (GUID).
ms-requestid	No	String	ID di idempotenza della richiesta.

Per altre informazioni, vedere Intestazioni REST del Centro per i partner

Corpo della richiesta

N/D.

Risposta dell'API

HTTP/1.1 202 Accepted

Il payload della risposta API restituisce gli attributi seguenti:

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

Valori e azioni possibili

Valore	Azione client
requestId	ID richiesta della richiesta di esportazione
requestDateTime	Data/ora di avvio della richiesta di esportazione
requestPath	Percorso della query della richiesta di esportazione.
requestQueryString	Filtro utilizzato come parte della richiesta di esportazione.
blobLocation	Risorsa BLOB con token quando il file di esportazione è pronto
Status	Esportare lo stato dell'operazione. Vedere l'elenco seguente dei valori possibili per lo stato.

Valori possibili per lo stato

Accodato: l'operazione di esportazione non è stata avviata
Elaborazione: l'operazione di esportazione è in corso
Operazione non riuscita: l'operazione di esportazione non è riuscita dopo i tentativi, provare a accodare una nuova richiesta
Completato: l'operazione di esportazione è stata 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 Negato	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.
404 Not Found	Risorsa non disponibile con i parametri di input.
429 Limitazione della frequenza	Troppe richieste dello stesso tipo. Prova dopo qualche minuto.

Condividi tramite