Мы решили опубликовать заметку о работе сложных фильтров аналитик через REST API по единственной причине — видим c вашей стороны недостаточное понимание того, как работать с этим инструментом. Ещё сразу отметим, заметка посвящена опытным пользователям. Она точно будет полезна разработчикам, которые используют REST API ПланФикса. Если вы не используете REST в своей работе, ничего страшного — это нормально. Солнце не перестанет светить, а земля крутиться 🙂
Далее на примере покажем работу со сложными фильтрами аналитик и как передавать данные по аналитикам Фактическое и Планируемое время работы из ПланФикса в другие системы.
Руководство поставило перед Сергеем интересную задачу — передать из ПланФикса данные по аналитикам Фактическое и Планируемое время работы во внутреннюю систему расчета зарплаты на базе 1С.
— И как мне это провернуть? — сказал Сергей, попутно открывая справку ПланФикса. После продолжительного изучения документации он решил всё сделать через REST API.
Первый шаг
Для начала Сергей создал токен авторизации с уровнем доступа на чтение аналитик:
Что запрашивать у API?
Прежде чем писать код на стороне 1С, Сергей перешел по ссылке в спецификацию и авторизовался с помощью токена, чтобы сразу протестировать и отладить работу:
Первым делом необходимо узнать идентификаторы нужных аналитик и их полей, чтобы понимать, что запрашивать у API.
Сергей воспользовался методом получения списка всех аналитик /datatag/list и выполнил запрос с параметрами:
{
"offset": 0,
"pageSize": 100,
"fields": "id,name,group,fields"
}
В ответ Сергей получил идентификаторы нужных аналитик и их полей:
{
"result": "success",
"dataTags": [{
"id": 4,
"name": "Планируемое время работы",
"group": {
"id": 1,
"name": "Управление временем"
},
"fields": [{
"id": 6,
"name": "Дата",
"type": 3,
"objectType": 4
}, {
"id": 7,
"name": "Планируемое время работы",
"type": 6,
"objectType": 4
}, {
"id": 17,
"name": "Сотрудник",
"type": 14,
"objectType": 4
}
]
}, {
"id": 12,
"name": "Фактическое время работы",
"group": {
"id": 1,
"name": "Управление временем"
},
"fields": [{
"id": 52,
"name": "Дата",
"type": 3,
"objectType": 4,
"directoryId": 10
}, {
"id": 54,
"name": "Время работы",
"type": 6,
"objectType": 4,
"directoryId": 10
}, {
"id": 56,
"name": "Тип времени",
"type": 9,
"objectType": 4,
"directoryId": 8
}, {
"id": 58,
"name": "Вид работы",
"type": 9,
"objectType": 4,
"directoryId": 10
}, {
"id": 60,
"name": "Сотрудник",
"type": 14,
"objectType": 4
}
]
}
]
}
Как получить все записи по аналитике?
Теперь Сергею нужны все записи по аналитике Планируемое время работы. Для получения данных он использовал метод /datatag/{id}/entry/list с параметром id «4» и телом запроса:
{
"offset": 0,
"pageSize": 100,
"fields": "key,6,7,17"
}
В поле fields Сергей передал идентификаторы полей аналитики, которые он хотел бы получить в ответ и поле key — это идентификатор записи аналитики. В ответ он получил все необходимые данные:
{
"result": "success",
"dataTagEntries": [{
"key": 40,
"customFieldData": [{
"field": {
"id": 6,
"name": "Дата",
"type": 3,
"objectType": 4
},
"value": {
"datetime": "2023-09-15T00:00Z",
"date": "15-09-2023",
"time": "00:00"
},
"stringValue": "15-09-2023"
}, {
"field": {
"id": 7,
"name": "Планируемое время работы",
"type": 6,
"objectType": 4
},
"value": {
"from": {
"time": "09:00"
},
"to": {
"time": "17:00"
}
},
"stringValue": "09:00 - 17:00"
}, {
"field": {
"id": 17,
"name": "Сотрудник",
"type": 14,
"objectType": 4
},
"value": [{
"id": "user:10",
"name": "Иван Иванов"
}
],
"stringValue": "Иван Иванов"
}
]
}, {
"key": 41,
"customFieldData": [{
"field": {
"id": 6,
"name": "Дата",
"type": 3,
"objectType": 4
},
"value": {
"datetime": "2023-09-18T00:00Z",
"date": "18-09-2023",
"time": "00:00"
},
"stringValue": "18-09-2023"
}, {
"field": {
"id": 7,
"name": "Планируемое время работы",
"type": 6,
"objectType": 4
},
"value": {
"from": {
"time": "09:00"
},
"to": {
"time": "14:00"
}
},
"stringValue": "09:00 - 14:00"
}, {
"field": {
"id": 17,
"name": "Сотрудник",
"type": 14,
"objectType": 4
},
"value": [{
"id": "user:10",
"name": "Иван Иванов"
}
],
"stringValue": "Иван Иванов"
}
]
}
]
}
Как отфильтровать данные аналитики?
Теперь полученные данные было бы неплохо отфильтровать по полю типа «Дата», чтобы получить записи только за определенный период.
Для этого Сергей обратился в раздел справки Сложные фильтры аналитик и нашел там необходимый фильтр – 3101. В спецификации был уже пример такого фильтра, Сергей воспользовался им и отправил запрос:
{
"offset": 0,
"pageSize": 100,
"fields": "key,6,7,17",
"filters": [{
"type": 3101,
"field": 6,
"operator": "equal",
"value": {
"dateType": "otherRange",
"dateFrom": "18-09-2023",
"dateTo": "18-09-2023"
}
}
В ответ он получил записи данной аналитики за 18 число:
{
"result": "success",
"dataTagEntries": [
{
"key": 41,
"customFieldData": [
{
"field": {
"id": 6,
"name": "Дата",
"type": 3,
"objectType": 4
},
"value": {
"datetime": "2023-09-18T00:00Z",
"date": "18-09-2023",
"time": "00:00"
},
"stringValue": "18-09-2023"
},
{
"field": {
"id": 7,
"name": "Планируемое время работы",
"type": 6,
"objectType": 4
},
"value": {
"from": {
"time": "09:00"
},
"to": {
"time": "14:00"
}
},
"stringValue": "09:00 - 14:00"
},
{
"field": {
"id": 17,
"name": "Сотрудник",
"type": 14,
"objectType": 4
},
"value": [
{
"id": "user:10",
"name": "Иван Иванов"
}
],
"stringValue": "Иван Иванов"
}
]
}
]
}
Обработка ответов в 1С
— Готово! Теперь можно переключиться на 1С, — продолжал бубнить себе под нос наш герой.
Сергею осталось реализовать выполнение запросов и обработку ответов с записью получаемых данных в базу 1С.
Аналогичным образом он поступил и с аналитикой Фактическое время работы — передал в запрос идентификатор этой аналитики «12» и тело с необходимыми параметрами:
{
"offset": 0,
"pageSize": 100,
"fields": "key,52,54,56,58,60",
"filters": [
{
"type": 3101,
"field": 52,
"operator": "equal",
"value": {
"dateType": "otherRange",
"dateFrom": "18-09-2023",
"dateTo": "18-09-2023"
}
}
]
}
В ответ получил также данные за 18 число:
{
"result": "success",
"dataTagEntries": [{
"key": 43,
"customFieldData": [{
"field": {
"id": 52,
"name": "Дата",
"type": 3,
"objectType": 4,
"directoryId": 10
},
"value": {
"datetime": "2023-09-18T00:00Z",
"date": "18-09-2023",
"time": "00:00"
},
"stringValue": "18-09-2023"
}, {
"field": {
"id": 54,
"name": "Время работы",
"type": 6,
"objectType": 4,
"directoryId": 10
},
"value": {
"from": {
"time": "13:00"
},
"to": {
"time": "19:00"
}
},
"stringValue": "13:00 - 19:00"
}, {
"field": {
"id": 56,
"name": "Тип времени",
"type": 9,
"objectType": 4,
"directoryId": 8
},
"value": {
"id": 1,
"value": "Рабочее время"
},
"stringValue": "1"
}, {
"field": {
"id": 58,
"name": "Вид работы",
"type": 9,
"objectType": 4,
"directoryId": 10
},
"value": {
"id": 10,
"value": "Доработка дизайн-макета"
},
"stringValue": "10"
}, {
"field": {
"id": 60,
"name": "Сотрудник",
"type": 14,
"objectType": 4
},
"value": [{
"id": "user:10",
"name": "Иван Иванов"
}
],
"stringValue": "Иван Иванов"
}
]
}
]
}
— Ну вот и всё! — радостно, потирая руки, произнёс Сергей, после тестирования настройки.
— Степан Петрович, у меня всё готово. Когда, говорите, у нас зарплата? Хотелось бы обсудить один момент…
Так можно работать со сложными фильтрами в REST API и передавать данные по аналитикам Фактическое и Планируемое время работы из ПланФикса в другие системы. Если какие-то моменты вызывают вопросы и непонимание — пишите в Службу поддержки, поможем разобраться.
Не забывайте о наших социальных сетях: ВКонтакте, Telegram, Facebook, Twitter и YouTube-канал. Там появляются новости о доработках и новинках. Подпишитесь, чтобы ничего не пропустить.
Вот было бы прекрасно, если бы с помощью какого-либо метода REST API можно было получить данные аналитик с идентификатором задачи, к которой эти аналитики прикреплены. Или я плохо читал справку и так можно сделать?
Здравствуйте! Вы можете корректно реализовать свою задумку только с помощью XML API.
Раньше так сделать было нельзя, но теперь (после вашего комментария) – можно)
Добавили такую возможность: https://t.me/planfix_details_ru/14
А не подскажите, возможно ли получить по REST API чек листы задач?
Перерыл документацию и перепробовал разные запросы, чек листы в ответ не приходят.
Увы, но пока работа с чек-листами через REST API не реализована. Это в планах есть, но не ближайших.
Добрый день, появилась возможность получить по REST API чек-листы задач:
POST /task/{id}/checklist/list
*(необходимые права для работы с данным методом (scope): task_readonly).