Chaves de API — tnea_ & tnsr_¶

O NumerologyAPI usa duas famílias de chaves de API. Ambas têm aparência semelhante, são geradas com o mesmo formato seguro de 80 caracteres e autenticam com o mesmo cabeçalho X-API-Key — mas são medidas de forma diferente e destinam-se a produtos diferentes.

1. Formato e Segurança da Chave¶

Toda chave tem exatamente 80 caracteres:

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• O prefixo de 4 caracteres identifica o tipo de chave; os 75 caracteres restantes são gerados com uma fonte aleatória criptograficamente segura.
• As chaves são armazenadas com hash SHA-256 no servidor. A chave em texto puro é exibida apenas uma vez, no momento da criação.
• Se uma chave for exposta, rotacione-a imediatamente no dashboard.

2. Chaves de Plataforma (tnea_)¶

As chaves de plataforma são as chaves padrão para integrar o NumerologyAPI ao seu próprio produto — sites, aplicativos móveis e serviços no servidor.

Autenticação¶

Envie a chave em cada requisição com o cabeçalho X-API-Key:

curl --request GET \
  --url "https://api.numerologyapi.com/api/v1/life_path?birth_year=1990&birth_month=5&birth_day=15" \
  --header "x-api-key: tnea_YOUR_API_KEY"

Medição¶

As chamadas faturáveis /api/v1 são deduzidas da carteira de créditos da sua organização (pay-as-you-go). Você pode recarregar a carteira a qualquer momento pelo dashboard.

Regra de canal: as chaves de plataforma não devem enviar o cabeçalho X-Numora-Client. Enviá-lo retorna 403 — esse cabeçalho é reservado para o canal desktop.

3. Chaves do Numora Studio (tnsr_)¶

As chaves do Numora Studio autenticam o aplicativo de desktop Numora Studio (macOS/Windows) usado por profissionais para gerar relatórios de clientes. Elas são irmãs das chaves de plataforma, com formato idêntico, mas são cobradas contra a cota do plano Numora Studio da organização em vez dos créditos de plataforma.

Provisionamento¶

Uma chave tnsr_ é criada de duas formas:

• pelo fluxo de login do aplicativo desktop (a página de consentimento do navegador provisiona uma chave automaticamente), ou
• manualmente na página API Keys do dashboard (/api-keys).

Assinatura de canal (obrigatória)¶

Toda chamada feita com uma chave tnsr_ deve incluir o cabeçalho de canal desktop:

Aplicação no servidor:

• chave tnsr_ sem X-Numora-Client → 403.
• chave tnea_ com X-Numora-Client → 403.

Medição¶

• Chamadas faturáveis /api/v1 deduzem da cota do plano Numora Studio da organização (um único pool compartilhado entre todas as chaves tnsr_ da organização).
• Existe uma opção de fallback de créditos por chave tnsr_: quando a cota do plano é esgotada, a chave pode cair no fallback para os créditos de plataforma da organização (desativada por padrão).
• Se a cota for esgotada e nenhum fallback estiver habilitado, as chamadas retornam 429.

Bloqueio de dispositivo (opcional)¶

Uma chave tnsr_ pode ser bloqueada para dispositivos registrados. Com o bloqueio habilitado, toda requisição deve carregar um X-Numora-Device-Id registrado na organização; dispositivos não registrados são rejeitados com 403.

Endpoints exclusivos do desktop¶

Alguns endpoints são reservados para o canal desktop e retornam 403 para chaves tnea_:

• POST /api/v1/numora/report-bundle — relatório completo do cliente em uma única chamada
• POST /api/v1/numora/order — fluxo de compra de plano/cota no aplicativo
• POST /api/v1/numora/devices/register — registrar uma instalação do desktop
• GET /api/v1/numora/studio-status — saldos do desktop e medidores de cota

Dica: as respostas faturáveis também carregam os cabeçalhos X-Remaining-Credits e X-Remaining-Tokens para que você acompanhe os saldos em tempo real sem chamadas extras.

4. Gerenciando Chaves (Dashboard)¶

A página API Keys do dashboard (/api-keys) é o centro de controle para ambos os tipos de chave.

Funções: as funções admin e developer podem criar e gerenciar chaves. finance não pode criar chaves de API de produção. As operações financeiras (compras de planos, recargas) são limitadas a admin e finance.

Múltiplas chaves: as organizações podem ter várias chaves de ambos os tipos — por exemplo, uma chave tnsr_ por profissional ou por instalação desktop. As cotas são compartilhadas por organização, então as chaves nunca "competem" pelo próprio saldo.

5. Boas Práticas¶

• Trate as chaves como senhas. Nunca as incorpore em código do lado do cliente, repositórios públicos ou logs.
• Use variáveis de ambiente ou um gerenciador de segredos no seu backend.
• Rotacione imediatamente se uma chave for comprometida ou se um membro da equipe sair.
• Use uma chave tnsr_ por instalação desktop para simplificar o gerenciamento de dispositivos e a revogação.
• Habilite o bloqueio de dispositivo para organizações de alta segurança.
• Monitore o uso no dashboard para detectar picos inesperados cedo.

6. Perguntas Frequentes¶

Uma chave tnsr_ pode chamar endpoints de plataforma regulares? Sim. As chaves do Numora Studio autenticam toda a superfície /api/v1; essas chamadas são cobradas contra a cota do plano Numora Studio.

Uma chave tnea_ pode chamar os endpoints /numora/* exclusivos do desktop? Não. Os endpoints exclusivos do desktop retornam 403 para chaves de plataforma.

Por que recebo 403 ao chamar com minha chave tnsr_? Provavelmente o cabeçalho X-Numora-Client está ausente ou o id do aplicativo não corresponde. Verifique se toda requisição inclui X-Numora-Client: numora-studio/<version>.

Por que recebo 403 com minha chave tnea_? As chaves de plataforma não devem carregar o cabeçalho X-Numora-Client — remova-o.

O que acontece quando minha cota se esgota? As chamadas faturáveis retornam 429, a menos que o fallback de créditos esteja habilitado na sua chave tnsr_ (ou que você recarregue a carteira de plataforma para chaves tnea_).

Relacionados¶

• Primeiros Passos
• Preços
• Soluções Empresariais