Руководство по использованию web-сервиса производственного календаря

Доступ к API сервиса производственного календаря является простым, быстрым и удобным инструментом для использования в Вашем приложении. Чтобы начать использовать сервис, просто отправьте HTTP GET-запрос с необходимыми параметрами (при необходимости) по нужному адресу. Сервис предоставляем доступ к следующим методам.

1. Основной метод get-period

Данный метод возвращает производственный календарь за произвольный период. URI данного метода представляет собой строку типа:

https://production-calendar.ru/get-period/{token}/{country}/{period}/{format}

где:

• {token} - индивидуальный токен доступа (получить можно тут)
• {country} – буквенный код страны;
• {period} – необходимый временной интервал;
• {format} – формат получаемых данных.

Простой пример для получения результата для РФ за январь 2025 года в формате JSON (в примере используется гостевой токен имеющий ряд ограничений):

https://production-calendar.ru/get-period/6914a408120146bcb82ab95c003bc6ad/ru/01.2025/json

Поддерживаемые страны {country}:

Информацию о полноте базы данных для указанных стран можно посмотреть тут.

Поддерживаемые форматы временного интервала {period}:

Кроме того, в качестве временного интервала {period} возможно передавать зарезервированные динамические переменные:

При этом динамические переменные поддерживают модификаторы (плюс или минус) позволяющие увеличить или уменьшить соответствующий интервал от текущего. Например, передав значение today+1 можно всегда получать данные за следующие сутки от текущих. Соответственно today+2 на двое суток итд. Модификаторы можно применять ко всем динамическим переменным.

Динамическую переменную today можно применять при задании произвольного интервала. Например, если передать {period} в виде строки today+1-today+8 вы всегда будете получать результат с данными на неделю вперед начиная с завтрашнего дня.

Поддерживаемые форматы получения данных от сервера {format}:

• JSON;
• XML;
• CSV.

Примеры:

https://production-calendar.ru/get-period/6914a408120146bcb82ab95c003bc6ad/ru/01.2025/xml
https://production-calendar.ru/get-period/6914a408120146bcb82ab95c003bc6ad/kz/01.2025/csv
https://production-calendar.ru/get-period/6914a408120146bcb82ab95c003bc6ad/by/03.2025/json

GET-параметры метода get-period

Для получения дополнительных данных, в URI можно передать ряд get-параметров. Все параметры не являются обязательными.

Примеры:

https://production-calendar.ru/get-period/6914a408120146bcb82ab95c003bc6ad/ru/042025/json?region=26
https://production-calendar.ru/get-period/6914a408120146bcb82ab95c003bc6ad/ru/042025/json?region=26&compact=true
https://production-calendar.ru/get-period/6914a408120146bcb82ab95c003bc6ad/ru/012025/json?region=26&week_type=6
https://production-calendar.ru/get-period/6914a408120146bcb82ab95c003bc6ad/ru/04.2020/json?wsch=1

Структура ответа сервера

Разберем структуру на примере ответа в формате JSON:

{
    "status": "ok"
    "country_code": "ru",
    "country_text": "Российская Федерация",
    "region_id": 26,
    "region_text": "Ставропольский край",
    "dt_start": "01.01.2025",
    "dt_end": "15.01.2025",
    "work_week_type": "5-и дневная рабочая неделя",
    "period": "Произвольный период",
    "statistic":
        {
            "calendar_days": 15,
            "calendar_days_without_holidays": 7,
            "work_days": 5,
            "weekends": 2,
            "holidays": 8,
            "shortened_working_days": 0,
            "working_hours": 40
        }
    },
    "days": [
        {
            "date": "01.01.2025",
            "type_id": 3,
            "type_text": "Государственный праздник",
            "note": "Новогодние каникулы",
            "week_day": "вс",
            "working_hours": 0
        },
        ...
        {
            "date": "08.01.2025",
            "type_id": 2,
            "type_text": "Выходной день",
            "week_day": "вс",
            "working_hours": 0
        },
        ...
        {
            "date": "15.01.2025",
            "type_id": 2,
            "type_text": "Выходной день",
            "week_day": "вс",
            "working_hours": 0
        }
    ]
}

Основные свойства главного объекта (country_code, country_text, region_id, region_text, dt_start, dt_end, work_week_type) интуитивно понятны и не требуют отдельного описания.

Свойство days представляет из себя массив объектов (или один объект, в зависимости от состояния get-параметра days_as_object), которые описывают календарные сутки. Каждый элемент массива содержит объект со следующими свойствами:

• type_id и type_text определяют тип суток:

• week_day – сокращенное наименование дня недели;
• working_hours – количество рабочих часов в данных сутках для 40-й часовой рабочей недели;
• is_project – наличие данного свойства равным 1 (true) означает что указанные сутки в производственном календаре находится в проект закона и еще не утверждена правительством;
• is_wsch - наличие свойства равным 1, означает что день является так называемый выходным днем с сохранением заработной платы. Смотри описание GET-параметра wsch.

Свойство statistic отображает ряд статистических данных для задаваемого периода:

• calendar_days – количество календарных дней в периоде;
• calendar_days_without_holidays - количество календарных дней в периоде без учета праздничных дней (полезный показатель для расчета продолжительности отпуска работника);
• work_days – количество рабочих дней в периоде;
• weekends – количество выходных дней в периоде (без учета праздничных);
• holidays – количество праздничных дней в периоде;
• shortened_working_days – количество сокращенных рабочих дней в периоде;
• working_hours – количество рабочего времени за период.

Формат XML имеет идентичную структуру и наименование параметров с форматом JSON и не требует отдельного описания.

Формат CSV адаптирован под русскоязычный MS Excel (кодировка windows-1251, разделитель точка с запятой (;)). Полученные данные с легкостью открываются в MS Excel без дополнительных преобразований. Строки, которые описывают производственный календарь начинаются с ключевого слова «Сутки», после идут значения, соответствующие параметрам date, type_id, type_text, week_day, working_hours описанные выше.

Глобальные переменные;Статус;ok
Глобальные переменные;Код страны;ru
Глобальные переменные;Страна;Российская Федерация
Глобальные переменные;Начало периода;01.01.2023
Глобальные переменные;Конец периода;31.12.2023
Глобальные переменные;Тип рабочей недели;5-и дневная рабочая неделя
Глобальные переменные;Период;год
Сутки;01.01.2025;3;Государственный праздник;вс;0;Новогодние каникулы
Сутки;02.01.2025;3;Государственный праздник;пн;0;Новогодние каникулы
Сутки;03.01.2025;3;Государственный праздник;вт;0;Новогодние каникулы
Сутки;04.01.2025;3;Государственный праздник;ср;0;Новогодние каникулы
Сутки;05.01.2025;3;Государственный праздник;чт;0;Новогодние каникулы
Сутки;06.01.2025;3;Государственный праздник;пт;0;Новогодние каникулы
Сутки;07.01.2025;3;Государственный праздник;сб;0;Рождество Христово
Сутки;08.01.2025;3;Государственный праздник;вс;0;Новогодние каникулы
Сутки;09.01.2025;1;Рабочий день;пн;8;
Сутки;10.01.2025;1;Рабочий день;вт;8;
...
Сутки;30.12.2025;2;Выходной день;сб;0;
Сутки;31.12.2025;2;Выходной день;вс;0;
Статистика;Календарных дней;365
Статистика;Календарных дней без праздничных;350
Статистика;Рабочих дней;246
Статистика;Выходных без праздничных;104
Статистика;Праздничные;15
Статистика;Рабочего времени;1964

2. Метод get-work-week

Данный метод возвращает даты начало и окончания рабочей недели по заданным суткам. URI данного метода представляет собой строку типа:

https://production-calendar.ru/get-work-week/{token}/{country}/{day}/{format}

где:

• {token} - индивидуальный токен доступа (получить можно тут)
• {country} – буквенный код страны;
• {day} – исходные сутки;
• {format} – формат получаемых данных.

Простой пример для получения результата для РФ для суток 06.03.2025 год в формате JSON:

https://production-calendar.ru/get-work-week/6914a408120146bcb82ab95c003bc6ad/ru/06.03.2025/json

Данный метод поддерживает только один get-параметр - week_type (подробности смотри в разделе 1 данного руководства)

Библиотеки от сообщества

При желании можно использовать SDK от разработчиков сообщества. На текущий момент доступны следующие библиотеки:

• php