Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Informações de Faturação

Aula 5 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Gerir a faturação via API
  2. Recuperar informações de faturação
  3. Atualizar informações
  4. Recuperar faturas
  5. Lógica de faturação da xAI
  6. Visualizar cobranças atuais
  7. Pontos-chave

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.

GET
Recuperar
POST
Atualizar
4
Estados da fatura
Mensal
Ciclo de faturação

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 GET e POST em /v1/billing/teams/{teamId}/billing-info para 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