API-ключ

Для чего нужен API-ключ

API-ключ необходим для:

идентификации клиента и учёта запросов по тарифу;
контроля лимитов (rolling window — 60 секунд и 1 час);
защиты сервиса от несанкционированного доступа.

API-ключ обязателен для запросов к методам с префиксами /fz44, /fz223 и /pprf615. Корневой путь https://v2.gosplan.info/ выполняется без ключа и подходит для простых health-check или получения метаданных.

До окончания переходного периода (01.08.2026) многие ресурсы могут отработать и без ключа, но для корректного учёта запросов и подготовки к новой политике доступа рекомендуется сразу подставлять API-ключ.

Как получить API-ключ

Через Telegram-бота (рекомендуемый способ)

Имя бота: Бот ГосПлан.
Запустите бота командой /start.
API-ключ будет показан в первом сообщении; новый пользователь получает бесплатный период для тестов.
После окончания пробного периода доступ сохраняется только при продлении тарифа.

По запросу на почту

Отправьте письмо в свободной форме на адрес mail@gosplan.info и опишите:

ожидаемые объёмы запросов и частоту обновлений;
предполагаемые подсистемы ЕИС (44-ФЗ, 223-ФЗ, ПП РФ 615);
контактное лицо для уточнения.

Мы свяжемся и согласуем выдачу ключа.

Как использовать ключ

Сервис поддерживает стандартный подход Key Authentication. API-ключ может передаваться:

HTTP-заголовке запроса;
query-параметре URL.

Во всех примерах ниже используется имя ключа apikey.

1. Ключ в заголовке (рекомендуемый способ)

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

curl -X GET -s \
  -H "apikey: $API_KEY" \
  "https://v2.gosplan.info/fz44/purchases?limit=10&skip=0"

Особенности:

ключ не попадает в строку URL и историю браузера;
удобно настраивать в HTTP-клиентах и библиотечных обёртках;
соответствует схеме apikey в Swagger UI.

2. Ключ в query-параметре

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

curl -X GET -s \
  "https://v2.gosplan.info/fz44/purchases?apikey=$API_KEY&limit=10&skip=0"

Особенности:

ключ виден в логах, истории браузера, реферерах и т.п.;
используйте только при осознанном риске и на доверенных каналах;
имя параметра — apikey.

Продление тарифа и оплата

Продление через Telegram-бота (рекомендуемый способ)

Если вы продолжаете работать через Бот ГосПлан, продление тарифа осуществляется прямо в боте:

откройте Бот ГосПлан;
выберите опцию «Продлить тариф»;
укажите срок продления (например, месяц или год).

Бот сформирует ссылку на оплату и проконтролирует зачисление, после чего продлит доступ по вашему API-ключу в рамках выбранного тарифа.

Продление через почту

Продлевать тариф можно через Бот ГосПлан — это проще и быстрее. Если вы привыкли к почте, продолжайте работать по ней, а если работали с ботом и хотите перейти на почту, это тоже возможно.

Для продления по почте:

отправьте письмо на mail@gosplan.info с темой «Продление API-ключа»;
укажите контактные данные, которые использовались при регистрации;
опишите желаемый тариф и срок продления (или ориентировочные объёмы запросов);
при необходимости приложите реквизиты для выставления счёта.

Если регистрация осуществлялась не через Telegram-бота, добавьте в письмо ваш идентификатор пользователя — его можно посмотреть в разделе «Настройки» бота. После получения оплаты доступ по вашему ключу будет продлён в рамках согласованного тарифа.

Коды ответов

Код	Описание
`200 OK`	Запрос выполнен, ответ содержит данные закупок.
`401 Unauthorized`	Отсутствует или неверен API-ключ (заголовок `apikey`, query или тело)
`403 Forbidden`	Ключ найден, но срок действия истёк или доступ запрещён. Обратитесь к поддержке.
`404 Not Found`	Документ не найден — проверьте идентификаторы и дату загрузки.
`429 Too Many Requests`	Превышен тарифный лимит. Обновлённое ограничение — в разделе «Тарифы и лимиты».
`5xx`	Внутренняя ошибка сервера. Повторите запрос позже или свяжитесь с поддержкой.

Быстрый старт

Быстрый старт: curl — пошаговые команды curl.
Быстрый старт: Python — пример скрипта с заголовком apikey.
Быстрый старт: Swagger — использование Swagger UI с авторизацией по ключу.

Если возникли сложности

Если что-то идёт не так — обращайтесь по контактам: https://gosplan.info/contacts/