Criar solicitação de exportação de lucros

Artigo
11/13/2024

Use essa API para enfileirar novos ganhos e solicitações de exportação de dados de transações/pagamentos subjacentes com filtros opcionais para fatiar os dados de ganhos e transações. Ele retorna um status HTTP 202 e uma ID de solicitação, que pode ser usada para fazer uma sondagem 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.

Solicitação REST

Método	URI da solicitação
POST	`https://api.partner.microsoft.com/v1.0/payouts/transactionhistory?$filter={$filter}&fileformat=csv`

Parâmetros da solicitação

Nome	Em	Obrigatório	Type	Descrição
$filter	Consulta	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	Consulta	Não	String	Os valores suportados são .csv/.tsv. O padrão é .csv se nenhum valor for fornecido.

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

Nome	Descrição	Type	Amostra
`enrollmentParticipantId`	ID do MPN registrado 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.	Double	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=transactionAmount ge 2000 and transactionAmount le 5000`
`earningAmount`	Valor de ganho em moeda de transação.	Double	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=earningAmount ge 2000 and earningAmount le 5000`
`engagementName`	Aplicável apenas para os Incentivos do Microsoft Commerce. Valores de exemplo - `'Azure CSP motion incentives - Indirect Provider'`.	String	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=engagementName=’Azure CSP motion incentives’`
`payableSubType`	Filtre 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 status de 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 da solicitação

Nome	Obrigatória	Type	Descrição
Autorização	Sim	String	Token de portador de autorização.
ms-correlationid	Não	String	Um rastreador de solicitações interno. 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 da solicitação

N/D

Resposta da API

HTTP/1.1 202 Accepted

A carga de resposta da API retorna os seguintes atributos:

Nome	Opcional	Descrição
Valor	false	Consulte a tabela a seguir para obter possíveis valores e ações.

Valores e ações possíveis

Valor	Ação do cliente
requestId	ID da solicitação de exportação
requestDateTime	Data/hora de início da solicitação 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 lista a seguir de valores possíveis para status.

Valores possíveis para status

Enfileirado: 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 de exemplo

{
    "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	A solicitação foi aceita. Consulte a 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 Solicitação Incorreta	Havia dados ausentes ou incorretos.
401 Não Autorizado	O chamador não é autenticado e deve autenticar 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.
Erro interno de servidor 500	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	Muitos pedidos do mesmo tipo. Tente depois de algum tempo.

Compartilhar via