REST API: работа со сложными фильтрами аналитик

Мы решили опубликовать заметку о работе сложных фильтров аналитик через 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 и ВК Видео. Там появляются новости о доработках и новинках. Подпишитесь, чтобы ничего не пропустить.

6 комментариев

  1. Аватар

    Вот было бы прекрасно, если бы с помощью какого-либо метода REST API можно было получить данные аналитик с идентификатором задачи, к которой эти аналитики прикреплены. Или я плохо читал справку и так можно сделать?

  2. Аватар

    А не подскажите, возможно ли получить по REST API чек листы задач?
    Перерыл документацию и перепробовал разные запросы, чек листы в ответ не приходят.

    1. Аватар

      Добрый день, появилась возможность получить по REST API чек-листы задач:
      POST /task/{id}/checklist/list
      *(необходимые права для работы с данным методом (scope): task_readonly).

Добавить комментарий