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#.

Partner-Center-Billing-Recon-Samples: ejemplos de API para obtener datos de conciliación de facturación del Centro de partners (github.com).