API de conciliación de uso facturada y no facturada diaria v2 (GA)

Se aplica a: Centro de partners (no disponible en Azure Government o Azure China 21Vianet).

Nuestra nueva API asincrónica ofrece una manera más rápida y eficaz de acceder a los datos de facturación y conciliación a través de blobs de Azure. En lugar de mantener abierta una conexión durante horas o procesar lotes de 2000 elementos de línea, ahora puede simplificar el flujo de trabajo, reducir la carga del servidor y mejorar los tiempos de procesamiento de datos.

Las nuevas API de conciliación de uso calificadas diariamente de comercio usan técnicas avanzadas como la clave de valet y los patrones asincrónicos de solicitud-respuesta . El patrón de clave de valet permite un acceso seguro a los recursos sin compartir credenciales, mientras que el patrón asincrónico de solicitud-respuesta permite una comunicación eficaz entre sistemas.

Estas API proporcionan un token de firma de acceso compartido (SAS) que puede usar para acceder a todos los atributos o a un subconjunto de los datos de conciliación de uso clasificados diariamente. Este token mejora la seguridad al conceder acceso a tiempo limitado y ofrece flexibilidad en la administración de permisos de acceso a datos.

Al adoptar nuestras API optimizadas, puede lograr resultados más rápidos con menos esfuerzo, simplificar el acceso a los datos y mejorar la eficacia general. Adopte estas herramientas para simplificar el flujo de trabajo y administrar los permisos de forma más eficaz.

Nota:

Las nuevas API no se hospedan en el host de api del Centro de partners. En su lugar, puede encontrarlos en MS Graph en Uso de Microsoft Graph API para exportar datos de facturación de asociados: Microsoft Graph v1.0 | Microsoft Learn. Para acceder a estas API, consulte los detalles siguientes.

Ahora solo puede usar estas API para la nube pública o global de MS Graph. Aún no están disponibles para Azure Government o Azure China 21Vianet.

Importante

Para permitir que la aplicación acceda a los datos de facturación de asociados, siga este vínculo y familiarícese con los conceptos básicos de autenticación y autorización de Microsoft Graph. Este paso es fundamental, ya que garantiza que la aplicación pueda acceder de forma segura a los datos necesarios.

Puede asignar el permiso "PartnerBilling.Read.All" mediante Azure Portal o el Centro de administración de Entra. A continuación, se indica cómo puede hacerlo.

• Registre la aplicación en la página principal de Microsoft Entra en la sección Registros de aplicaciones.
• Para conceder el permiso necesario, vaya a la página Aplicación de Microsoft Entra. En la sección Permisos de API, seleccione "Agregar un permiso" y elija el ámbito "PartnerBilling.Read.All".

Al completar estos pasos, asegúrese de que la aplicación tiene el acceso necesario a los datos de facturación de asociados.

Nota:

Si ha estado usando nuestra versión beta, es probable que encuentre la transición a la versión de disponibilidad general (GA) fluida e intuitiva. Para ayudarle a comprender las actualizaciones y mejoras, se recomienda comparar las versiones beta y GA. Comprender estas actualizaciones le ayudará a maximizar las nuevas características y mejoras disponibles en la versión de disponibilidad general.

Importante

El nuevo uso diario del comercio no incluye los cargos por estos productos:

• Reserva de Azure
• Plan de ahorro de Azure
• Office
• Dynamics
• Microsoft Power Apps
• Software perpetuo
• Suscripción de software
• Producto SaaS que no es de Microsoft o Marketplace

Introducción a la API

Para ayudarle a recuperar los nuevos artículos de línea de uso diario facturados diariamente de forma asincrónica, ofrecemos dos puntos de conexión clave de API. Siga esta guía simplificada para empezar a trabajar de forma rápida y eficaz.

Punto de conexión de elemento de línea de uso

En primer lugar, use esta API para capturar nuevos elementos de línea de uso clasificados diariamente por el comercio . Al realizar una solicitud, recibirá un estado HTTP 202 y un encabezado de ubicación con una dirección URL. Sondee esta dirección URL con regularidad hasta que obtenga un estado correcto y una dirección URL de manifiesto.

Punto de conexión de estado de la operación

A continuación, siga comprobando el estado de la operación llamando a esta API a intervalos regulares. Si los datos no están listos, la respuesta incluye un encabezado Retry-After que indica cuánto tiempo debe esperar antes de volver a intentarlo. Una vez completada la operación, recibirá un recurso de manifiesto con un vínculo de carpeta de almacenamiento para descargar los datos de uso. La respuesta segmenta los archivos para mejorar el rendimiento y permitir el paralelismo de E/S.

Siguiendo estos pasos, puede administrar eficazmente el proceso de conciliación de facturas.

Diagrama de secuencia

Este es un diagrama de secuencia que muestra los pasos para descargar los datos de conciliación.

Secuencia de acciones del usuario

Para recuperar nuevos artículos de línea de conciliación de uso con clasificación diaria comercial, siga estos pasos:

Paso 1: Enviar solicitud

Envíe una solicitud POST al punto de conexión de API.

Obtención de elementos de línea de uso no facturados diarios

Obtenga nuevos artículos de línea de uso no facturados diariamente para el mes actual o el último mes natural o período de facturación.

Nota:

Puede acceder a los elementos de línea de uso no facturados diariamente a través de la API o el portal del Centro de partners. Para garantizar la precisión de los datos, permita hasta 24 horas para que estén disponibles. Dependiendo de su ubicación y cuando los medidores notifiquen el uso, puede haber más retrasos.

Priorizamos la entrega del tiempo de los datos de uso valorados diariamente en primer lugar. En ocasiones, los datos de uso más recientes clasificados por día sin facturar podrían no aparecer hasta que se encuentren disponibles los datos facturados del mes previo. Una vez que reciba los datos facturados, podrá acceder a todos los datos de uso no facturados actualizados desde el inicio del mes.

puntos clave:

• Espere hasta 24 horas para que los datos estén disponibles.
• Podría haber más retrasos dependiendo de tu ubicación y los tiempos de envío de informes de los medidores.
• Los datos de uso valorados diariamente facturados se priorizan por encima de los datos no facturados.

Su comprensión y paciencia se aprecian a medida que nos esforzamos por proporcionar la información más precisa y oportuna posible.

Solicitud a la API

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export

Accept: application/json

Content-Type: application/json

{

"currencyCode": "USD",

"billingPeriod": "current",

"attributeSet": "basic"

}

Cuerpo de la solicitud

Atributo	Obligatorio	Type	Descripción
attributeSet	False	Cadena	Elija "full" para todos los atributos o "básico" para un conjunto limitado. Si no se especifica, "full" es el valor predeterminado. Compruebe la lista de atributos de esta sección. Opcional.
billingPeriod	True	Cadena	Para obtener el uso diario no facturado, use "actual" para el período de facturación actual o "último" para el período de facturación anterior (equivalente a "anterior" en la API v1). Necesario.
currencyCode	True	Cadena	Código de moneda de facturación de partners. Necesario.

Encabezados de solicitud

Para solicitar encabezados para la API, consulte Confiabilidad y soporte técnico.

Respuesta de la API

HTTP/1.1 202 Accepted  
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Normalmente, la API responde con un estado HTTP 202. También puede encontrar otros estados en función de las solicitudes. Estos estados se enumeran en la sección Estados de respuesta de api estándar .

Código	Descripción
202 – Aceptado	Se aceptó la solicitud. Para comprobar el estado de la solicitud, consulte la dirección URL proporcionada en el encabezado de ubicación.

Obtención de elementos de línea de uso valorados diariamente facturados

Obtenga nuevos artículos de línea de uso facturados diariamente para una factura para el período de facturación cerrado.

Solicitud a la API

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export

{  
"invoiceId": "G00012345",  
"attributeSet": "full"  
}

Parámetros de consulta

N/D

Cuerpo de la solicitud

Atributo	Obligatorio	Type	Descripción
invoiceId	True	Cadena	Un identificador único para cada factura. Necesario.
attributeSet	False	Cadena	Elija "full" para todos los atributos o "básico" para un conjunto limitado. Si no se especifica, "full" es el valor predeterminado. Revise la lista de atributos de en esta sección. Opcional.

Encabezado de solicitud

Encabezados de solicitud para la API. Para más información, consulte la confiabilidad y la compatibilidad.

Respuesta de la API

HTTP/1.1 202 Aceptado
Ubicación: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Cuando se usa la API, normalmente devuelve un estado HTTP 202. Para otros estados posibles según sus peticiones, consulte los estados.

Código	Descripción
202 – Aceptado	Se aceptó la solicitud. Para comprobar el estado de la solicitud, consulte la dirección URL proporcionada en el encabezado de ubicación.

Paso 2: Comprobar el estado de la solicitud

Para realizar un seguimiento del estado de una solicitud, asegúrese de recibir una respuesta HTTP 200 que es un código de estado estándar que indica "correcto" o "error". Si se ejecuta correctamente, encontrará la dirección URL del manifiesto en el atributo "resourceLocation". Este atributo proporciona un punto de conexión para acceder a la información necesaria.

Obtener el estado de la operación

Recupera el estado de una solicitud.

Solicitud a la API

GET https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Parámetros de solicitud

Nombre	Incluir en	Obligatorio	Type	Descripción
operationId	URI de solicitud	True	Cadena	Identificador único para comprobar el estado de la solicitud. Necesario.

Encabezado de solicitud

Para solicitar encabezados para la API, consulte Confiabilidad y soporte técnico.

Cuerpo de la solicitud

N/A.

Estado de respuesta

Además de los estados HTTP estándar enumerados en los estados de respuesta de la API estándar, la API también puede devolver el siguiente estado HTTP:

Código	Descripción
410 – Desaparecido	El vínculo de manifiesto expira después de una hora establecida. Para obtener de nuevo el vínculo del manifiesto, envíe una nueva solicitud.

Carga de respuesta

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

Atributo	Obligatorio	Descripción
id	True	Identificador único para cada respuesta. Necesario.
status	True	Valores y acciones: Obligatorio: notstarted: espere el tiempo especificado en el encabezado "Retry-After" antes de hacer otra llamada para comprobar el estado. running: espere la duración especificada en el encabezado "Retry-After" y luego realice otra llamada para comprobar el estado. correcto: los datos están listos. Recupere la carga del manifiesto mediante el URI especificado en resourceLocation. failed: la operación no se pudo realizar de forma permanente. Reinícielo.
createdDateTime	True	Hora a la que se realizó la solicitud. Necesario.
lastActionDateTime	True	La última vez que cambió el estado. Necesario.
resourceLocation	False	Identificador URI de la carga del manifiesto. Opcional.
error	False	Detalles sobre los errores, proporcionados en formato JSON. Opcional. Atributos incluidos: message: Descripción del error. code: el tipo de error.

Objeto de ubicación de recursos

Atributo	Descripción
id	Identificador único del manifiesto.
schemaVersion	Versión del esquema del manifiesto.
dataFormat	Formato del archivo de datos de facturación. compressedJSON: formato de datos donde cada blob es un archivo comprimido que contiene datos en formato de líneas JSON . Para recuperar los datos de cada blob, descomprima.
createdDateTime	Fecha y hora en que se creó el archivo de manifiesto.
eTag	Versión de los datos del manifiesto. Un cambio en la información de facturación genera un nuevo valor.
partnerTenantId	Id. de Microsoft Entra del inquilino del asociado.
rootDirectory	Directorio raíz del archivo.
sasToken	Token de SAS (firma de acceso compartido) que le permite leer todos los archivos del directorio.
partitionType	Divide los datos en varios blobs en función del atributo "partitionValue". El sistema divide las particiones que superan el número admitido. De forma predeterminada, los datos se particionan en función del número de elementos de línea del archivo. Evite codificar los recuentos de elementos de línea o los tamaños de archivo, ya que podrían cambiar.
blobCount	Número total de archivos para este identificador de inquilino del asociado.
blobs	Matriz JSON de objetos "blob" que contienen los detalles del archivo para el identificador de inquilino del asociado.
objeto de blob	Objeto que contiene los siguientes detalles: name y partitionValue
nombre	Nombre del blob.
partitionValue	Partición que contiene el archivo. La partición grande se divide en varios archivos en función de determinados criterios, como el tamaño del archivo o el número de registros, cada archivo conteniendo el mismo "partitionValue".

Solicitud a la API

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Respuesta de la API

La respuesta recomienda esperar 10 segundos antes de intentarlo de nuevo al procesar datos.

HTTP/1.1 200 OK  
Retry-After: 10  
{  
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",  
"createdDateTime": "2022-06-1T10-01-03.4Z",  
"lastActionDateTime": "2022-06-1T10-01-05Z",  
"status": "running"  
}

Solicitud a la API

(10 segundos después de la solicitud anterior...)

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Respuesta de la API

La API devuelve el estado "correcto" y el URI de "resourceLocation".

HTTP/1.1 200 OK  
Content-Type: application/json  
{

    "@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",

    "@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",

    "id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",

    "createdDateTime": "2023-12-05T21:17:29Z",

    "lastActionDateTime": "2023-12-05T21:18:00.8897902Z",

    "status": "succeeded",

    "resourceLocation": {

        "id": "44e8500b-ab92-490e-8ac3-90500a1d3427",

        "createdDateTime": "2023-11-06T19:58:47.513Z",

        "schemaVersion": "2",

        "dataFormat": "compressedJSON",

        "partitionType": "default",

        "eTag": "RwDrn7fbiTXy6UULE",

        "partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",

        "rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",

        "sasToken": "{token}",

        "blobCount": 1,

        "blobs": \[

            {

                "name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",

                "partitionValue": "default"

            }

        \]

    }

}

Paso 3: Descarga de elementos de línea de conciliación de uso clasificados diariamente de Azure Blob Storage

En primer lugar, debe obtener el token de firma de acceso compartido (SAS) y la ubicación de Blob Storage. Puede encontrar estos detalles en las propiedades "sasToken" y "rootDirectory" de la respuesta de la API de carga de manifiesto. Después, para descargar y descomprimir el archivo de blob, use el SDK o la herramienta de Azure Storage. Está en el formato JSONLines .

Sugerencia

Asegúrese de consultar nuestro código de ejemplo. Muestra cómo descargar y descomprimir el archivo de blob de Azure en la base de datos local.

Estados de respuesta de API estándar

Es posible que reciba estos estados HTTP de la respuesta de la API:

Código	Descripción
400: Solicitud incorrecta	Falta la solicitud o contiene datos incorrectos. Compruebe el cuerpo de la respuesta para obtener los detalles del error.
401 - No autorizado	Se requiere autenticación antes de realizar la primera llamada. Autentíquese con el servicio de API del asociado.
403 - Prohibido	No tiene la autorización necesaria para realizar la solicitud.
404 – Not Found	Los recursos solicitados no están disponibles con los parámetros de entrada proporcionados.
410 – Desaparecido	El vínculo del manifiesto ya no es válido ni activo. Envíe una nueva solicitud.
500: Error interno del servidor	La API o sus dependencias no pueden cumplir la solicitud en este momento. Vuelva a intentarlo más tarde.
5000: no hay datos disponibles	El sistema no tiene datos para los parámetros de entrada proporcionados.

Comparación de versiones beta y de disponibilidad general

Consulte la tabla de comparación para ver las diferencias entre las versiones beta y las versiones de disponibilidad general (GA). Si actualmente usa la versión beta, la transición a la versión de disponibilidad general es sencilla y sencilla.

Información importante	Beta	Disponible en general
Punto de conexión de host de API	https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/
HTTP method	POST	POST
Punto de conexión de API de uso no facturado diario	https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
Parámetros de entrada para la API de uso diaria no facturada	Para especificar parámetros en la solicitud de API, inclúyelos en la cadena de consulta de la dirección URL de la solicitud. Por ejemplo, para especificar los parámetros period y currencyCode, anexe ?period=current&currencyCode=usd a la dirección URL de la solicitud.	Para proporcionar entradas, incluya un objeto JSON en el cuerpo de la solicitud. El json debe tener las siguientes propiedades: * currencyCode: su moneda de facturación. Por ejemplo, USD. * billingPeriod: período de facturación de la factura. Por ejemplo, actual. Este es un objeto JSON de ejemplo que incluye las propiedades currencyCode y billingPeriod:<br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>}
Punto de conexión de API de uso diario facturado	https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId}	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
Parámetros de entrada para la API de uso diaria facturada	Para especificar parámetros en la solicitud de API, incluya invoiceId en la dirección URL de la solicitud. Además, puede incluir un parámetro de fragmento opcional en la cadena de consulta para recuperar el conjunto completo de atributos. Por ejemplo, para recuperar el conjunto completo de atributos, anexe ?fragment=full a la dirección URL de la solicitud.	Para proporcionar entradas, incluya un objeto JSON en el cuerpo de la solicitud. El json debe tener las siguientes propiedades: * invoiceId: identificador único de la factura. Por ejemplo, G00012345. * attributeSet: los atributos que deben estar en la respuesta, como full. Este es un objeto JSON de ejemplo que incluye las propiedades invoiceId y attributeSet: {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>}
Recurso de manifiesto	Use un método GET /manifests/{id} independiente para recuperar el recurso de manifiesto.	Use el método GET /operations/{Id} para acceder al recurso de manifiesto en resourceLocation. Este método ahorra tiempo eliminando la necesidad de una llamada independiente a GET /manifests/{id}.
Cambios en el esquema del manifiesto
	"id": No disponible	"id": identificador único para el recurso de manifiesto.
	"version": Disponible	"version": cambiado a "schemaversion".
	"dataFormat": Disponible	"dataFormat": disponible.
	"utcCretedDateTime": disponible	"utcCretedDateTime": se cambió a "createdDateTime".
	"eTag": Disponible	"eTag": Disponible.
	"partnerTenantId": disponible	"partnerTenantId": disponible
	"rootFolder": Disponible	"rootFolder": cambiado a "rootDirectory".
	"rootFolderSAS": disponible	"rootFolderSAS": cambiado a "sasToken". Esta actualización proporciona solo el token sin la ruta de acceso del directorio raíz. Para buscar el directorio, use la propiedad "rootDirectory" en su lugar.
	"partitionType": Disponible	"partitionType": disponible.
	"blobCount": disponible	"blobCount": disponible.
	"sizeInBytes": Disponible	"sizeInBytes": no disponible.
	"blobs": disponible	"blobs": disponible.
	"blob object": disponible	"blob object": disponible.
	"name": Disponible	"name": Disponible.
	"partitionValue": Disponible	"partitionValue": disponible.

Atributos de elemento de línea de conciliación de uso clasificados diariamente

Consulte esta tabla para comparar los atributos devueltos por la API de conciliación de uso tanto facturada como no facturada para los conjuntos de atributos "completos" o "básicos". Para obtener más información sobre estos atributos y sus significados, consulte esta documentación de .

Atributo	Completo	Básico
PartnerId	sí	sí
PartnerName	sí	sí
CustomerId	sí	sí
CustomerName	sí	Sí
CustomerDomainName	sí	no
CustomerCountry	sí	no
MpnId	sí	no
Tier2MpnId	sí	no
InvoiceNumber	sí	sí
ProductId	sí	sí
SkuId	sí	sí
AvailabilityId	sí	no
SkuName	sí	sí
ProductName	sí	no
PublisherName	sí	sí
PublisherId	sí	no
SubscriptionDescription	sí	no
SubscriptionId	sí	sí
ChargeStartDate	sí	sí
ChargeEndDate	sí	sí
UsageDate	sí	sí
MeterType	sí	no
MeterCategory	sí	no
MeterId	sí	no
MeterSubCategory	sí	no
MeterName	sí	no
MeterRegion	sí	no
Unidad	sí	sí
ResourceLocation	sí	no
ConsumedService	sí	no
ResourceGroup	sí	no
ResourceURI	sí	sí
ChargeType	sí	sí
UnitPrice	sí	sí
Cantidad	sí	sí
UnitType	sí	no
BillingPreTaxTotal	sí	sí
BillingCurrency	sí	sí
PricingPreTaxTotal	sí	sí
PricingCurrency	sí	sí
ServiceInfo1	sí	no
ServiceInfo2	sí	no
Etiquetas	sí	no
AdditionalInfo	sí	no
EffectiveUnitPrice	sí	sí
PCToBCExchangeRate	sí	sí
PCToBCExchangeRateDate	sí	no
EntitlementId	sí	sí
EntitlementDescription	sí	no
PartnerEarnedCreditPercentage	sí	no
CreditPercentage	sí	sí
CreditType	sí	sí
BenefitOrderID	sí	sí
BenefitID	sí	no
BenefitType	sí	sí

Importante

Tome nota de estos cambios al pasar de API v1 a v2.

• Cada nombre de atributo comienza ahora con una letra mayúsculas para mantener la coherencia con el archivo y mejorar la legibilidad.

• unitOfMeasure se actualiza a Unit. Su significado y valor permanecen sin cambios, lo que simplifica el nombre del atributo.

• resellerMpnId ahora es Tier2MpnId. El significado y el valor son los mismos.

• rateOfPartnerEarnedCredit se actualiza a PartnerEarnedCreditPercentage. El nuevo nombre y el valor ahora reflejan el porcentaje en lugar de la fracción, lo que facilita la comprensión. Por ejemplo, el 0,15 es ahora el 15 %.

• rateOfCredit es ahora CreditPercentage. Tanto el nombre como el valor han cambiado para proporcionar una comprensión más clara. Por ejemplo, el 1,00 ahora es del 100 %.

Creemos que estos cambios hacen que las API sean más intuitivas y fáciles de usar.

Código de ejemplo

Para usar esta API, consulte el vínculo siguiente, que incluye código de ejemplo de C#.

Ejemplos de API del Centro de partners: obtener datos de conciliación de facturación.