PropNum Developer Hub

API Документация

Мощный инструментарий для работы с документами и данными. Интегрируйте функции PropNum в свои приложения, сайты и таблицы.

Основные принципы

API построено на принципах REST. Запросы принимаются методами POST (JSON) и GET (для интеграций). Все ответы возвращаются в формате JSON.

Base URL

https://propnum.ru

Формат данных

application/json

Авторизация

Public API без ключа, Morph API по API key

1. Конвертация чисел в текст

Перевод чисел в сумму прописью с поддержкой валют и падежей.

EndpointPOST /api/convert/numGET /api/convert/num?amount=100

Параметры запроса:

amountЧисло для конвертации (обязательно)
currencyRUB, USD, EUR, KZT. По умолчанию: RUB
caseПадеж: nom, gen, dat, acc, ins, pre. По умолчанию: nom

Terminal (bash)

curl -X POST https://propnum.ru/api/convert/num \
  -H "Content-Type: application/json" \
  -d '{"amount": 1250, "currency": "RUB"}'

JavaScript

const res = await fetch('https://propnum.ru/api/convert/num', {
  method: 'POST',
  body: JSON.stringify({ amount: 1500.50, currency: 'RUB' })
});
const data = await res.json();
console.log(data.result.full); // "Одна тысяча пятьсот рублей 50 копеек"

2. Дата прописью

Текстовое представление даты для договоров и приказов.

EndpointPOST /api/convert/date

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

Request Body

{
  "date": "01.01.2026",
  "case": "gen"
}

Response Example

{
  "full": "первого января две тысячи двадцать шестого года",
  "parts": { "day": "первого", "month": "января", "year": "две тысячи двадцать шестого года" }
}

3. Склонение слов и словосочетаний

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

EndpointPOST /api/convert/casesGET /api/convert/cases?phrase=трудовой%20договор&grammaticalCase=datPOST /api/v1/morph/inflectPOST /api/v1/morph/analyzePOST /api/v1/morph/declensionPOST /api/v1/morph/spellPOST /api/v1/morph/ordinalPOST /api/v1/morph/spell-datePOST /api/v1/morph/fio/analyzePOST /api/v1/morph/gender

Параметры запроса:

phraseСлово или словосочетание с поддержкой названий судов, юридических шаблонов и числительных
grammaticalCasenom, gen, dat, acc, ins, pre. По умолчанию: nom
modestrict для точных юридических кейсов, broad для расширенных эвристик
flagsname, feminine, masculine, animate, inanimate, common для снятия неоднозначности
domainlegal, courts, documents, roles, authorities, generic
result.modefull или partial, если часть фразы оставлена без изменений
diagnosticsheadGender, headNumber и numeralValueKind доступны в versioned morph API

Versioned Morph API

Для /api/v1/morph/* используйте Authorization: Bearer <api_key> или X-API-Key. Public endpoint /api/convert/cases остаётся совместимым UI-обёрткой для базовых сценариев.

Расширенный morph suite дополняет базовое склонение отдельными capability-endpoint’ами: /declension, /spell, /ordinal, /spell-date, /fio/analyze, /gender и /userdict/*.

Terminal (bash)

curl -X POST https://propnum.ru/api/convert/cases \
  -H "Content-Type: application/json" \
  -d '{"phrase": "два трудовых договора", "grammaticalCase": "gen"}'

Commercial Morph API

curl -X POST https://propnum.ru/api/v1/morph/inflect \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{"text":"два трудовых договора","targetCase":"gen","mode":"strict","domain":"legal"}'

Response Example

{
  "phrase": "два трудовых договора",
  "case": "gen",
  "result": {
    "text": "двух трудовых договоров",
    "mode": "full",
    "warnings": []
  }
}

Versioned Response Example

{
  "input": {
    "text": "два трудовых договора",
    "targetCase": "gen",
    "mode": "strict",
    "domain": "legal"
  },
  "result": {
    "text": "двух трудовых договоров",
    "status": "full",
    "warnings": [],
    "unchangedTokens": [],
    "matchedTemplate": "numbered_adjective_noun",
    "confidence": 0.98,
    "diagnostics": {
      "headGender": "male",
      "headNumber": "plural",
      "numeralValueKind": "few"
    }
  },
  "meta": {
    "version": "v1",
    "requestId": "morph-..."
  }
}

Declension Suite Example

{
  "input": {
    "text": "Александр Пушкин",
    "flags": ["name", "masculine"],
    "mode": "strict",
    "domain": "generic"
  },
  "result": {
    "singular": {
      "nom": "Александр Пушкин",
      "gen": "Александра Пушкина",
      "dat": "Александру Пушкину",
      "acc": "Александра Пушкина",
      "ins": "Александром Пушкиным",
      "pre": "Александре Пушкине",
      "pre_o": "об Александре Пушкине"
    },
    "gender": "male",
    "fio": {
      "surname": "Пушкин",
      "name": "Александр"
    },
    "status": "full"
  }
}

4. Расчет НДС

Выделение и начисление НДС с автоматическим расчетом.

Параметры mode:

extract— Выделить НДС из общей суммы (включен в стоимость).
add— Начислить НДС сверх указанной суммы.

cURL

curl -X POST https://propnum.ru/api/convert/nds \
  -d '{"amount": 1200, "rate": 20, "mode": "extract"}'

5. Валидация ИНН

Проверка корректности ИНН по контрольным числам для Физлиц и Юрлиц.

Метод проверяет ИНН на соответствие формату (10 или 12 цифр) и вычисляет контрольное число согласно алгоритму ФНС.

cURL

curl -X POST https://propnum.ru/api/validate/inn \
  -d '{"inn": "7707083893"}'

Лимиты и ошибки

Мы предоставляем API бесплатно для всех пользователей. Для обеспечения стабильности мы используем гибкое ограничение частоты запросов.

Если вы используете API из CRM, таблиц, ботов или серверных интеграций, лучше сразу заложить защиту от кратковременных ограничений: не отправлять одинаковые запросы повторно без необходимости, разбивать массовую обработку на небольшие пачки и корректно обрабатывать ответ 429 с повторной попыткой через задержку.

Общие лимиты

• 60 запросов в минуту на один IP
• 1000 запросов в сутки бесплатно
• Без регистрации

Коды ошибок

• 429 — Превышен лимит запросов
• 400 — Некорректные параметры
• 500 — Внутренняя ошибка сервера

Как снизить риск ограничения

• Кэшируйте результаты для повторяющихся сумм, дат и фраз хотя бы на несколько минут.
• Не отправляйте большой объём запросов одним всплеском: лучше разбивать обработку на небольшие пачки.
• Если запросы идут в цикле, добавляйте паузу 200–500 мс между вызовами.
• Для таблиц и скриптов вызывайте API только для непустых и изменившихся значений, а не для всего диапазона на каждом пересчёте.
• Не дублируйте одинаковые вызовы одновременно из клиента и сервера в одном сценарии.

Что делать при ошибке 429

• Не повторяйте запрос мгновенно: это обычно только продлевает ограничение.
• Сделайте паузу 5–15 секунд и повторите запрос.
• Если ограничение повторяется, используйте backoff: 5 → 15 → 30 секунд.
• Для пакетных задач сохраняйте прогресс, чтобы после паузы продолжить с последнего успешного элемента.
• В интерфейсе показывайте понятное сообщение пользователю: «Лимит запросов временно исчерпан, повторите чуть позже».
• Если ваш сценарий стабильно упирается в бесплатные лимиты, напишите нам через контакты и опишите тип нагрузки.

Интеграция в таблицы

Используйте мощь PropNum напрямую в Google Таблицах или Excel без программирования сложных формул.

GS
Google Sheets (Apps Script)

Автоматизируйте работу в облачных таблицах без установки ПО:

В Google Таблице перейдите в меню Расширения → Apps Script.
Вставьте код функции, приведенный ниже, в редактор скриптов.
Нажмите иконку Сохранить (дискету) и дайте проекту имя.
Теперь используйте в любой ячейке формулу =PROPNUM(A1).

Apps Script (JS)

function PROPNUM(amount) {
  if (!amount) return "";
  const cleanAmount = amount.toString().replace(/\s/g, '').replace(',', '.');
  const url = "https://propnum.ru/api/convert/num?amount=" + encodeURIComponent(cleanAmount);
  const res = UrlFetchApp.fetch(url, { "muteHttpExceptions": true });
  if (res.getResponseCode() !== 200) return "Ошибка: " + res.getResponseCode();
  const data = JSON.parse(res.getContentText());
  return data.result.full;
}

⚡ Высокая стабильность через GET

💡 Совет: Используйте формат /api/convert/num для доступа к дополнительным параметрам (валюты, падежи).

XL
Excel VBA (Макросы)

Используйте функции PropNum в локальных файлах Excel:

Нажмите Alt + F11 в Excel для открытия редактора макросов.
Перейдите в Вставка (Insert) → Модуль (Module).
Вставьте код функции, приведенный ниже, в открывшееся окно.
Теперь вам доступна новая функция =PROPNUM(A1).

VBA

Function PROPNUM(amount As Double) As String
    Dim xml As Object: Set xml = CreateObject("MSXML2.XMLHTTP.6.0")
    xml.Open "GET", "https://propnum.ru/api/convert/num?amount=" & amount, False
    xml.Send
    Dim resp As String: resp = xml.ResponseText
    If InStr(resp, """full"":""") > 0 Then
        PROPNUM = Split(Split(resp, """full"":""")(1), """")(0)
    Else: PROPNUM = "Ошибка": End If
End Function

⚠️ Сохраняйте файл как .xlsm

Макросы требуют разрешения на выполнение при открытии документа.

CORS & Браузеры

Наше API поддерживает кросс-доменные запросы (CORS). Это значит, что вы можете вызывать методы напрямую из браузерного JavaScript без использования прокси-серверов.

Поддержка

Нужна помощь в интеграции или есть идеи по улучшению? Мы всегда открыты для диалога. Напишите нам, и мы ответим в течение 24 часов.

Связаться с нами

API Документация

Основные принципы

1. Конвертация чисел в текст

Параметры запроса:

2. Дата прописью

3. Склонение слов и словосочетаний

Параметры запроса:

4. Расчет НДС

5. Валидация ИНН

Лимиты и ошибки

Общие лимиты

Коды ошибок

Как снизить риск ограничения

Что делать при ошибке 429

Интеграция в таблицы

GS
Google Sheets (Apps Script)

XL
Excel VBA (Макросы)

CORS & Браузеры

Поддержка

Попробуйте инструменты онлайн

Слова

Конвертер чисел прописью

Генератор документов

Руководство пользователя

FAQ

API Документация

Основные принципы

1. Конвертация чисел в текст

Параметры запроса:

2. Дата прописью

3. Склонение слов и словосочетаний

Параметры запроса:

4. Расчет НДС

5. Валидация ИНН

Лимиты и ошибки

Общие лимиты

Коды ошибок

Как снизить риск ограничения

Что делать при ошибке 429

Интеграция в таблицы

GSGoogle Sheets (Apps Script)

XLExcel VBA (Макросы)

CORS & Браузеры

Поддержка

Попробуйте инструменты онлайн

Слова

Конвертер чисел прописью

Генератор документов

Руководство пользователя

FAQ

GS
Google Sheets (Apps Script)

XL
Excel VBA (Макросы)