API de conciliación de facturas facturadas v2 (GA)
Se aplica a: Centro de partners (no disponible en la nube soberana)
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.
La nueva API de conciliación de facturas facturadas de comercio usa técnicas avanzadas, como la clave de valet y los patrones asincrónicos de solicitud-respuesta . Esta API proporciona 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 facturas facturados.
Nuestra API usa técnicas optimizadas para aumentar su eficiencia, por lo que puede lograr resultados más rápidos con menos esfuerzo. Adopte esta API para simplificar el acceso a los datos y mejorar la eficacia general.
Nota:
La nueva API no se hospeda en el host de la API del Centro de partners. En su lugar, puede encontrarlo en MS Graph en Uso de Microsoft Graph API para exportar datos de facturación de asociados: Microsoft Graph v1.0. Para acceder a esta API, consulte los detalles siguientes.
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.
Introducción a la API
Para ayudarle a recuperar los nuevos elementos de línea de conciliación de factura comercial facturados de forma asincrónica, ofrecemos dos puntos de conexión de API clave. Esta es una guía simplificada para empezar a trabajar:
Punto de conexión de conciliación de facturas facturadas
En primer lugar, use esta API para capturar nuevos elementos de línea de conciliación de facturas facturadas de 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 nuevos datos de conciliación de facturas comerciales.
Secuencia de acciones del usuario
Para recuperar los datos de conciliación de facturas facturadas, 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 conciliación de facturas facturados
Solicitud a la API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export
Accept: application/json
Content-Type: application/json
{
"invoiceId": "G016907411",
"attributeSet": "basic"
}
Parámetros de consulta
N/D
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. |
| invoiceId | True | String | Un identificador único para cada factura. Necesario. |
Encabezados de solicitud
Solicite encabezados para la API mediante los pasos que se enumeran en Procedimientos recomendados para usar Microsoft Graph. Al seguir estas instrucciones, se garantiza la confiabilidad y la compatibilidad con la aplicación. Su atención a los detalles de este paso es fundamental para una integración sin problemas y un rendimiento óptimo.
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. |
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
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 | String | Identificador único para comprobar el estado de la solicitud. Necesario. |
Encabezado de solicitud
Solicite encabezados para la API mediante los pasos que se enumeran en Procedimientos recomendados para usar Microsoft Graph. Al seguir estas instrucciones, se garantiza la confiabilidad y la compatibilidad con la aplicación. Su atención a los detalles de este paso es fundamental para una integración sin problemas y un rendimiento óptimo.
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 | Un 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. Se genera un nuevo valor cada vez que se produce un cambio en la información de facturación. |
| 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 detalles siguientes: name y partitionValue |
| nombre | Nombre del blob. |
| partitionValue | Partición que contiene el archivo. Partición que contiene el archivo. Las particiones grandes se dividen en varios archivos, cada uno 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 cuando los datos siguen procesando.
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": "0e195b37-4574-4539-bc42-0e539b9684c0",
"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 los elementos de línea de conciliación de facturas facturados 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 obtenga 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: sin datos disponibles | El sistema no tiene datos para los parámetros de entrada proporcionados. |
Atributos de elemento de línea de conciliación de facturas facturadas
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 obtener más información sobre estos atributos, consulte Uso del archivo de conciliación.
| Attribute | Completo | Básico |
|---|---|---|
| PartnerId | sí | sí |
| CustomerId | sí | sí |
| CustomerName | sí | sí |
| CustomerDomainName | sí | no |
| CustomerCountry | sí | no |
| InvoiceNumber | sí | sí |
| MpnId | sí | no |
| Tier2MpnId | sí | sí |
| OrderId | sí | sí |
| OrderDate | sí | sí |
| ProductId | sí | sí |
| SkuId | sí | sí |
| AvailabilityId | sí | sí |
| SkuName | sí | no |
| ProductName | sí | sí |
| ChargeType | sí | sí |
| UnitPrice | sí | sí |
| Cantidad | sí | no |
| Subtotal | sí | sí |
| TaxTotal | sí | sí |
| Total | sí | sí |
| Moneda | sí | sí |
| PriceAdjustmentDescription | sí | sí |
| PublisherName | sí | sí |
| PublisherId | sí | no |
| SubscriptionDescription | sí | no |
| SubscriptionId | sí | sí |
| ChargeStartDate | sí | sí |
| ChargeEndDate | sí | sí |
| TermAndBillingCycle | sí | sí |
| EffectiveUnitPrice | sí | sí |
| UnitType | sí | no |
| AlternateId | sí | no |
| BillableQuantity | sí | sí |
| BillingFrequency | sí | no |
| PricingCurrency | sí | sí |
| PCToBCExchangeRate | sí | sí |
| PCToBCExchangeRateDate | sí | no |
| MeterDescription | sí | no |
| ReservationOrderId | sí | sí |
| CreditReasonCode | sí | sí |
| SubscriptionStartDate | sí | sí |
| SubscriptionEndDate | sí | sí |
| ReferenceId | sí | sí |
| ProductQualifiers | sí | no |
| PromotionId | sí | sí |
| ProductCategory | sí | sí |
Código de ejemplo
Para usar esta API, consulte el vínculo siguiente, que incluye código de ejemplo de C#.