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.
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 . 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.
Nuestras API usan técnicas optimizadas para aumentar su eficiencia, por lo que puede lograr resultados más rápidos con menos esfuerzo. Adopte estas API para simplificar el acceso a los datos y mejorar la eficacia general.
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.
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.
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. Esta es una guía simplificada para empezar a trabajar:
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 la disponibilidad. 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, es posible que no vea los datos de uso no facturados diarios más recientes hasta que estén disponibles los datos de uso facturados del mes anterior. Una vez que reciba los datos de uso facturados, podrá recuperar todos los datos de uso no facturados actualizados desde el inicio del mes.
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 | String | Para obtener el uso diario clasificado para el mes actual o el último mes natural o período de facturación, use "current" o "last" (igual que "anterior" en la API v1). Necesario. |
| currencyCode | True | String | 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 | String | 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. Compruebe la lista de atributos de 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 ver otros estados posibles en función de las solicitudes, consulte 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 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
Parámetros de solicitud
| Nombre | Incluir en | Obligatorio | Type | Descripción |
|---|---|---|---|---|
| operationId | URI de solicitud | True | String | 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" y, a continuación, realice otra llamada para comprobar el estado. running: espere el tiempo especificado en el encabezado "Retry-After" y, a continuación, 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. No establezca un número fijo de elementos de línea o tamaño de archivo en el código, ya que estos valores pueden 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, con cada archivo que contiene 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 | PUBLICAR |
| 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¤cyCode=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
Para comparar los atributos devueltos por la API de conciliación de facturas facturadas para los conjuntos de atributos "completos" o "básicos", consulte la tabla siguiente. Para más información sobre estos atributos, consulte esta documentación.
| Attribute | 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 migrar de la API v1 de la versión 2.
Cada nombre de atributo comienza ahora con una letra mayúscula .
unitOfMeasure se actualiza a Unit. Su significado y valor permanecen sin cambios.
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. Por ejemplo, el 0,15 es ahora el 15 %.
rateOfCredit es ahora CreditPercentage. El nombre y el valor han cambiado. 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.