Crie um portal de revendedores de API de IA: provisionamento de locatários, medição de uso, cobrança e operações de telegrama
Uma arquitetura de referência prática para agências, consultores e construtores de SaaS que empacotam acesso à API de IA para clientes: registros de locatários, chaves com escopo de cliente, limites de gastos, livros de uso, sincronização de faturamento e operações de Telegram.
Se você empacotar o acesso de IA para clientes, não entregue a eles as chaves do provedor upstream. Crie uma camada de revendedor que emita chaves no escopo do cliente, imponha limites de locatários antes de cada solicitação, registre o uso em seu próprio livro-razão e sincronize os totais faturáveis com seu sistema de faturamento.
Este guia descreve um modelo operacional prático para uma API de IA para agências, consultores e criadores de SaaS. Não é um estudo de caso de cliente. É uma arquitetura de referência que você pode adaptar se usar uma API de parceiro, um gateway interno ou um proxy personalizado na frente de vários provedores de modelos.
A arquitetura do portal do revendedor
Um portal de revendedor seguro separa quatro responsabilidades:
- Administração de parceiros: seu aplicativo interno para criar clientes, planos, chaves, limites e fluxos de trabalho de suporte.
- Aplicação de solicitação: o caminho do gateway que autentica chaves de clientes, verifica políticas, roteia solicitações e bloqueia tráfego acima do limite.
- Contabilidade de uso: um livro-razão durável que registra o uso em nível de solicitação e informações de preços.
- Faturamento e operações: sincronização programada de faturas, alertas, avisos de rotação de chaves e escalonamento de suporte.
Um fluxo típico é assim:
Aplicativo de administração de parceiros
→ API de parceiro
→ registros de cliente/espaço de trabalho
→ chaves de API com escopo do cliente
→ plano, modelo, orçamento e limites de taxas
→ solicitar gateway
→ razão de uso
→ sincronização de faturamento
→ Bot de notificação de telegramaFato: a OpenAI recomenda não compartilhar chaves de API baseadas no usuário para colaboração e, em vez disso, usar chaves baseadas em projetos, membros atribuídos e chaves distintas com limites de taxas isolados e controles de gastos. Os termos de serviço da OpenAI também proíbem a compra, venda ou transferência de chaves de API de ou para terceiros. Esses fatos apoiam um design de revendedor onde as credenciais upstream permanecem no servidor e os clientes recebem suas próprias chaves downstream.
Recomendação: emita uma chave downstream por cliente, projeto ou ambiente. Não reutilize uma chave de cliente em vários clientes finais. Não exponha as credenciais do provedor upstream em documentação, código do navegador, aplicativos móveis, registros ou mensagens de suporte ao cliente.
Modelo de dados do locatário
O modelo de locatário deve tornar o isolamento explícito. No mínimo, armazene estes campos:
partner_id
ID_do_cliente
espaço de trabalho_id
api_key_id
id_plano
status_de faturamento
limite_de_gastos
taxa_limite
modelos_permitidos
telegram_chat_id
uso_ledger_id
criado_em
atualizado_em
revogado_atEm um portal maior, adicione campos para saldo pré-pago, moeda, região fiscal, ID do cliente da fatura, nível de suporte, status de abuso e substituições temporárias.
Exemplo de registro de cliente
Recomendação: trate customer_id, workspace_id e api_key_id como conceitos separados. Um cliente pode ter vários espaços de trabalho e cada espaço de trabalho pode precisar de chaves separadas de produção, preparo e desenvolvimento. Isso torna a revogação, a depuração e a atribuição de uso muito mais fáceis.
Sequência de integração para um novo cliente
Um fluxo de integração confiável é enfadonho por natureza. Deve produzir sempre os mesmos registros e deixar uma trilha de auditoria.
- Crie o cliente: armazene o nome legal, o contato de cobrança, o contato técnico e o proprietário interno.
- Crie um espaço de trabalho: separe a produção dos testes se o cliente integrar programaticamente.
- Atribuir um plano: defina modelos incluídos, marcação, cadência de faturamento e expectativas de suporte.
- Definir limites: configure limites de gastos, limites de solicitação, limites de token e política de burst.
- Crie chaves de API: emita chaves com escopo para os ambientes do cliente.
- Enviar instruções de integração: forneça URL base, formato de autenticação, lista de modelos, limites e canal de suporte.
- Ativar alertas: conecte o Telegram ou outro canal de operações para avisos de saldo baixo, chave, interrupção e cobrança.
- Execute uma solicitação de teste: verifique a autenticação, o registro de uso, o acesso ao modelo e o mapeamento da fatura.
Recomendação: torne a integração idempotente. Se seu aplicativo de administração tentar novamente uma operação de “criar cliente”, ele não deverá criar registros de faturamento duplicados ou chaves de API duplicadas. Use IDs externos e chaves de idempotência para chamadas de provisionamento.
Controle de orçamento no momento da solicitação
A aplicação mais importante acontece antes que a solicitação chegue a um modelo upstream. Seu gateway não deve descobrir que um cliente ultrapassou o orçamento somente depois que o provedor já tiver cobrado de você.
Use esta sequência de simulação:
- Autenticar a chave de API downstream.
- Resolver
partner_id,customer_ideworkspace_id. - Verifique se a chave está ativa e não revogada.
- Verifique o status do faturamento: ativo, em teste, pré-pago, pausado, vencido ou suspenso.
- Verifique o limite máximo de gastos para o período de faturamento atual.
- Verifique os limites de taxas, como solicitações por minuto e tokens por dia.
- Verifique se o modelo solicitado é permitido para o plano do cliente.
- Estime o custo máximo possível a partir do modelo, do máximo de tokens e dos parâmetros de solicitação.
- Encaminhe a solicitação somente se a política for aprovada.
se key.revoked:
rejeitar(401, "Chave de API revogada")
se customer.billing_status em ["pausado", "suspenso", "atrasado"]:
rejeitar(402, "Status de cobrança não permite uso")
se request_model não estiver em customer.allowed_models:
rejeitar(403, "Modelo não habilitado para este espaço de trabalho")
se gasto_período_atual + custo_máx_estimado > cliente.hard_cap:
rejeitar(402, "Limite de gastos excedido")
se taxa_limit_exceeded(customer_id, modelo_requisitado):
rejeitar(429, "Limite de taxa excedido")
route_request()Fato: OWASP API Security Top 10 2023 destaca a autorização de objetos quebrada, a autenticação quebrada e o consumo irrestrito de recursos como os principais riscos da API. Eles são mapeados diretamente para portais de revendedores: um locatário não deve ler os dados de outro locatário, as chaves não devem ser ignoráveis e um cliente não deve ser capaz de criar gastos ilimitados com o provedor.
Compensação: limites rígidos estritos protegem sua margem, mas podem interromper picos legítimos. Um bom compromisso é um fluxo de trabalho de substituição temporária com prazo de validade, aprovador, motivo e entrada de registro de auditoria.
Registro de uso como fonte da verdade
Para controle de acesso em tempo real, mantenha seu próprio registro de uso. As ferramentas de faturamento externo são excelentes para faturamento, mas geralmente não são o lugar certo para tomar decisões de permissão ou negação em nível de milissegundos.
Um evento de uso deve capturar detalhes suficientes para reconciliar faturas de fornecedores, explicar faturas de clientes e depurar disputas:
Registre também as solicitações com falha, mas diferencie as falhas que são faturáveis das que não o são. Tempos limite do provedor, falhas de validação, cancelamentos de clientes, novas tentativas e bloqueios de segurança podem ter resultados contábeis diferentes dependendo de quando ocorrem.
Recomendação: escreva um evento contábil pendente quando a solicitação for aceita e finalize-o quando o uso e o custo do token forem conhecidos. Isso permite que você reserve o orçamento antes do encaminhamento e corrija o valor final após a conclusão.
Padrão de reconciliação
- Armazene eventos em nível de solicitação no razão interno.
- Uso agregado por cliente, modelo e período de faturamento.
- Compare os totais internos com as faturas do fornecedor upstream ou com as exportações de uso.
- Investigar diferenças materiais antes de emitir faturas.
- Sincronize o uso faturável resumido com o sistema de faturamento.
Compensação: a sincronização do uso resumido reduz o volume e a complexidade dos eventos de faturamento, mas pode tornar as faturas dos clientes menos detalhadas. Se os clientes precisarem de relatórios em nível de modelo ou de projeto, preserve essas dimensões na sincronização de faturamento ou no painel do cliente.
Sincronização de faturamento com medidores baseados em uso
Os sistemas de faturamento baseados em uso geralmente seguem um padrão: definem produtos e preços, ingere eventos de uso, agrega-os ao longo de um período de faturamento, gera faturas e monitora erros. O Stripe Billing, por exemplo, oferece suporte a eventos de medidor com nome de evento, identificador de cliente, valor numérico, carimbo de data/hora opcional, identificador de idempotência opcional e dimensões opcionais.
Para faturamento da API AI, as opções comuns de medidor são:
- Total de tokens: útil quando o preço está intimamente ligado aos tokens de entrada e saída.
- Contagem de solicitações: útil para planos simples ou chamadas de API com baixo token.
- Unidades específicas do modelo: úteis quando os modelos premium têm margens diferentes.
- Assentos ou espaços de trabalho ativos: úteis para planos híbridos de SaaS mais uso.
Fato: os medidores de distribuição suportam fórmulas de agregação como soma, contagem e último. Eles são mapeados para totais de tokens, contagens de solicitações e valores semelhantes a estados, como licenças ou limites ativos.
Uma sincronização de faturamento diária pode criar eventos de medidor como este:
Recomendação: mantenha o razão interno mais granular do que a fatura. Você pode faturar totais diários de tokens e ainda manter registros em nível de solicitação para suporte, análise de fraudes, ajuste de limite de taxa e análise de margem.
Operações do Telegram sem fazer do Telegram o sistema de registro
O Telegram é útil para fluxos de trabalho rápidos de operadores: as equipes de suporte já percebem mensagens, os bots podem enviar alertas e os clientes podem receber instruções de integração sem fazer login em um painel. Mas o Telegram não deve ser a única trilha de auditoria para decisões de faturamento, segurança ou suporte.
Bons fluxos de trabalho do Telegram incluem:
- Alertas de saldo baixo ou gasto alto em 50%, 80% e 95% do limite.
- Mensagens de integração de novos clientes com links de documentação e nomes de chaves mascarados.
- Avisos de rotação de chaves de API antes e depois da rotação.
- Alertas de interrupção do provedor ou modelo degradado.
- Escalonamento de suporte humano quando um cliente encontra erros 401, 402, 403 ou 429 repetidos.
Fato: as chamadas da API do Bot do Telegram são feitas por HTTPS para endpoints de token de bot, e os webhooks do Telegram podem incluir um cabeçalho de token secreto para ajudar a verificar a origem do webhook.
Recomendação: armazene os IDs de bate-papo do Telegram como metadados de locatário, mas não os exponha aos clientes. Registre todas as ações administrativas acionadas por bot em seu registro de auditoria interna com ator, carimbo de data/hora, cliente, valor antigo, novo valor e motivo.
Lista de verificação de segurança e isolamento
Antes de vender o acesso, teste o isolamento do locatário como se um cliente estivesse ativamente tentando cruzar fronteiras.
- O cliente A não pode visualizar as chaves de API do cliente B.
- O Cliente A não pode visualizar o uso, as faturas, os limites, os IDs de bate-papo do Telegram ou o status de cobrança do Cliente B.
- Uma chave revogada falha imediatamente em todos os caminhos de solicitação.
- Um cliente com faturamento pausado não pode continuar gastando por meio de sessões em cache ou chaves antigas.
- Um cliente não pode solicitar modelos fora do plano atribuído.
- Os limites de tarifas se aplicam por cliente e espaço de trabalho, não apenas por endereço IP global.
- Os manipuladores de Webhook verificam assinaturas ou cabeçalhos secretos quando suportados.
- Todos os provisionamentos, alterações de limites, rotações de chaves e substituições de faturamento criam entradas de registro de auditoria.
- A lógica de nova tentativa usa chaves de idempotência para que solicitações duplicadas não faturem duplicadamente os clientes.
- As ferramentas de suporte mascaram segredos e restringem quem pode revelar ou alternar chaves.
Previsão: os portais de revendedores competirão cada vez mais em governança e clareza de faturamento, não apenas no acesso a muitos modelos. Os clientes esperam uso por projeto, faturas claras, rotação rápida de chaves e controles rígidos de gastos como recursos padrão.
Principais compensações a serem decididas antecipadamente
Pré-pago versus pós-pago
Os saldos pré-pagos reduzem o risco de crédito e simplificam os cortes, mas os clientes podem não gostar de interrupções. O faturamento pós-pago é mais tranquilo para clientes estabelecidos, mas requer verificações de crédito, fluxos de trabalho de cobrança e detecção de anomalias mais forte.
Um preço combinado versus preço específico do modelo
Um preço combinado é mais fácil de explicar. O preço específico do modelo protege as margens e incentiva a seleção eficiente do modelo. Se você oferece muitos modelos, publique um catálogo de modelos simples voltado para o cliente e oculte a complexidade desnecessária específica do fornecedor.
Medição em tempo real versus cobrança atrasada
A medição em tempo real permite limites de gastos e saldos pré-pagos. Também requer gravações duráveis, manipulação de reprodução e reconciliação. O faturamento atrasado é mais simples, mas expõe você a gastos excessivos antes que os limites entrem em vigor.
Suporte que prioriza o Telegram versus suporte que prioriza o painel
O Telegram é rápido e familiar para muitas operadoras. Um painel é melhor para auditabilidade, exportações, permissões e autoatendimento do cliente. Use o Telegram para notificações e aprovações, mas armazene o registro canônico em seu sistema.
Plano de implementação prático
- Comece com o isolamento do locatário: implemente registros de cliente, espaço de trabalho, chave, plano e limite antes de adicionar recursos avançados de faturamento.
- Crie uma aplicação de comprovação: bloqueie chaves revogadas, faturamento suspenso, modelos não permitidos e limite excessivo de tráfego antes do roteamento.
- Crie o registro de uso: registre IDs de solicitação, contagens de tokens, custos, preços de revendedor, status, carimbos de data/hora e chaves de idempotência.
- Adicionar reconciliação: compare o uso interno com os totais do fornecedor upstream antes do faturamento.
- Sincronize resumos de faturamento: envie agregados diários ou por hora para sua plataforma de faturamento com mapeamentos de clientes estáveis e chaves de idempotência.
- Alertas de Wire Telegram: comece com mensagens de baixo equilíbrio, interrupção, rotação de chaves e escalonamento de suporte.
- Execute testes de isolamento: verifique se nenhum cliente pode acessar chaves, uso, limites, faturas ou metadados de bate-papo de outro cliente.
Um portal de revendedor não é apenas um wrapper de uma API de IA. É uma camada operacional para autenticação, política de locatário, análise de uso, cobrança e suporte. Crie o razão e os limites primeiro, mantenha as chaves upstream no lado do servidor e torne cada chave voltada ao cliente revogável, com escopo definido e atribuível.