Creación de una solicitud de exportación de ganancias

Artículo
12/19/2023

Use esta API para poner en cola nuevas ganancias y transacciones subyacentes o solicitudes de exportación de datos de pagos con filtros opcionales para segmentar y desglosar los datos de ganancias y transacciones. Devuelve un estado HTTP 202 y un identificador de solicitud, que se puede usar para sondear de nuevo para comprobar el estado de la solicitud de exportación de transacciones en cola.

Envíe una solicitud POST al punto de conexión de API para poner en cola una nueva solicitud de exportación para transacciones o ganancias.

Solicitud REST

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

Parámetros de solicitud

Nombre	En	Obligatorio	Type	Descripción
$filter	Consultar	No	Cadena	Aunque es un filtro opcional, se recomienda encarecidamente usar filtros para un rendimiento más rápido y limitar los datos de exportación en lugar de exportar los últimos tres años de datos. Consulte la tabla siguiente para obtener un conjunto completo de opciones de $filter.
fileFormat	Consultar	No	Cadena	Los valores admitidos son .csv/.tsv. El valor predeterminado es .csv si no se proporciona ningún valor.

El parámetro de consulta $filter es un parámetro opcional para crear una operación de exportación. Sin embargo, se recomienda encarecidamente usar $filters para mejorar el rendimiento y una mayor disponibilidad del informe de exportación. A continuación se muestran algunos de los filtros de atributo clave que se pueden usar como parte de la operación de exportación:

Nombre	Description	Tipo	Ejemplo
`enrollmentParticipantId`	Id. de MPN inscrito de la organización.	Int	{baseUrl}`/v1.0/payouts/transactionhistory?$filter= enrollmentParticipantId=12345`
`EarningForDate`	Fecha de período de ganancia para la operación de exportación.	DateTime	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=earningForDate ge 2023-03-01 and earningForDate le 2023-04-12`
`transactionAmount`	Importe de la transacción.	Doble	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=transactionAmount ge 2000 and transactionAmount le 5000`
`earningAmount`	Importe de la ganancia en moneda de transacción.	Doble	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=earningAmount ge 2000 and earningAmount le 5000`
`engagementName`	Aplicable solo a los incentivos comerciales de Microsoft. Valores de ejemplo: `'Azure CSP motion incentives - Indirect Provider'`.	Cadena	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=engagementName=’Azure CSP motion incentives’`
`payableSubType`	Filtre por el tipo de ganancia. Valores de ejemplo: `'REBATE'`, `'COOP'`, `'FEE'`, `'SELL'`	Cadena	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=payableSubType=’REBATE’ or payableSubType=’FEE’`
`payoutStatus`	Filtre las transacciones por el estado de pago. Valores de ejemplo: `'SENT'`, `'UPCOMING'`, `'IN PROGRESS'`.	Cadena	{baseUrl}`/v1.0/payouts/transactionhistory?$filter=?$filter=payoutStatus=’IN PROGRESS’`

Filtro de historial de transacciones de ejemplo con varios parámetros de solicitud:

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

Encabezado de solicitud

Nombre	Obligatorio	Type	Descripción
Authorization	Sí	Cadena	Token de portador de autorización.
ms-correlationid	No	Cadena	Un rastreador de solicitudes interno. Cada solicitud genera un nuevo rastreador (GUID).
ms-requestid	No	Cadena	Identificador de idempotency de solicitud.

Para más información, consulte Encabezados REST del Centro de partners.

Cuerpo de la solicitud

N/D

Respuesta de la API

HTTP/1.1 202 Accepted

La carga de respuesta de la API devuelve los atributos siguientes:

Nombre	Opcionales	Descripción
Valor	false	Consulte la tabla siguiente para ver los posibles valores y acciones.

Valores y acciones posibles

Valor	Acción del cliente
requestId	Identificador de solicitud de la solicitud de exportación
requestDateTime	Fecha y hora de inicio de la solicitud de exportación
requestPath	Ruta de acceso de consulta de la solicitud de exportación.
requestQueryString	Filtro usado como parte de la solicitud de exportación.
blobLocation	Recurso de blob con token cuando el archivo de exportación está listo
Estado	Estado de la operación de exportación. Consulte la siguiente lista de valores posibles para el estado.

Valores posibles para el estado

En cola: la operación de exportación no se ha iniciado
Procesamiento: la operación de exportación está en curso
Error: error en la operación de exportación después de reintentos, intente poner en cola una nueva solicitud.
Completado: la operación de exportación se completó y el archivo de exportación está listo para su descarga.

Respuesta de muestra

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

LA API devuelve el estado HTTP 202.

Nombre	Descripción
202 - Aceptado	Se aceptó la solicitud. Consulte la dirección URL de solicitud GET para el estado de la solicitud.

En función de la solicitud, la API puede devolver otros estados estándar:

Nombre	Descripción
400 Solicitud incorrecta	Faltaban datos o eran incorrectos.
401 No autorizado	El autor de la llamada no está autenticado y debe autenticarse con el servicio de API de asociado antes de realizar la primera llamada.
403 Prohibida	El autor de la llamada no está autorizado para realizar la solicitud.
500 Error interno del servidor	La API o una de sus dependencias no pueden cumplir la solicitud. Vuelva a intentarlo más tarde.
404 No encontrado	Recurso no disponible con parámetros de entrada.
429 Limitación de velocidad	Demasiadas solicitudes del mismo tipo. Pruebe después de algún tiempo.

Compartir vía