{"meta":{"title":"Automatización de informes de uso con la API de REST","intro":"Descubre cómo automatizar los informes sobre el uso de características de pago mediante la API de REST.","product":"Facturación y pagos","breadcrumbs":[{"href":"/es/billing","title":"Facturación y pagos"},{"href":"/es/billing/tutorials","title":"Tutoriales"},{"href":"/es/billing/tutorials/automate-usage-reporting","title":"Automatización de informes de uso"}],"documentType":"article"},"body":"# Automatización de informes de uso con la API de REST\n\nDescubre cómo automatizar los informes sobre el uso de características de pago mediante la API de REST.\n\nDespués de realizar la transición a la facturación de uso medido, es posible que desee realizar un seguimiento automático del uso y los costos de las funciones de pago GitHub en los sistemas de informes internos. Por ejemplo, es posible que quiera supervisar el gasto con el tiempo, conciliar facturas o proporcionar datos de uso a las herramientas de finanzas o BI.\n\nEn este tutorial, aprenderá a usar la API REST para recuperar datos de uso de facturación, filtrarlos por período de tiempo o centro de costos y automatizar informes periódicos en el nivel de usuario, organización o empresa. También aprenderá a interpretar los campos clave en la respuesta para que pueda convertir los datos de uso sin procesar en conclusiones de costos significativas.\n\n## Prerrequisitos\n\nAntes de comenzar este tutorial, asegúrese de que:\n\n* Tiene acceso a los datos de facturación en el nivel en el que desea informar:\n  * Informes de nivel de usuario: titular de la cuenta\n  * Informes de nivel de organización: propietario de la organización o administrador de facturación\n  * Informes de nivel empresarial: administrador de empresa o administrador de facturación\n\n* Está familiarizado con la realización de solicitudes autenticadas a la API REST. Para obtener una introducción, consulta [Mediante la API de REST](/es/rest/using-the-rest-api).\n\n* Se autentica mediante un personal access token (classic). Los puntos de conexión de uso de facturación no admiten fine-grained personal access tokens.\n\nEn función de sus necesidades de informes, también puede que desee acceder a un sistema interno (como una hoja de cálculo, una base de datos o una herramienta de BI), donde puede almacenar y analizar los datos de uso recuperados de la API.\n\n## Paso 1: Decidir el nivel en el que se va a informar\n\nDecida en qué nivel de cuenta desea informar. Esto determina **qué punto de conexión de la API REST llamarás** y qué incluirá tu informe.\n\nElija el nivel de informes que mejor se adapte a su objetivo:\n\n| Nivel de informes | Cuándo se debe usar                                                                                                                                          |\n| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **Usuario**       | Quiere un informe de una sola cuenta, por ejemplo, para comprender el uso personal y los costos.                                                             |\n| **Organización**  | Quieres realizar un seguimiento del uso y los costos de una organización específica, por ejemplo, para la supervisión o reparto de costos a nivel de equipo. |\n| **Empresa**       | Quiere una vista centralizada en varias organizaciones, por ejemplo, para los informes financieros o los informes del centro de costes.                      |\n\nUna vez que haya elegido un nivel de informes, usará el punto de conexión correspondiente en el paso siguiente para recuperar los datos de uso y crear un informe automatizado.\n\n## Paso 2: Recuperar datos de uso de productos de pago\n\nDespués de decidir en qué nivel se va a informar, use la API REST para recuperar los datos de uso de los productos de pago GitHub . Para todos los endpoints, vea [Uso de facturación](/es/rest/billing/usage).\n\nGitHub proporciona dos tipos de datos sobre el uso de facturación:\n\n* **Resúmenes de** uso: datos agregados de uso y costo para todos los productos de pago.\n* ```\n            **              Uso de AI credits**: datos detallados de uso y facturación para AI credits, incluido el consumo del grupo y el gasto de uso adicional.\n  ```\n\nEn la mayoría de los escenarios de informes, empezará con un **resumen de uso** para comprender el uso general y el gasto y, a continuación, usará AI credits los datos de uso cuando necesite información más detallada sobre el Copilot consumo.\n\n### Recuperación de un resumen de uso\n\nUtilice el punto de conexión de resumen de uso que se corresponda con el nivel de informes que eligió en el paso 1.\n\nPor ejemplo, para recuperar un resumen de uso de una empresa, realice una solicitud a:\n\n`/enterprises/{enterprise}/settings/billing/usage/summary`\n\nDebe autenticar la solicitud en este punto de conexión.\n\n**Ejemplo de uso de curl**\n\n```bash\ncurl -L \\\n  -H \"Authorization: Bearer $GITHUB_TOKEN\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  https://api.github.com/enterprises/ENTERPRISE/settings/billing/usage/summary\n```\n\nReemplace `ENTERPRISE` con el slug empresarial y establezca la variable de entorno `GITHUB_TOKEN` a personal access token con los permisos de facturación necesarios.\n\n**Ejemplo de uso de GitHub CLI**\n\n```bash\ngh api \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  /enterprises/ENTERPRISE/settings/billing/usage/summary\n```\n\nEste punto de conexión devuelve datos de uso agregados para todos los productos de pago para el año actual de forma predeterminada. Cada entrada incluye información como el producto, el tipo de unidad, la cantidad utilizada y el importe facturado.\n\nPuede usar el mismo enfoque para recuperar resúmenes de uso para una organización o usuario llamando al punto de conexión equivalente para ese nivel de cuenta.\n\n### Recuperar el uso de AI credits\n\nSi necesita hacer un informe sobre el consumo de Copilot, utilice el punto de conexión de uso de IA para el mismo nivel de cuenta. Este punto de conexión proporciona detalles adicionales, como el uso del grupo incluido, el uso adicional facturado y el consumo por modelo.\n\n## Paso 3: Filtrar los datos de uso por período de tiempo o centro de costos\n\nDe forma predeterminada, los endpoints de resumen de uso devuelven datos para el **año actual**. Para generar informes más específicos o analizar tendencias a lo largo del tiempo, puede filtrar los datos de uso mediante parámetros de consulta.\n\n### Filtrar por período de tiempo\n\nPuede limitar los datos de uso devueltos especificando uno o varios de los parámetros de consulta siguientes:\n\n* `year`\n* `month`\n* `day`\n* `hour`\n\nPor ejemplo, para recuperar los datos de uso de un mes específico, incluya los `year` parámetros y `month` en la solicitud:\n\n```http\nGET /enterprises/{enterprise}/settings/billing/usage/summary?year=2024&month=12\n```\n\nEl filtrado por período de tiempo es útil cuando desea:\n\n* Generación de informes de uso mensual o diario\n* Comparar el uso antes y después de un cambio, como habilitar una nueva característica\n* Conciliar el uso con las facturas para un periodo de facturación específico\n\n### Filtrar por centro de costos (solo empresa)\n\nSi va a recuperar datos de uso de nivel empresarial, también puede filtrar los resultados por centro de costos mediante el `cost_center_id` parámetro de consulta.\n\nEl filtrado por centro de costos le permite:\n\n* Atribuir el uso y los costos a equipos o unidades de negocio específicas\n* Generación de informes específicos del centro de costos para las partes interesadas de finanzas o liderazgo\n\nEl filtrado por centro de costes solo está disponible para los puntos de conexión de resumen de uso empresarial.\n\nEn el paso siguiente, aprenderá a automatizar estas llamadas API para generar informes de uso periódicos.\n\n## Paso 4: Automatizar informes de uso periódicos\n\nUna vez que haya identificado los datos de uso que desea recopilar y cómo filtrarlos, puede automatizar los informes mediante la ejecución de las mismas solicitudes de API según una programación periódica.\n\nEntre los patrones de automatización comunes se incluyen los siguientes:\n\n* Ejecución de solicitudes de API programadas (por ejemplo, diarias o mensuales) para recopilar datos de uso\n* Almacenar los resultados en un sistema interno, como una base de datos, una hoja de cálculo o una herramienta de BI\n* Uso de los datos para supervisar las tendencias, detectar variaciones en el uso o respaldar revisiones de costos\n\nAl automatizar informes, la coherencia es importante. Use el mismo nivel de informes, filtros y intervalos de tiempo cada vez para que las tendencias de uso sean comparables con el tiempo.\n\nPor ejemplo, es posible que:\n\n* Ejecución de un resumen de uso mensual de nivel empresarial para realizar un seguimiento del gasto total\n* Generación de informes específicos del centro de costes para el contracargo o control de gastos\n* Supervisión del crecimiento del uso después de habilitar nuevas características de pago\n\nEn el paso siguiente, aprenderá a interpretar los campos de uso y costo devueltos por la API para que pueda convertir los datos sin procesar en información significativa.\n\n## Paso 5: Interpretar los campos de uso y costo en la respuesta de la API\n\nLa respuesta de resumen de uso incluye información sobre **el uso** y **el costo** . Comprender cómo se relacionan estos campos entre sí le ayuda a interpretar el gasto, el uso incluido y los usos facturados por encima del límite.\n\nCada elemento de uso incluye:\n\n* **Cantidad**, que representa la cantidad de uso de un producto y un tipo de unidad específicos.\n* **NetAmount**, que representa el costo facturado por ese uso\n* Un **discountAmount**, que representa el uso cubierto por cuotas o descuentos incluidos\n\nEn general:\n\n* Usar **cantidad** para comprender la cantidad de un producto consumido\n* Utilice **netAmount** para comprender lo que fue facturado\n* Uso de **discountAmount** para saber cuánto uso se ha incluido o descontado\n\nPor ejemplo, una cantidad alta con un netAmount bajo puede indicar que la mayoría del uso se ha cubierto por cuotas incluidas, mientras que un aumento de netAmount a lo largo del tiempo puede indicar un aumento del uso pagado.\n\nDiferentes productos notifican el uso mediante diferentes tipos de unidad (como minutos, gigabytes o solicitudes). Para calcular métricas específicas del producto o reproducir valores de la plataforma de facturación anterior, es posible que tenga que filtrar los elementos de uso por tipo de producto y unidad y agregar los resultados. Los ejemplos detallados están disponibles en la documentación de referencia vinculada en el paso siguiente.\n\n## Paso 6: Cálculo de métricas de uso específicas del producto\n\nEn algunos casos, es posible que tenga que calcular las métricas de uso específicas del producto a partir de la respuesta de resumen de uso. Esto es más relevante si desea generar informes personalizados para un producto específico o reproducir valores usados en los informes heredados.\n\nPara calcular estas métricas, normalmente se filtran los elementos de uso por `product` y `unitType`, después se agregan campos como `quantity`, `netAmount`y `discountAmount`.\n\nPara obtener ejemplos detallados y cálculos específicos del producto, consulte [Introducción a la facturación y las licencias](/es/billing/reference/previous-billing-platform-endpoints)."}