API — публичный интерфейс калькулятора НДФЛ

Здесь собрана документация по открытому API сервиса для расчёта НДФЛ по прогрессивной шкале. Данные не сохраняются, вычисления выполняются в реальном времени.

Текущая версия API v1

Все эндпоинты доступны по префиксу /api/v1/

Формат денежных значений

Все денежные значения в API передаются и возвращаются в копейках.

Это означает, что:

10000 = 100 рублей
8000056 = 80 000 рублей 56 копеек
Дробные значения и числа с плавающей точкой (float) не поддерживаются

Такой формат используется для точных финансовых расчётов и исключения ошибок округления.

📡 Public API

Публичные методы доступны без аутентификации. Подходят для клиентских приложений и простых интеграций.

POST /api/v1/calc

Открытый расчёт НДФЛ

Запрос:

{"gross_salary": 12000000}

Пример ответа:

{
  "annual_gross_income": 144000000,
  "annual_net_income": 125280000,
  "annual_tax_amount": 18720000,
  "gross_salary": 12000000,
  "monthly_details": [
    {
      "month": "2025-01-01T00:00:00Z",
      "monthly_gross_income": 12000000,
      "monthly_net_income": 10440000,
      "monthly_tax_amount": 1560000
    },
    {
      "month": "2025-02-01T00:00:00Z",
      "monthly_gross_income": 12000000,
      "monthly_net_income": 10440000,
      "monthly_tax_amount": 1560000
    },
    "... 10 more months ..."
  ],
  "northern_coefficient": 100,
  "territorial_multiplier": 100
}

🔐 Private API

Private API использует расширенный расчёт и требует заголовка x-api-key. Эти методы предназначены для серверов, скриптов, интеграций и внутренних инструментов.

POST /api/v1/private-calc Требуется авторизация

Закрытый расчёт НДФЛ (требуется x-api-key)

Заголовок авторизации:

x-api-key: <ваш_private_api_key>

Запрос:

{
  "gross_salary": 12000000,
  "territorial_multiplier": 120,
  "northern_coefficient": 150,
  "start_date": "2025-01-01",
  "has_tax_privilege": false
}

Пример ответа:

{
  "annualFOMS": 13219200,
  "annualFSS": 7516800,
  "annualPFR": 57024000,
  "annual_gross_income": 259200000,
  "annual_net_income": 225480000,
  "annual_tax_amount": 33720000,
  "gross_salary": 12000000,
  "monthly_details": [
    {
      "month": "2025-01-01T00:00:00Z",
      "monthlyFOMS": 1101600,
      "monthlyFSS": 626400,
      "monthlyPFR": 4752000,
      "monthly_base_gross_income": 14400000,
      "monthly_base_tax_amount": 1870000,
      "monthly_gross_income": 21600000,
      "monthly_net_income": 18790000,
      "monthly_north_gross_income": 7200000,
      "monthly_north_tax_amount": 940000,
      "monthly_tax_amount": 2810000,
      "tax_rate": 13
    },
    {
      "month": "2025-02-01T00:00:00Z",
      "monthlyFOMS": 1101600,
      "monthlyFSS": 626400,
      "monthlyPFR": 4752000,
      "monthly_base_gross_income": 14400000,
      "monthly_base_tax_amount": 1870000,
      "monthly_gross_income": 21600000,
      "monthly_net_income": 18790000,
      "monthly_north_gross_income": 7200000,
      "monthly_north_tax_amount": 940000,
      "monthly_tax_amount": 2810000,
      "tax_rate": 13
    },
    "... 10 more months ..."
  ],
  "northern_coefficient": 150,
  "territorial_multiplier": 120
}

🚀 Примеры вызова API

Примеры кода для различных языков программирования и инструментов.

curl (Public API)

curl -X POST https://calculator-ndfl.ru/api/v1/calc \
  -H "Content-Type: application/json" \
  -d '{"gross_salary": 12000000}'

JavaScript (Public API)

fetch("/api/v1/calc", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ gross_salary: 12000000 })
})
  .then(r => r.json())
  .then(console.log)
  .catch(console.error);

curl (Private API)

curl -X POST https://calculator-ndfl.ru/api/v1/private-calc \
  -H "Content-Type: application/json" \
  -H "x-api-key: <ваш_private_api_key>" \
  -d '{ 
        "gross_salary": 12000000,
        "territorial_multiplier": 120,
        "northern_coefficient": 150,
        "start_date": "2025-01-01",
        "has_tax_privilege": false
      }'

JavaScript (Private API)

fetch("/api/v1/private-calc", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<ваш_private_api_key>"
  },
  body: JSON.stringify({
    gross_salary: 12000000,
    territorial_multiplier: 120,
    northern_coefficient: 150,
    start_date: "2025-01-01",
    has_tax_privilege: false
  })
})
  .then(r => r.json())
  .then(console.log)
  .catch(console.error);