Data API сервера task24.pro
Data API позволяет взаимодействовать с сервером task24 из внешних систем по GET-, POST-запросам, JSON.
Поддерживается CRUD-механизм работы со всеми объектами вашей базы данных:
- Tickets (заявки)
- Categories (категории услуг)
- Users (сотрудники)
- Clients (клиенты)
CRUD- механизм предусматривает следующие действия с объектами:
- get - получить запись по id
- items - получить список записей по фильтру
- add - добавить запись
- save - изменить запись (по id)
- delete - удалить запись (по id)
Далее приводится описание API для отдельных объектов базы данных.
Доступ к API
Доступ к API размещается по адресу:
https://<ваш домен>.task24.pro/data/
Работа с объектами вашей БД осуществляется через CRUD-методы путем URL-запросов. Предусмотрено 2 варианта доступа к данным:
- Метод указан прямо в адресе: https://<ваш домен>.task24.pro/data/<тип данных>/<метод>, где <метод> = {get|add|save|items|delete}
- Метод указан как параметр: https://<ваш домен>.task24.pro/data/<тип данных>?method={get|add|save|items|delete}
В каждом запросе передается Ваш персональный ключ-токен, который отображается в Профиле владельца портала, в поле ID, например, "c1d8hb4d-d4f1-11e3-8301-f4de7aca8743".
Внимание! Данный токен нельзя никому сообщать! Его должен знать ваш сервер или программа. В случае, если Ваш токен узнают посторонние лица, сменить его будет невозможно.
Например, получить все категории:
https://demo.task24.pro/data/categories/items?token=operator
Тестовый режим
Для тестирования предусмотрен тестовый режим. В тестовом режиме никакие изменения не сохраняются.
Для этого нужно передать параметр testmode=1, например:
https://demo.task24.pro/data/categories/items?token=<ваш токен>&testmode=1
Структура данных API
Все данные возвращаются в JSON-формате, следующего вида:
{ success: true/false - признак успешности выполнения запроса. Если true - все в порядке, false - возникли ошибки data: Mixed - возвращаемые данные (результат запроса). Может быть структура/массив/значение например, в случае запроса items, вернет массив записей [] error: код ошибки (строковый). Содержит строковое id ошибки, в случае неудачного выполненния запроса, например, ‘invalid’ - неверный параметр. errormsg: описание ошибки, содержит текстовое описание ошибки, например “неверный параметр” errors: служит уточнением ошибки, какой параметр заполнен неверно, является структурой в виде {“поле”: “значение”} worktime: время обработки запроса, в секундах (служебное) time: время сервера (служебное) }
Далее, в примерах запросов, для краткости, будет показано только содержимое поля data.
Пример для PHP
Создание заказа
//Создание заказа, с заполнением основных реквизитов $res = file_get_contents('https://demo.task24.pro/data/tickets/add?' . http_build_query(array( //ключ вашего аккаунта (можно посмотреть в профиле) 'token' => 'fe91233e-a145-11e4-9c76-001e8c8f500c', //Запланированное время работ 'date' => '2015-02-10 10:35:27', //Сразу на раздачу 'state' => 'distributing', //id категории "Стиральная машина" 'category' => '12a374ad-3c59-47a7-8a23-97c78eb2ad36', //детализация категории 'subject' => 'Проблема с водой', //Описание заказа 'description' => 'LG 10 лет, не сливает воду', //Телефон 'phone' => '89355672210', //Адрес 'address' => 'Пушкинская 213-155', //Контактное лицо 'contact' => 'Марина', //Комментарий (внутренний) 'comment' => 'домофон не работает' )));
Описание API объектов БД
Categories (категории услуг)
Метод | Описание |
---|---|
add |
Создать новую категорию. Параметры:
Возвращает: В результате возвращается структура с полями созданной записи Пример http-запроса: https://demo.task24.pro/data/categories/add? token=demo &name=Доставка корреспонденции &clientcanview=1 Ответ сервера: data:{ "name":"Доставка корреспонденции", "view":"Доставка корреспонденции", "id":"7b6168ac-74c9-11e4-a33d-f46d0485af38" } |
get |
Получить данные записи по ее id. Параметры:
Возвращает: В результате возвращается структура записи категории. Пример http-запроса: https://demo.task24.pro/data/categories/get? token=demo &id=93ae5832-4e22-11e4-8301-f4de7aca8743 Ответ сервера: data:{ "id":"9db92ac6-ea74-11e3-9168-f46d0485af38", "parent":"d5e8c0b8-2ce6-11e4-9eab-f46d0485af38", "view":"Доставка документов", "name":"Доставка документов", "clientcanview":"1", "__owner":"Администратор", "__parent":"Доставка корреспонденции" } |
items |
Получить список записей Параметры:
Возвращает: Возвращает массив записей категорий Пример http-запроса: https://demo.task24.pro/data/categories/items? token=demo &filter={"parent":"a3088d52-4e22-11e4-8301-f4de7aca8743"} Ответ сервера: data:[{ "id":"9db92ac6-ea74-11e3-9168-f46d0485af38", "parent":"d5e8c0b8-2ce6-11e4-9eab-f46d0485af38", "view":"Доставка документов", "name":"Доставка документов", "clientcanview":"1", "__owner":"Администратор", "__parent":"Доставка корреспонденции" }] |
save |
Изменить запись по ее id Параметры:
Возвращает: В результате возвращается структура с полями измененной записи Пример http-запроса: https://demo.task24.pro/data/categories/save? token=demo &id=9db92ac6-ea74-11e3-9168-f46d0485af38 &name=Доставка рекламок &clientcanview=0 Ответ сервера: data:{ "id":"9db92ac6-ea74-11e3-9168-f46d0485af38", "parent":"d5e8c0b8-2ce6-11e4-9eab-f46d0485af38", "view":"Доставка рекламок", "name":"Доставка рекламок", "clientcanview":"0", "__owner":"Администратор", "__parent":"Доставка корреспонденции" } |
delete |
Удалить запись по id. Нельзя удалять категории, в которых есть подкатегории, в этом случае возникает код ошибки 'denied'. В этом случае, сперва надо удалить все подкатегории. Параметры:
Возвращает: В случае успеха, возвращает true. Пример http-запроса: https://demo.task24.pro/data/categories/delete? token=demo &id=9db92ac6-ea74-11e3-9168-f46d0485af38 Ответ сервера: data: true |
Users (пользователи)
Метод | Описание |
---|---|
add |
Создать нового пользователя. Параметры:
Возвращает: В результате возвращается структура с полями созданной записи Пример http-запроса: https://demo.task24.pro/data/users/add? token=demo &name=Петрович &role=worker &phone=%2B79042115020 &comment=Опыт 12 лет по холодильникам, есть авто &workerpercent=60 &properties={"categories":"232758ee-10dc-11e4-8301-f4de7aca8743"} Ответ сервера: data:{ state: "draft", comment: "Опыт 12 лет по холодильникам, есть авто", id: "4e10d7b5-b7f7-4acb-826a-92b25353fb94", name: "Петрович", paid: "0", phone: "+79042115020", photoloaded: "0", processingcount: "0", processinglimit: "", properties: "{"categories":"232758ee-10dc-11e4-8301-f4de7aca8743"}", regdate: "2014-12-04 14:57:13", role: "worker", smscount: "0", view: "Петрович", workerpercent: "60" } |
get |
Получить данные пользователя по его id. Параметры:
Возвращает: В результате возвращается структура записи Пример http-запроса: https://demo.task24.pro/data/users/get? token=demo &id=4e10d7b5-b7f7-4acb-826a-92b25353fb94 Ответ сервера: data:{ state: "active", comment: "Опыт 12 лет по холодильникам, есть авто", id: "4e10d7b5-b7f7-4acb-826a-92b25353fb94", name: "Петрович", paid: "0", phone: "+79042115020", photoloaded: "0", processingcount: "0", processinglimit: "", properties: "{"categories":"232758ee-10dc-11e4-8301-f4de7aca8743"}", regdate: "2014-12-04 14:57:13", role: "worker", smscount: "0", view: "Петрович", workerpercent: "60" } |
items |
Получить список записей сотрудников Параметры:
Возвращает: Возвращает массив записей Пример http-запроса: Получим список активных пользователей https://demo.task24.pro/data/users/items? token=demo &filter={"state": "active"} Ответ сервера: data:[{ state: "active", comment: "Опыт 12 лет по холодильникам, есть авто", id: "4e10d7b5-b7f7-4acb-826a-92b25353fb94", name: "Петрович", paid: "0", phone: "+79042115020", photoloaded: "0", processingcount: "0", processinglimit: "", properties: "{"categories":"232758ee-10dc-11e4-8301-f4de7aca8743"}", regdate: "2014-12-04 14:57:13", role: "worker", smscount: "0", view: "Петрович", workerpercent: "60" }] |
save |
Изменить запись по ее id Параметры:
Далее идет список полей, которые можно изменять
Возвращает: В результате возвращается структура с полями измененной записи Пример http-запроса: Изменим % исполнителя. Так же, установим новый состав доступных категорий (добавим грузоперевозки) https://demo.task24.pro/data/users/save? token=demo &id=4e10d7b5-b7f7-4acb-826a-92b25353fb94 &workerpercent=50 &properties={"categories":"232758ee-10dc-11e4-8301-f4de7aca8743,a3088d52-4e22-11e4-8301-f4de7aca8743"} Ответ сервера: data:{ state: "active", comment: "Опыт 12 лет по холодильникам, есть авто", id: "4e10d7b5-b7f7-4acb-826a-92b25353fb94", name: "Петрович", paid: "0", phone: "+79042115020", photoloaded: "0", processingcount: "0", processinglimit: "", properties: "{"categories":"232758ee-10dc-11e4-8301-f4de7aca8743,a3088d52-4e22-11e4-8301-f4de7aca8743"}", regdate: "2014-12-04 14:57:13", role: "worker", smscount: "0", view: "Петрович", workerpercent: "50" } |
delete |
Удалить запись по id. Параметры:
Возвращает: В случае успеха, возвращает true. Пример http-запроса: https://demo.task24.pro/data/users/delete? token=demo &id=4e10d7b5-b7f7-4acb-826a-92b25353fb94 Ответ сервера: data: true |
Clients (клиенты)
Метод | Описание |
---|---|
add |
Создать нового клиента. Параметры:
Возвращает: В результате возвращается структура с полями созданной записи Пример http-запроса: https://demo.task24.pro/data/clients/add? token=demo &name=Строймонтаж №6 &rank=vip &phone=203-12-33 &address=Мельникова, 24 &contact=Красин Николай &info=Обед с 12:30 до 13:30 Ответ сервера: data:{ accessweb: "0", address: "Мельникова, 24", id: "0da8d106-7bad-11e4-8612-f46d0485af38", info: "Обед с 12:30 до 13:30", lat: "55.736770452865755", lng: "37.63461969818111", name: "Строймонтаж №6", phone: "203-12-33", rank: "vip", regdate: "2014-12-04 15:59:51", view: "Строймонтаж №6" } |
get |
Получить данные клиента по его id. Параметры:
Возвращает: В результате возвращается структура записи Пример http-запроса: https://demo.task24.pro/data/clients/get? token=demo &id=0da8d106-7bad-11e4-8612-f46d0485af38 Ответ сервера: data:{ accessweb: "0", address: "Мельникова, 24", id: "0da8d106-7bad-11e4-8612-f46d0485af38", info: "Обед с 12:30 до 13:30", lat: "55.736770452865755", lng: "37.63461969818111", name: "Строймонтаж №6", phone: "203-12-33", rank: "vip", regdate: "2014-12-04 15:59:51", view: "Строймонтаж №6" } |
items |
Получить список записей клиентов Параметры:
Возвращает: Возвращает массив записей Пример http-запроса: Получим список VIP-клиентов https://demo.task24.pro/data/clients/items? token=demo &filter={"rank": "vip"} Ответ сервера: data:[{ accessweb: "0", address: "Мельникова, 24", id: "0da8d106-7bad-11e4-8612-f46d0485af38", info: "Обед с 12:30 до 13:30", lat: "55.736770452865755", lng: "37.63461969818111", name: "Строймонтаж №6", phone: "203-12-33", rank: "vip", regdate: "2014-12-04 15:59:51", view: "Строймонтаж №6" }] |
save |
Изменить запись по ее id Параметры:
Далее идет список полей, которые можно изменять:
Возвращает: В результате возвращается структура с полями измененной записи Пример http-запроса: Изменим статус и адрес клиента. https://demo.task24.pro/data/clients/save? token=demo &id=4e10d7b5-b7f7-4acb-826a-92b25353fb94 &rank=normal &address=Крутицкая, 11 Ответ сервера: data:{ accessweb: "0", address: "Крутицкая 11", id: "0da8d106-7bad-11e4-8612-f46d0485af38", info: "Обед с 12:30 до 13:30", lat: "55.72828932072981", lng: "37.65988186508178", name: "Строймонтаж №6", phone: "203-12-33", rank: "normal", regdate: "2014-12-04 15:59:51", view: "Строймонтаж №6" } |
delete |
Удалить запись по id. Параметры:
Возвращает: В случае успеха, возвращает true. Пример http-запроса: https://demo.task24.pro/data/clients/delete? token=demo &id=4e10d7b5-b7f7-4acb-826a-92b25353fb94 Ответ сервера: data: true |
Tickets (заявки)
Метод | Описание |
---|---|
add |
Создать новую заявку на сервере. Параметры:
Возвращает: В результате возвращается структура с полями созданной заявки.
Пример http-запроса: https://demo.task24.pro/data/tickets/add?token=demo &testmode=1 &state=opened &category=net &description=<p>Тестовая заявка</p> &date=2014-11-28 Ответ сервера: data: { acceptdate: null, amount: 0, author: "operator", category: "net", date: "2014-11-28", description: "<p>Тестовая заявка</p>", enddate: null, id: "0f9897aa-810e-11e4-9351-f01cb848416d", number: "32", planamount: 0, plansum: 0, priority: "normal", profitsum: 0, regdate: "2014-12-11 12:16:51", state: "opened", subject: null, sum: 0, supplysum: 0, total: 0, view: "№32 от 28.11.14 00:00:00", workerpercent: 0, workersum: 0 } |
get |
Получить данные заявки по ее id. Параметры:
Возвращает: В результате возвращается структура записи Пример http-запроса: https://demo.task24.pro/data/tickets/get? token=demo &id=0da8d106-7bad-11e4-8612-f46d0485af38 Ответ сервера: { __author: "Оператор Наталья", __category: "Грузоперевозки", __client: "Альянс", __owner: "Директор", __worker: "Алексей (водила)", acceptdate: "2014-10-08 14:50:03", amount: "0.0", author: "operator", category: "a3088d52-4e22-11e4-8301-f4de7aca8743", client: "d014dece-4ed4-11e4-8301-f4de7aca8743", address: "Остаповский проезд, 3 ст23", contact: "", email: "", name: "Альянс", phone: "620-69-30", clientrank: "normal", comment: null, date: "2014-10-08 14:48:00", description: "<p>Перевезти сейф + персонал. Сами погрузят/разгрузят</p>", enddate: null, history: [{id: "dc0a64ca-4ed8-11e4-8301-f4de7aca8743", view: "2014-10-08 14:50:03", owner: "demo",…},…], id: "d1de2e3c-4ed8-11e4-8301-f4de7aca8743", number: "23", planamount: "0.0", plansum: "1500.00", priority: "normal", profitsum: "0.00", properties: "{"style":""}", regdate: "2014-10-08 14:49:46", state: "processing", subject: "Крупногабаритные", sum: "0.00", supplysum: "0.00", total: "0.00", view: "№23 от 08.10.14 14:48:00", worker: "2979ce82-20e8-422d-bc8b-3edbf2a688d0", workerpercent: "0.0", workersum: "0.00" } |
items |
Получить список заявок Параметры:
Особенности фильтра:
Если задан фильтр по состоянию документа state, то поля from, to будут работать по разному, в зависимости от состояния:
Возвращает: Возвращает массив записей в data. Так же, возвращается итоговое количесто заявок, по состояниям - структура stat Пример http-запроса: Получим список заявок на раздаче https://demo.task24.pro/data/tickets/items? token=demo &filter={"state": "distributing"} Ответ сервера: data: [{id: "0e80f094-758b-11e4-9351-f01cb848416d", view: "№27 от 26.11.14 20:41:00", number: "27",…},…] stat: {all: 27, opened: 0, distributing: 17, processing: 5, completed: 5, cancelled: 0} |
save |
Изменить запись по ее id Параметры:
Далее идет список полей, которые можно изменять:
Возвращает: В результате возвращается структура с полями измененной записи Пример http-запроса: Изменим состояние заявки. https://demo.task24.pro/data/tickets/save? token=demo &testmode=1 &id=d1de2e3c-4ed8-11e4-8301-f4de7aca8743 &state=opened Ответ сервера: { acceptdate: "2014-10-08 14:50:03", amount: "0.0", author: "operator", category: "a3088d52-4e22-11e4-8301-f4de7aca8743", client: "d014dece-4ed4-11e4-8301-f4de7aca8743", address: "Остаповский проезд, 3 ст23", contact: "", email: "", name: "Альянс", phone: "620-69-30", comment: null, date: "2014-10-08 14:48:00", description: "<p>Перевезти сейф + персонал. Сами погрузят/разгрузят</p>", enddate: null, id: "d1de2e3c-4ed8-11e4-8301-f4de7aca8743", number: "23", planamount: "0.0", plansum: "1500.00", priority: "normal", profitsum: "0.00", regdate: "2014-10-08 14:49:46", state: "opened", subject: "Крупногабаритные", sum: "0.00", supplysum: "0.00", total: "0.00", view: "№23 от 08.10.14 14:48:00", worker: "2979ce82-20e8-422d-bc8b-3edbf2a688d0", workerpercent: "0.0", workersum: "0.00" } |
delete |
Удалить запись по id. Параметры:
Возвращает: В случае успеха, возвращает true. Пример http-запроса: https://demo.task24.pro/data/tickets/delete? token=demo &testmode=1 &id=d1de2e3c-4ed8-11e4-8301-f4de7aca8743 Ответ сервера: data: true |