Partilhar via


Criar solicitação de exportação de ganhos

Use esta API para enfileirar novos ganhos e solicitações de exportação de dados de transações/pagamentos subjacentes com filtros opcionais para fatiar e segmentar os dados de ganhos e transações. Ele retorna um status HTTP 202 e uma ID de solicitação, que pode ser usada para pesquisar de volta para verificar o status da solicitação de exportação de transação enfileirada.

Envie uma solicitação POST para o ponto de extremidade da API para enfileirar uma nova solicitação de exportação para transações/ganhos.

Pedido REST

Método URI do pedido
POST https://api.partner.microsoft.com/v1.0/payouts/transactionhistory?$filter={$filter}&fileformat=csv

Parâmetros de solicitação

Nome Está presente em Obrigatório Type Description
$filter Query Não String Embora seja um filtro opcional, é altamente recomendável usar filtros para um desempenho mais rápido e limitar seus dados de exportação em vez de exportar os últimos três anos de dados. Consulte a tabela a seguir para obter um conjunto completo de opções de $filter.
fileFormat Query Não String Os valores suportados são .csv/.tsv. O padrão é .csv se nenhum valor for fornecido.

O $filter query param é um parâmetro opcional para criar uma operação de exportação. No entanto, é altamente recomendável usar $filters para um melhor desempenho e uma disponibilidade mais rápida do relatório de exportação. A seguir estão alguns dos principais filtros de atributos que podem ser usados como parte da operação de exportação:

Nome Descrição Type Exemplo
enrollmentParticipantId ID MPN inscrito da organização. Int {baseUrl}/v1.0/payouts/transactionhistory?$filter= enrollmentParticipantId=12345
EarningForDate Data do período de ganho para a operação de exportação. DateTime {baseUrl}/v1.0/payouts/transactionhistory?$filter=earningForDate ge 2023-03-01 and earningForDate le 2023-04-12
transactionAmount Valor da transação. Duplo {baseUrl}/v1.0/payouts/transactionhistory?$filter=?$filter=transactionAmount ge 2000 and transactionAmount le 5000
earningAmount Valor de ganho na moeda da transação. Duplo {baseUrl}/v1.0/payouts/transactionhistory?$filter=?$filter=earningAmount ge 2000 and earningAmount le 5000
engagementName Aplicável apenas para Incentivos de Comércio da Microsoft. Valores de exemplo - 'Azure CSP motion incentives - Indirect Provider'. String {baseUrl}/v1.0/payouts/transactionhistory?$filter=?$filter=engagementName=’Azure CSP motion incentives’
payableSubType Filtrar pelo tipo de ganho. Valores de exemplo - 'REBATE', , , 'COOP''FEE''SELL' String {baseUrl}/v1.0/payouts/transactionhistory?$filter=?$filter=payableSubType=’REBATE’ or payableSubType=’FEE’
payoutStatus Filtre as transações pelo estado do pagamento. Valores de exemplo - 'SENT', , 'IN PROGRESS''UPCOMING'. String {baseUrl}/v1.0/payouts/transactionhistory?$filter=?$filter=payoutStatus=’IN PROGRESS’

Exemplo de filtro de histórico de transações com vários parâmetros de solicitação:

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

Cabeçalho do pedido

Nome Obrigatório Type Description
Autorização Sim String Token de portador de autorização.
MS-CorrelationID Não String Um rastreador de solicitações internas. Cada solicitação gera um novo rastreador (GUID).
MS-RequestID Não String O ID de idempotência da solicitação.

Para saber mais, consulte Cabeçalhos REST do Partner Center

Corpo do pedido

N/D.

Resposta da API

HTTP/1.1 202 Accepted

A carga útil de resposta da API retorna os seguintes atributos:

Nome Opcional Description
valor false Consulte a tabela a seguir para obter os valores e ações possíveis.

Valores e ações possíveis

valor Ação do cliente
requestId ID do pedido de exportação
requestDateTime Data/hora de início do pedido de exportação
requestPath Caminho de consulta da solicitação de exportação.
requestQueryString Filtro usado como parte da solicitação de exportação.
blobLocalização Recurso de Blob com token quando o arquivo de exportação estiver pronto
Status Status da operação de exportação. Consulte a seguinte lista de valores possíveis para status.

Valores possíveis para o status

  • Em fila: a operação de exportação não foi iniciada
  • Processamento: A operação de exportação está em andamento
  • Falha: A operação de exportação falhou após tentativas, tente enfileirar uma nova solicitação
  • Concluído: A operação de exportação foi concluída e o arquivo de exportação está pronto para download.

Resposta da amostra

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

A API retorna o status HTTP 202.

Nome Descrição
202 Aceito O pedido foi aceite. Consulte o URL da solicitação GET para obter o status da solicitação.

Dependendo da solicitação, a API pode retornar outros status padrão:

Nome Descrição
400 Pedido Incorreto Havia dados ausentes ou incorretos.
401 Não Autorizado O chamador não é autenticado e deve autenticar-se com o serviço de API do parceiro antes de fazer a primeira chamada.
403 Proibido O chamador não está autorizado a fazer a solicitação.
500 Erro de Servidor Interno A API ou uma de suas dependências não consegue atender à solicitação. Tente novamente mais tarde.
404 Não Encontrado Recurso não disponível com parâmetros de entrada.
429 Limitação da taxa Demasiados pedidos do mesmo tipo. Tente depois de algum tempo.