Informações de Faturação
Nesta página
Gerir a faturação via API
A secção de Faturação da API de Gestão permite-lhe recuperar e atualizar as suas informações de faturação, obter faturas e monitorizar despesas — tudo de forma programática. Acabaram-se as idas e voltas à consola para verificar o estado dos pagamentos.
Recuperar informações de faturação
Os detalhes de faturação parecem inofensivos até que a contabilidade rejeite uma fatura devido a um nome incorreto ou à falta de número de IVA. Verificá-los via API requer apenas um pedido e previne um erro irreparável: como explica a nota abaixo, não é possível regenerar uma fatura já emitida com novos detalhes.
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/billing-info" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
A resposta contém os detalhes de faturação registados: nome da empresa, morada, país e número de IVA, se aplicável.
Atualizar informações
Para modificar as suas informações de faturação:
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": "My Company SAS",
"address": "15 Peace Street",
"city": "Paris",
"country": "FR",
"vatNumber": "FR12345678901"
}'
Nota importante sobre faturas existentes
As informações de faturação atualizadas aplicam-se apenas a faturas futuras. Não é possível regenerar retroativamente uma fatura com novos detalhes. Verifique as suas informações antes do fim do ciclo de faturação para garantir faturas corretas.
Recuperar faturas
O endpoint GET /v1/billing/teams/{teamId}/invoices devolve o seu histórico de faturas:
# Faturas de um mês 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"
# Faturas desde um determinado mês
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 filtragem
- billingCycle.year e billingCycle.month: recupera faturas de um ciclo específico
- since.year e since.month: recupera todas as faturas desde um determinado mês
Estados da fatura
Destes quatro estados, apenas um exige ação imediata. FAILED significa que a cobrança não foi processada — cartão expirado, limite atingido, litígio — e uma fatura por pagar acaba por levar à suspensão do serviço. Este é o estado que deve monitorizar automaticamente, como mostrado na lição sobre métodos de pagamento; revê os outros três, mas gera alertas apenas para este.
- PENDING: a fatura está a ser processada; o pagamento ainda não foi cobrado
- PAID: o pagamento foi bem-sucedido
- FAILED: a cobrança falhou (cartão expirado, fundos insuficientes, etc.)
- WILL_NEVER_BE_CHARGED: a fatura nunca será cobrada (crédito, ajuste)
Lógica de faturação da xAI
Compreender como os dois modos interagem evita interpretações erradas do seu painel. Os créditos pré-pagos são utilizados em primeiro lugar; a faturação mensal só entra em ação quando o saldo se esgota. Um saldo zero com serviço ativo não é uma anomalia: significa que está agora a consumir em regime pós-pago e que a fatura de fim de mês está a acumular valores.
Créditos pré-pagos
Os créditos comprados são cobrados imediatamente no momento da compra. Cada chamada à API consome créditos com base no número de tokens processados. Os créditos são utilizados prioritariamente.
Faturação mensal (pós-paga)
Se os seus créditos se esgotarem ou se não tiver nenhuns, o consumo é faturado no final do mês. O custo de cada chamada à API é calculado imediatamente, mas a cobrança ocorre no final do ciclo.
Diferenças na contagem de tokens
Espere uma discrepância entre a sua contagem local e a contagem de faturação, e é melhor saber isto antes de perder meio dia a tentar descobrir a causa. A faturação é a fonte de verdade: baseie as suas estimativas de custo nos dados da API de analítica, nunca numa contagem realizada com um tokenizador do lado do cliente. Isto é normal: os endpoints de inferência adicionam tokens internos para processamento (instruções do sistema, formatação), o que aumenta ligeiramente a contagem faturada em comparação com o texto bruto.
Visualizar cobranças atuais
Para visualizar as cobranças acumuladas antes do fim do ciclo:
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Esta pré-visualização é a única forma de conhecer o valor atual antes da emissão da fatura. Verificada uma vez por semana, transforma a faturação mensal numa tarefa gerível: deteta desvios de custos a meio do mês, quando ainda há tempo para redirecionar o tráfego para um modelo mais barato ou reduzir um limite.
Pontos-chave
- Utilize
GETePOSTem/v1/billing/teams/{teamId}/billing-infopara recuperar e modificar informações - As faturas têm 4 estados: PENDING, PAID, FAILED, WILL_NEVER_BE_CHARGED
- As alterações de faturação não são retroativas em faturas existentes
- A xAI combina créditos pré-pagos (prioritários) e faturação mensal
- A pré-visualização de cobranças (
invoice/preview) permite antecipar custos