Numerologia no API: 5 sistemas de cálculo via um único endpoint

Numerologia - é uma parte do stack esotérico que a API geralmente ignora por completo ou reduz a apenas um «número do caminho de vida» pitagórico. Seguimos outro caminho: 5 sistemas completos, cada um com 10 cálculos canónicos, através de um único roteiro parametrizado.

Juntos são 50 endpoints em /numerology/{system}/{calc}, mais a Destiny Matrix à parte. A seguir - como está organizado e por que um único roteiro basta.

Todos os cálculos vivem sob o modelo:

POST /v1/numerology/{system}/{calc}

{system} - um dos cinco valores. Cada sistema tem sua própria tabela de correspondência «letra → número» e suas próprias regras de redução, portanto o resultado para o mesmo nome varia consoante a escola:

Um sistema desconhecido devolve 400 INVALID_SYSTEM com a lista de valores válidos - nenhum fallback silencioso para pitagórico.

O mesmo conjunto de 10 cálculos está disponível para qualquer um dos cinco sistemas:

• `life-path` - número do caminho de vida (a partir da data de nascimento)
• `expression` - número de expressão / destino (a partir do nome completo)
• `soul-urge` - número da alma (vogais do nome)
• `personality` - número da personalidade (consoantes do nome)
• `birthday` - número do dia de nascimento
• `maturity` - número de maturidade (life-path + expression)
• `balance` - número de equilíbrio (iniciais)
• `challenge` - números dos desafios
• `pinnacles` - números dos pináculos (períodos de vida)
• `personal-year` - número do ano pessoal

O corpo do pedido para a maioria dos chamados - simplesmente nome e data:

{ "name": "Ada Lovelace", "date": "1815-12-10" }

personal-year aceita adicionalmente o parâmetro year, pois calcula a vibração do ano calendário específico.

curl -X POST https://api.astroway.info/v1/numerology/pythagorean/life-path \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace","date":"1815-12-10"}'

A resposta contém não apenas o número, mas também a cadeia completa de redução e uma interpretação pronta:

{
  "ok": true,
  "data": {
    "system": "pythagorean",
    "name": "Ada Lovelace",
    "date": "1815-12-10",
    "lifePath": {
      "raw": 10,
      "reduced": 1,
      "isMaster": false,
      "steps": [10, 1],
      "meaning": {
        "number": 1,
        "archetype": "The Pioneer",
        "strengths": ["leadership", "independence", "innovation", "initiative"],
        "challenges": ["ego", "impatience", "isolation", "stubbornness"],
        "career": ["entrepreneur", "executive", "inventor", "pioneer"],
        "relationship": "needs a partner who respects independence; thrives on mutual challenge",
        "shortRead": "born to lead and originate; learn to balance solo drive with collaboration"
      }
    }
  }
}

O campo steps mostra cada passo da redução (10 → 1), e isMaster é ativado para 11, 22 e 33 - eles não são reduzidos segundo o acordo da escola pitagórica. Isto é importante se estiveres a construir o teu UI: não precisas de adivinhar por que 29 se tornou 11 e não 2 - a cadeia é dada explicitamente.

A Matriz do Destino (Destiny Matrix) - não é parte da numerologia clássica, portanto vive no seu próprio roteiro:

POST /v1/destiny-matrix

É um método baseado nos 22 arcanos maiores do Tarô, que se dispõem em um octagrama a partir da data de nascimento. Devolve as posições da cruz central, linhas ancestrais, zonas de dinheiro e relacionamentos - uma estrutura pronta para renderizar a matriz. Mantemo-lo fora de /numerology/* porque é outro modelo (arcanos, não redução de dígitos).

Os cálculos de numerologia são pura aritmética sobre uma string e uma data, sem efemérides. Por isso são determinísticos e baratos: a mesma entrada sempre produz a mesma saída, e o caching é trivial. As interpretações (meaning) são tabelas estáticas, não LLM, portanto nelas não há alucinações nem variabilidade entre chamadas.

Se precisares de texto livre por cima dos números, isso já é uma camada separada /interpret/* com IA - mas os números básicos vêm sempre do núcleo determinístico.

A numerologia faz parte do pacote complementar esotérico juntamente com Tarô, runas, geomancia e I Ching. Cada chamada tem um custo fixo em créditos (são endpoints de cálculo, não de IA, portanto baratos). O plano gratuito oferece 10 000 créditos por mês, o que basta para obter um perfil numerológico completo de algumas centenas de utilizadores por mês sem pagar.

1. Chave em dashboard/sign-up
2. Escolhe o sistema de acordo com o teu público (pitagórico - padrão para o mercado ocidental, védico - para o indiano)
3. Recolhe um perfil com 10 chamadas ou puxa um número de cada vez para um ecrã específico

A lista completa de campos e esquemas está em documentação OpenAPI no grupo Numerology.