API de conciliación de facturas facturadas v2 (GA)
Se aplica a: Centro de partners (no disponible en la nube soberana)
Nuestra API asincrónica ofrece una manera más rápida y fácil de acceder a los datos de facturación y conciliación a través de blobs de Azure. Con esta API, no es necesario mantener abierta una conexión durante horas ni recorrer en bucle los lotes de 2000 elementos de línea a la vez.
Hemos optimizado nuestra nueva API de conciliación de facturas facturadas comerciales mediante 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.
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.
Ahora solo puede usar esta API para la nube pública o global de MS Graph. Aún no está disponible para Azure Government, Azure Alemania o Azure China 21Vianet.
Introducción a la API
Para recuperar los nuevos datos de conciliación de facturas comerciales facturados de forma asincrónica, use dos puntos de conexión de API. Este es el proceso:
Punto de conexión de conciliación de facturas facturadas
Use esta API para recuperar nuevos elementos de línea de conciliación de facturas facturadas de comercio . La API devuelve un estado HTTP 202 y un encabezado de ubicación que contiene una dirección URL. Sondee esta dirección URL a intervalos regulares hasta que reciba un estado correcto con una dirección URL de manifiesto.
Punto de conexión de estado de la operación
Para obtener un estado correcto, siga llamando a esta API a intervalos regulares. Si los datos no están listos, la respuesta de la API incluye un encabezado Retry-After para indicarle cuánto tiempo debe esperar antes de volver a intentarlo. Una vez completada la operación, obtendrá un recurso de manifiesto con una carpeta de almacenamiento donde puede descargar los datos de uso. La respuesta divide los archivos en partes más pequeñas para optimizar el rendimiento y el paralelismo de E/S.
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. El valor predeterminado es "full". (Consulte la lista de atributos de este artículo). 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.
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. En este artículo se enumeran otros posibles estados, en función de las solicitudes, en los estados de respuesta de la 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 comprobar el estado de una solicitud, espere una respuesta HTTP 200 con un estado de "correcto" o "error". Obtiene la dirección URL del manifiesto en el atributo "resourceLocation" si la solicitud se realiza correctamente.
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.
Cuerpo de la solicitud
N/D
Estado de respuesta
Además de los estados HTTP estándar enumerados en los estados de respuesta de la API estándar de este artículo, la API 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 | Hora en que se cambió por última vez el estado. Necesario. |
| resourceLocation | False | Identificador URI de la carga del manifiesto. Opcional. |
| error | False | Si se produce un error en la operación, los detalles del error se proporcionan en formato JSON. Opcional. Se incluyen los siguientes atributos: message: descripción detallada del error. code: el tipo de error que se produjo. |
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 | Identificador 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: 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". |
| 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 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 datos de conciliación de facturas facturados de Azure Blob Storage
Obtenga el token de firma de acceso compartido (SAS) y la ubicación de almacenamiento de blobs desde las propiedades "sasToken" y "rootDirectory" de la respuesta de la API de carga del manifiesto. SDK o herramienta de Azure Storage para descargar y descomprimir el archivo de blob. Está en el formato JSONLines .
Sugerencia
Consulte nuestro código de ejemplo para 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 | 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 - Prohibido | No tiene la autorización necesaria para realizar la solicitud. |
| 404: No encontrado | 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 una de sus dependencias no pueden cumplir la solicitud en este momento. Vuelva a intentarlo más tarde. |
Atributos de datos 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.
| Attribute | Completo | Basic |
|---|---|---|
| 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 obtener instrucciones sobre el uso de la API, consulte el vínculo siguiente que incluye código de ejemplo en C#.
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de