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

API данного сервиса предоставляет простой и удобный интерфейс для получения производственного календаря в форматах JSON, XML и CSV для использования в вашем приложении. Для этого необходимо отправить HTTP GET-запрос с необходимыми параметрами (при необходимости) по заданному адресу. Сервис предоставляем доступ к двум методам.

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

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

где:

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

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

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

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

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

• JSON;
• XML;
• CSV.

Примеры:

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

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

Примеры:

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

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

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

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

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

• 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 – количество праздничных дней в периоде;
• working_hours – количество рабочего времени за период.

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

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

Глобальные переменные;Код страны;ru
Глобальные переменные;Страна;Российская Федерация
Глобальные переменные;Начало периода;01.01.2023
Глобальные переменные;Конец периода;31.12.2023
Глобальные переменные;Тип рабочей недели;5-и дневная рабочая неделя
Глобальные переменные;Период;год
Сутки;01.01.2023;3;Государственный праздник;вс;0;Новогодние каникулы
Сутки;02.01.2023;3;Государственный праздник;пн;0;Новогодние каникулы
Сутки;03.01.2023;3;Государственный праздник;вт;0;Новогодние каникулы
Сутки;04.01.2023;3;Государственный праздник;ср;0;Новогодние каникулы
Сутки;05.01.2023;3;Государственный праздник;чт;0;Новогодние каникулы
Сутки;06.01.2023;3;Государственный праздник;пт;0;Новогодние каникулы
Сутки;07.01.2023;3;Государственный праздник;сб;0;Рождество Христово
Сутки;08.01.2023;3;Государственный праздник;вс;0;Новогодние каникулы
Сутки;09.01.2023;1;Рабочий день;пн;8;
Сутки;10.01.2023;1;Рабочий день;вт;8;
...
Сутки;30.12.2023;2;Выходной день;сб;0;
Сутки;31.12.2023;2;Выходной день;вс;0;
Статистика;Календарных дней;365
Статистика;Календарных дней без праздничных;350
Статистика;Рабочих дней;246
Статистика;Выходных без праздничных;104
Статистика;Праздничные;15
Статистика;Рабочего времени;1964

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

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

где:

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

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

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

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

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

• php