Нумерологія в API: 5 систем розрахунку за одним маршрутом

Нумерологія - та частина езотеричного стеку, яку API зазвичай або пропускають повністю, або зводять до однієї піфагорійської «life path number». Ми пішли іншим шляхом: 5 повних систем, кожна з 10 канонічних розрахунків, за одним параметризованим маршрутом.

Разом це 50 ендпоінтів під /numerology/{system}/{calc}, плюс окрема Матриця Долі. Нижче - як це влаштовано і чому одного маршруту достатньо.

Усі розрахунки живуть під шаблоном:

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

{system} - одне з п’яти значень. Кожна система має власну таблицю відповідності «літера → число» і власні правила редукції, тому результат для того самого імені відрізняється залежно від школи:

Невідома система повертає 400 INVALID_SYSTEM з переліком допустимих значень - жодних мовчазних fallback-ів на піфагорійську.

Той самий набір із 10 обчислень доступний для будь-якої з п’яти систем:

• life-path - число життєвого шляху (з дати народження)
• expression - число вираження / доля (з повного імені)
• soul-urge - число душі (голосні імені)
• personality - число особистості (приголосні імені)
• birthday - число дня народження
• maturity - число зрілості (life-path + expression)
• balance - балансове число (ініціали)
• challenge - числа викликів
• pinnacles - числа вершин (життєві періоди)
• personal-year - число персонального року

Тіло запиту для більшості викликів - просто ім’я і дата:

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

personal-year додатково приймає year, бо рахує вібрацію конкретного календарного року.

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"}'

Відповідь містить не тільки число, а й повний ланцюжок редукції та готову інтерпретацію:

{
  "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"
      }
    }
  }
}

Поле steps показує кожен крок редукції (10 → 1), а isMaster вмикається на 11, 22 і 33 - їх не редукують за угодою піфагорійської школи. Це важливо, якщо ти будуєш власний UI: не треба здогадуватись, чому 29 стало 11, а не 2 - ланцюжок віддається явно.

Матриця Долі (Destiny Matrix) - не частина класичної нумерології, тому вона живе на власному маршруті:

POST /v1/destiny-matrix

Це метод на 22 старших арканах Таро, які розкладаються на октаграму з дати народження. Повертає позиції центральної хрести, ліній предків, зон грошей і стосунків - готову структуру для рендерингу матриці. Тримаємо його поза /numerology/*, бо це інша модель (аркани, не редукція цифр).

Нумерологічні розрахунки - чиста арифметика над рядком і датою, без ефемерид. Тому вони детерміновані і дешеві: той самий вхід завжди дає той самий вихід, кешування тривіальне. Інтерпретації (meaning) - статичні таблиці, не LLM, тому в них немає ні галюцинацій, ні варіативності між викликами.

Якщо потрібен вільний текст поверх чисел, це вже окремий шар /interpret/* з AI - але базові числа завжди приходять з детермінованого ядра.

Нумерологія входить до езотеричного add-on пакета разом із Таро, рунами, геомантією та I Ching. Кожен виклик - фіксована кредитна вартість (розрахункові, не AI-ендпоінти, тому дешеві). Безкоштовний тариф - 10 000 кредитів на місяць, чого вистачає, щоб зібрати повний нумерологічний профіль на кількасот користувачів за місяць без оплати.

1. Ключ на dashboard/sign-up
2. Обери систему під свою аудиторію (піфагорійська - дефолт для західного ринку, ведична - для індійського)
3. Збери профіль із 10 викликів або тягни по одному числу під конкретний екран

Повний перелік полів і схем - в OpenAPI-довіднику під групою Numerology.