Información de facturación
En esta página
Gestión de la facturación mediante la API
La sección de Facturación de la Management API te permite recuperar y actualizar tu información de facturación, obtener facturas y supervisar el gasto, todo de forma programática. Olvídate de ir y venir a la consola para comprobar el estado de los pagos.
Recuperación de la información de facturación
Los detalles de facturación pueden parecer inofensivos hasta que contabilidad rechaza una factura por un nombre incorrecto o la falta del número de IVA. Verificarlos mediante la API requiere una sola solicitud y evita un error irreparable: como explica la nota siguiente, no es posible regenerar una factura ya emitida con nuevos datos.
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/billing-info" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
La respuesta contiene los detalles de facturación registrados: nombre de la empresa, dirección, país y número de IVA, si procede.
Actualización de la información
Para modificar tu información de facturación:
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/billing-info" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"companyName": "Mi Empresa SAS",
"address": "Calle de la Paz, 15",
"city": "París",
"country": "FR",
"vatNumber": "FR12345678901"
}'
Nota importante sobre las facturas existentes
La información de facturación actualizada solo se aplica a las facturas futuras. No puedes regenerar retroactivamente una factura con nuevos detalles. Verifica tu información antes de que finalice el ciclo de facturación para garantizar la precisión de las facturas.
Recuperación de facturas
El endpoint GET /v1/billing/teams/{teamId}/invoices devuelve tu historial de facturas:
# Facturas de un mes específico
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/invoices?billingCycle.year=2026&billingCycle.month=3" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
# Facturas desde un mes determinado
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/invoices?since.year=2026&since.month=1" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Parámetros de filtrado
- billingCycle.year y billingCycle.month: recupera facturas de un ciclo específico.
- since.year y since.month: recupera todas las facturas desde un mes determinado.
Estados de la factura
De estos cuatro estados, solo uno requiere acción inmediata. FAILED significa que el cargo no se ha realizado (tarjeta caducada, límite alcanzado, disputa) y una factura impagada acaba conduciendo a la suspensión del servicio. Este es el estado que debes supervisar automáticamente, como se muestra en la lección sobre métodos de pago; revisas los otros tres, pero configuras alertas para este.
- PENDING: la factura está siendo procesada; el pago aún no se ha cargado.
- PAID: el pago se ha realizado correctamente.
- FAILED: el cargo ha fallado (tarjeta caducada, fondos insuficientes, etc.).
- WILL_NEVER_BE_CHARGED: la factura nunca se cargará (crédito, ajuste).
Lógica de facturación de xAI
Entender cómo interactúan los dos modos evita interpretaciones erróneas en tu panel de control. Los créditos prepago se utilizan en primer lugar; la facturación mensual solo entra en juego una vez agotado el saldo. Un saldo cero con servicio activo no es una anomalía: significa que ahora estás consumiendo a posteriori (postpaid) y la factura de fin de mes se está acumulando.
Créditos prepago
Los créditos comprados se cargan inmediatamente en el momento de la compra. Cada llamada a la API consume créditos en función del número de tokens procesados. Los créditos se utilizan en primer lugar.
Facturación mensual (posterior al consumo)
Si tus créditos se han agotado o no tienes ninguno, el consumo se factura a final de mes. El coste de cada llamada a la API se calcula inmediatamente, pero el cargo se realiza al final del ciclo.
Diferencias en el recuento de tokens
Es normal esperar una discrepancia entre tu recuento local y el de facturación; es mejor saberlo antes de perder medio día intentando rastrearla. La facturación es la fuente de autoridad: basa tus estimaciones de costes en las cifras de la analytics API, nunca en un recuento realizado con un tokenizador del lado del cliente. Esto es normal: los endpoints de inferencia añaden tokens internos para el procesamiento (instrucciones del sistema, formato), lo que aumenta ligeramente el recuento facturado en comparación con el texto sin procesar.
Visualización de los cargos actuales
Para ver los cargos acumulados antes de que finalice el ciclo:
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Esta vista previa es la única forma de conocer el importe actual antes de que se emita la factura. Si la consultas una vez a la semana, convertirás la facturación mensual en algo manejable: verás la desviación de costes a mitad de mes, cuando aún hay tiempo para redirigir el tráfico a un modelo más barato o reducir un límite.
Puntos clave
- Utiliza
GETyPOSTen/v1/billing/teams/{teamId}/billing-infopara recuperar y modificar la información. - Las facturas tienen 4 estados: PENDING, PAID, FAILED, WILL_NEVER_BE_CHARGED.
- Los cambios de facturación no son retroactivos en las facturas existentes.
- xAI combina créditos prepago (prioritarios) y facturación mensual.
- La vista previa de cargos (
invoice/preview) te permite anticipar los costes.