МойСклад Phone API 1.0
API Endpoint
https://api.moysklad.ru/api/phone/1.0API интергации для телефонных провайдеров
Общие Сведения ¶
Аутентификация
Для того чтобы успешно взаимодействовать с Phone API онлайн-сервиса МойСклад необходимо аутентифицироваться в системе. МойСклад поддерживает аутентификацию через передачу в заголовке параметра Lognex-Phone-Auth-Token
со значением ключа аутентификации, который генерируется для клиента при подключении Phone API на странице Приложений.
Замечания по разработке клиентских приложений
При разработке клиентского приложения необходимо учитывать следующие моменты:
-
Phone API работает с обязательным сжатием трафика, поэтому HTTP запрос должен содержать заголовок Accept-Encoding с методом сжатия gzip
-
Структура ответов и типы полей поддерживаются нами неизменными
-
Может быть добавлено новое поле без нарушения структуры ответа
-
Может быть добавлен новый ресурс
Ограничения
Для Phone API установлены следующие ограничения:
-
Не более 100 запросов за 5 секундный период
-
Не более 5 одновременных запросов от одного пользователя
-
Не более 100 одновременных запросов с одного ip-адреса
Метаданные
В Phone API есть несколько видов Метаданных. Один из них - поле meta, которое фигурирует в большинстве JSON представлений объектов, и содержит информацию об объекте или о выдаче, а также может использоваться в качестве ссылки на другой объект. Поле meta представляет собой объект со следующими атрибутами:
-
href - Ссылка на объект
-
type - Тип объекта
-
mediaType - Тип данных, которые приходят в ответ от сервиса, либо отправляются в теле запроса. В рамках данного API всегда равен
application/json
Обработка ошибок
СТРУКТУРА ОШИБОК
Ошибка в данном API представляет собой массив errors, содержащий объекты error, каждый из которых описывает отдельную ошибку.
СТРУКТУРА ОБЪЕКТА error
-
error - Заголовок ошибки
-
parameter - Параметр, на котором произошла ошибка
-
code - Код ошибки (Если поле ничего не содержит, смотрите HTTP status code)
-
error_message - Сообщение, прилагаемое к ошибке.
Возвращаемые HTTP статусы ошибок и их значения:
HTTP status code | Значение |
---|---|
301 | Запрашиваемый ресурс находится по другому URL. |
400 | Ошибка в структуре JSON передаваемого запроса |
401 | Имя и/или пароль пользователя указаны неверно или заблокированы пользователь или аккаунт |
403 | У вас нет прав на просмотр данного объекта |
404 | Запрошенный ресурс не существует |
405 | http-метод указан неверно для запрошенного ресурса |
409 | Указанный объект используется и не может быть удалён |
410 | Версия API больше не поддерживается |
412 | Не указан обязательный параметр строки запроса или поле структуры JSON |
413 | Размер запроса или количество элементов запроса превышает лимит (например, количество позиций, передаваемых в массиве positions, превышает 100) |
429 | Превышен лимит количества запросов |
500 | При обработке запроса возникла непредвиденная ошибка |
502 | Сервис временно недоступен |
503 | Сервис временно отключен |
504 | Превышен таймаут обращения к сервису, повторите попытку позднее |
Также, вместе с телом ответа ошибки, вам могут прийти следующие заголовки (Headers):
-
X-Lognex-Auth - расширенный код ошибки аутентификации
-
X-Lognex-Auth-Message - сообщение об ошибке.
-
X-Lognex-API-Version-Deprecated - дата отключения запрошенной версии API.
-
Location - URL по которому доступен запрашиваемый ресурс (в случае ответа с кодом 301)
Все коды ошибок и их описания
1000
- Сообщение: Элемент URI не является идентификатором
- Описание: Вероятнее всего вы пытаетесь обратиться к несуществующему ресурсу. Проверьте указанный вами URI, проверьте правильно ли вы указали ключевое слово сущности и полностью ли вы скопировали ID.
1002
- Сообщение: Неопознанный путь: {путь}
- Описание: Не удалось определить ресурс, по которому был сделан запрос. Проверьте URI по которому совершается запрос.
1021
- Сообщение: Объект с типом ‘{тип}’ и идентификатором ‘{id}’ не найден
- Описание: Не удалось загрузить сущность данного типа с данным id. Проверьте корректность id. Убедитесь что сущность с данным id присутствует среди списка сущностей данного типа (возможно сущность с данным id была удалена)
1034
- Сообщение: Ошибка фильтрации: ‘{описание ошибки}’
- Описание: Не удалось отфильтровать сущности по заданному параметру. Проверьте корректность запроса.
1037
- Сообщение: Неверно указан Content-Type запроса
- Описание Возможно ресурс, к которому вы обращаетесь, требует form-data вместо JSON (или наоборот).
1039
- Сообщение: Операция {HTTP метод} не поддерживается для данного ресурса
- Описание Проверьте метод, с которым вы обращаетесь к ресурсу. Убедитесь, что в документации ресурса этот метод описан и его можно применить.
1040
- Сообщение: Неверно заданы параметры запроса
- Описание Один или несколько параметров запроса заданы некорректно. Проверьте формат параметров согласно документации.
1044
- Сообщение: Превышен максимальный размер запроса
- Описание: Максимальный размер запроса 10 МБ.
1051
- Сообщение: Тип
не совпадает с типом <meta_type> из meta - Описание Тип, который вы указали в объекте meta не соответствует типу ресурса, к которому вы делаете запрос.
1052
- Сообщение: Неверный формат UUID
- Описание: Проверьте сгенерированные вами UUID на корректность.
1056
- Сообщение: Ошибка аутентификации: {текст ошибки аутентификации}
- Описание Проверьте указанные для аутентификации данные. Возможно для данного ресурса требуется другой вид аутентификации.
1060
- Сообщение: Некорректный тип данных в meta сущности, поле type
- Описание Тип данных указанный в поле type метаданных сущности не совпадает с ожидаемым типом.
1062
- Сообщение: Неверное значение заголовка ‘Accept’. Поддерживается только значение ‘application/json;charset=utf-8’
- Описание Значение заголовка ‘Accept’ может быть только application/json;charset=utf-8.
1065
- Сообщение: Ошибка сохранения объекта: объект уже изменен/удален в параллельном запросе
- Описание Ошибка возникает при попытке изменить объект из нескольких параллельных запросов к API.
1074
- Сообщение: Сервис временно недоступен, ведутся технические работы
- Описание На сервере проводятся технические работы.
1999
- Сообщение: Неизвестная ошибка
- Описание Произошла непредвиденная ошибка. Пожалуйста, обратитесь в поддержку сервиса МойСклад подробно изложив условия при которых эта ошибка произошла.
2001
- Сообщение: Ошибка формата: входящий запрос не соответствует формату JSON
- Описание: Данные должны быть отправлены в формате JSON. Если это так, а ошибка всё-таки возникает - попробуйте добавить Header
Content-Type
со значениемapplication/json
.
2005
- Сообщение: Ошибка формата: входящий JSON должен начинаться либо с объекта, либо с массива
- Описание: Отсутствует открывающаяся фигурная/квадратная скобка в начале тела запроса.
2009
- Сообщение: Ошибка формата: запрос на создание/обновление одной сущности не должен содержать массив
- Описание: При обновлении отдельной сущности подразумевается, что в теле запроса будет передано её новое представление (одно). В теле запроса должен быть один корневой объект.
2010
- Сообщение: Ошибка формата: отсутствует href для meta поля ‘{доп. сообщение}’
- Описание: В переданном объекте метаданных отсутствует поле href. Проверьте тело запроса.
2011
- Сообщение: Ошибка формата: отсутствует type для meta поля ‘{доп. сообщение}’
- Описание: В переданном объекте метаданных отсутствует поле type. Проверьте тело запроса.
2013
- Сообщение: Ошибка формата: неправильное значение href для meta поля ‘{доп. сообщение}’
- Описание: Переданный href указывает на несуществующий объект. Убедитесь в корректности ссылки. Ошибка может быть в версии API, типе ресурса (entity/pos/report), ключевом слове сущности/(отчёта), id сущности.
2017
- Сообщение: Ошибка формата: неизвестная ошибка
- Описание: Не удалось однозначно классифицировать ошибку. Убедитесь что формат передаваемых вами данных соответствует требуемому. Посмотрите примеры запросов в документации по используемой вами сущности.
3000
- Сообщение: Ошибка сохранения объекта: поле ‘{имя поля}’ не может быть пустым или отсутствовать
- Описание: Необходимое поле не может содержать пустого значения или отсутствовать. Все необходимые поля можно посмотреть в документации по сущности, с которой вы работаете, под заголовком “Атрибуты сущности”. Такие поля помечены как
Необходимое
.
3005
- Сообщение: Ошибка сохранения объекта: неверное значение ‘{значение}’ поля ‘{имя поля}’. Допустимые значения: {список значений}
- Описание: Вы пытаетесь присвоить несуществующее значение полю типа “перечисление”(enum). Проверить все возможные значения этого поля вы можете в документации по данной сущности в разделе “Атрибуты сущности”.
3006
- Сообщение: Ошибка сохранения объекта: нарушено ограничение уникальности параметра ‘{имя параметра}’
- Описание: У указанного поля/параметра должно быть уникальное значение в системе. Например, если включена проверка на уникальность номеров операций,
name
у разных документов не может быть одинаковым.
3007
- Сообщение: Ошибка валидации сохраняемого объекта: ‘{доп. сообщение}’
- Описание: Ошибка при обмене. Проверьте, соблюдает ли все условия передаваемый вами объект.
55008
- Сообщение: Не установлено приложение для работы c ‘{наименование API}’
- Описание: Для работы с ресурсом необходимо установить приложение из списка приложений МоегоСклада.
Создание и обновление объекта
При создании объекта достаточно заполнить только поля, помеченные Необходимое
. Данные поля используются только при создании, при обновлении они не требуются.
Поля, помеченные Только для чтения
, игнорируются при создании/обновлении объекта.
Пустые поля
Если какое-то из полей сущности не было заполнено и, при этом оно не является обязательным, оно не будет выдано в JSON представлении этой сущности.
Формат даты и времени
В Phone API поля типа дата-время (момент времени) - это строка в формате:
-
Без миллисекунд:
ГГГГ-ММ-ДД ЧЧ:мм:сс
-
С миллисекундами:
ГГГГ-ММ-ДД ЧЧ:мм:сс.ммм
Для получения полей типа дата-время с миллисекундами в формате:ГГГГ-ММ-ДД ЧЧ:ММ:СС.ммм
нужно добавить специальный заголовок к запросу:
X-Lognex-Format-Millisecond
со значениемtrue
. В запросах на создание/обновление сущностей, а также в параметрах фильтрации нужно указыватьmoment
именно в этом формате.
Вывод JSON с отступами
В Phone API можно получать ответы от сервера в виде pretty-print JSON (JSON с отступами вместо JSON в одну строку). Для этого нужно добавить специальный заголовок к запросу:
Lognex-Pretty-Print-JSON
со значением true
.
Фильтрация выборки с помощью параметра filter
Для фильтрации выборки по нескольким полям можно использовать url параметр filter
.
Значение этого параметра - urlencoded строка с поисковыми условиями, перечисленными через ;
. (Все примеры ниже указаны без urlencoded для лучшей читаемости)
Каждое поисковое условие - это сочетание названия поля, оператора и константы.
Фильтровать можно по всем полям, значения которых являются примитивными типами. Т.е. нельзя фильтровать поля-объекты и поля-массивы,
все остальные поля могут быть использованы в параметре filter
.
- Допустимые операторы:
['=', '!=', '~', '~=', '=~']
Если в поисковом запросе несколько раз встречается условие типа “равенство” =
применённое к одному и тому же полю,
то такое условие интерпретируется как совокупность условий, разделённых логическим оператором ИЛИ
.
- Например условие
filter=sum=100;sum=150
будет интерпретировано какsum=100 ИЛИ sum=150
или жеsum in (100, 150)
Если же встречается несколько условий вида “не равно” !=
, наложенных на одну и ту же переменную, то они интерпретируются как совокупность
условий разделённых логическим оператором И
.
- Например условие
filter=name!=0001;name!=0002
будет эквивалентно следующим (взаимно эквивалентным) условиям :name != 0001 И name != 0002
илиname not in (0001, 0002)
Если на одно из полей наложено ограничение типа “равенство”, а затем на него накладывается ограничение типа неравенство - в таком случае произойдёт ошибка.
- Например условие
filter=sum=100;sum!=99
вызовет ошибку.
Проверка на пустое значение
Если в строке фильтрации указать конструкцию вида: <имя_поля>=;
то в выборку попадут только объекты, где
данное поле равно null (т.е. отсутствует значение), а если тип поля - строковое, то будет также выполнена проверка на пустую строку, т.е. поле=’’.
Конструкция <имя_поля>!=;
выполнит проверку на присутствие значения. С помощью данной конструкции можно проверить наличие значения в ссылочном поле.
Фильтрация работников по внутреннему номеру
Для фильтрации выборки следует использовать параметр extention. Параметр является строковым. Примеры фильтров
-
filter=extention=101
-
filter=extention~=10
Сценарий работы ¶
Перед использованием Phone API клиент должен подключить данную функциональность в настройках МоегоСклада на страници приложений. Там происходит генерация ключа доступа.
Сценарий работы с Phone API состоит из нескольких шагов:
-
Создание сущности звонка
-
Рассылка событий карточки звонка (нотификации)
-
Обновление сущности звонка при его завершении/добавлении записи
Существующая функциональность МоегоСклада по работе со звонками состоит из следующих пунктов
-
Функциональность по просмотру истории звонков с контрагентами с возможностью прослушать запись разговора при её наличии
-
Отображение нотификаций о звонках, происходящих в данный момент
-
Возможность инициировать исходящий вызов
Пример
Ниже, в качестве примера, описан один из возможных сценариев работы с Phone API, состоящий из следующих шагов:
-
Создание сущности звонка
-
Рассылка событий карточки звонка (нотификации)
-
Обновление сущности звонка при его завершении/добавлении записи
Создать звонок ¶
Пример запроса для создания Звонка.
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
{
"externalId": "AkjhDlkJDlkjD09D",
"number": "+74959999999",
"extension": "101",
"isIncoming": true,
"startTime": "2017-01-01 00:00:05.000",
"comment": "example comment"
}
Успешный запрос. Результат - JSON представление созданного звонка.
Headers
Content-Type: application/json
{
"meta": {
"href": "https://api.moysklad.ru/api/phone/1.0/call/89fc07ad-2c8d-11e6-8a84-bae500000051",
"type": "call",
"mediaType": "application/json"
},
"id": "89fc07ad-2c8d-11e6-8a84-bae500000051",
"externalId": "AkjhDlkJDlkjD09D",
"number": "+74959999999",
"counterparty": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
"type": "counterparty",
"mediaType": "application/json"
},
"counterpartyowner": {
"extention": "100",
"meta": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
}
},
"comment": "example comment",
"extension": "100",
"employee": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
},
"isIncoming": true,
"startTime": "2017-01-01 00:00:05.000",
"endTime": null,
"duration": null,
"recordUrl": []
}
Пример запроса для создания Звонка с одновременным отображением нотификации.
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
{
"externalId": "AkjhDlkJDlkjD09D",
"number": "+74959999999",
"extension": "101",
"isIncoming": true,
"startTime": "2017-01-01 00:00:05.000",
"events": [
{
"eventType": "SHOW",
"extension": "101",
"sequence": 1
}
]
}
Успешный запрос. Результат - JSON представление созданного звонка.
Headers
Content-Type: application/json
{
"meta": {
"href": "https://api.moysklad.ru/api/phone/1.0/call/89fc07ad-2c8d-11e6-8a84-bae500000051",
"type": "call",
"mediaType": "application/json"
},
"id": "89fc07ad-2c8d-11e6-8a84-bae500000051",
"externalId": "AkjhDlkJDlkjD09D",
"number": "+74959999999",
"counterparty": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
"type": "counterparty",
"mediaType": "application/json"
},
"counterpartyowner": {
"extention": "100",
"meta": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
}
},
"comment": "example comment",
"extension": "100",
"employee": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
},
"isIncoming": true,
"startTime": "2017-01-01 00:00:05.000",
"endTime": null,
"duration": null,
"recordUrl": []
}
Создать звонокPOST/call
Создаём сущность звонка, которая теперь доступна для просмотра как через интерфейс, так и через PhoneApi
Послать событие карточки звонка ¶
Событие карточки звонка с указанным id.
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
{
"eventType": "SHOW",
"extension": "101",
"sequence": 1
}
Успешный запрос.
Headers
Content-Type: application/json
Послать событие карточки звонкаPOST/call/{id}/event
Показываем нотификацию клиенту о том что начался звонок
- id
string
(required) Example: 7944ef04-f831-11e5-7a69-971500188b19id Звонка.
Изменить звонок ¶
В теле запроса можно указать только те поля, которые необходимо изменить у звонка
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
{
"endTime": "2017-01-01 00:01:05.000",
"recordUrl": [
"http://some_url.ru"
],
"comment": "updated example comment",
"events": [
{
"eventType": "HIDE",
"extension": "101",
"sequence": 2
}
]
}
Успешное обновление. Результат - JSON представление обновлённого Контрагента.
Headers
Content-Type: application/json
{
"meta": {
"href": "https://api.moysklad.ru/api/phone/1.0/call/89fc07ad-2c8d-11e6-8a84-bae500000051",
"type": "call",
"mediaType": "application/json"
},
"id": "89fc07ad-2c8d-11e6-8a84-bae500000051",
"externalId": "AkjhDlkJDlkjD09D",
"number": "+74959999999",
"counterparty": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
"type": "counterparty",
"mediaType": "application/json"
},
"counterpartyowner": {
"extention": "100",
"meta": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
}
},
"comment": "updated example comment",
"extension": "101",
"employee": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
},
"isIncoming": true,
"startTime": "2017-01-01 00:00:05.000",
"endTime": "2017-01-01 00:01:05.000",
"duration": 0,
"recordUrl": [
"http://some_url.ru"
]
}
Изменить звонокPUT/call/{id}
Обновляем звонок при его завершении/добавлении записи. Одновременно скрываем нотификаю.
- id
string
(required) Example: 89fc07ad-2c8d-11e6-8a84-bae500000051id Звонка.
Найти сотрудников с добавочным номером ¶
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
Успешный поиск. Результат - JSON представление сотрудника.
Headers
Content-Type: application/json
{
"employees": [
{
"meta": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/7bac6104-1c79-11e8-5bec-bccf0000002a",
"type": "employee",
"mediaType": "application/json"
},
"extention": "1234"
}
]
}
Найти сотрудников с добавочным номеромGET/employee?filter={filter}
Ищем сотрудников с добавочным номером с возможностью фильтрации в запросе по нему
- filter
string
(optional) Example: extention~=12фильтр в запросе.
Звонок ¶
Средствами JSON API можно создавать и обновлять сведения о звонках, а так же направлять события карточки звонка.
Создать звонок ¶
Пример полного запроса для создания Звонка.
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
{
"externalId": "AkjhDlkJDlkjD09D",
"number": "+74959999999",
"counterparty": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
"type": "counterparty",
"mediaType": "application/json"
},
"extension": "100",
"employee": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ad-2c8d-11e6-8a84-bae500001324",
"type": "employee",
"mediaType": "application/json"
},
"isIncoming": true,
"startTime": "2017-01-01 00:00:05.000",
"endTime": "2017-01-01 00:00:05.000",
"duration": 0,
"recordUrl": [
"http://some_url.ru"
],
"comment": "example comment",
"events": [
{
"eventType": "SHOW",
"extension": "101",
"sequence": 1,
"employee": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ad-2c8d-11e6-8a84-bae500001325",
"type": "employee",
"mediaType": "application/json"
}
}
]
}
Успешный запрос. Результат - JSON представление созданного звонка.
Headers
Content-Type: application/json
{
"meta": {
"href": "https://api.moysklad.ru/api/phone/1.0/call/89fc07ad-2c8d-11e6-8a84-bae500000051",
"type": "call",
"mediaType": "application/json"
},
"id": "89fc07ad-2c8d-11e6-8a84-bae500000051",
"externalId": "AkjhDlkJDlkjD09D",
"number": "+74959999999",
"counterparty": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
"type": "counterparty",
"mediaType": "application/json"
},
"counterpartyowner": {
"extention": "100",
"meta": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
}
},
"extension": "100",
"comment": "example comment",
"employee": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
},
"isIncoming": true,
"startTime": "2017-01-01 00:00:05.000",
"endTime": "2017-01-01 00:00:05.000",
"duration": 0,
"recordUrl": [
"http://some_url.ru"
]
}
Создать звонокPOST/call
Создать новый звонок
Описание
Звонок создаётся на основе переданного объекта JSON, который содержит представление нового Звонка. Поле counterparty, при его заполнении, приоритетнее чем number. Поле employee, при его заполнении, приоритетнее чем extension. Поле endTime, при его заполнении, приоритетнее чем duration.
-
externalId -
Необходимое
Внешний ID звонка -
number -
Необходимое
Внешний номер телефона -
counterparty - Ссылка на Контрагента, с которым связан звонок в формате Метаданных
-
extension - Добавочный номер пользователя, который совершил звонок, или который привязан к звонку
-
employee - Сотрудник, с которым связан звонок, в формате Метаданных
-
isIncoming -
Необходимое
Направление звонка: входящий (true) или исходящий(false) -
startTime -
Необходимое
Время начала разговора: время в ISO формате (yyyy-MM-dd HH:mm:ss.SSS) -
endTime - Время окончания разговора: время в ISO формате (yyyy-MM-dd HH:mm:ss.SSS)
-
duration - Продолжительность вызова в миллисекундах
-
recordUrl - Массив URL записей разговоров
-
events - Список событий карточки звонка для обработки
- eventType -
Необходимое
Тип события (SHOW, STARTTIME, HIDE) - extension -
Необходимое
Добавочный номер - sequence -
Необходимое
Порядковый номер события - employee - Сотрудник, которому предназначена нотификация, в формате Метаданных
- eventType -
-
comment - Комментарий к звонку. Строка, не более 4096 символов (слишком длинная строка обрезается).
Получить звонок ¶
Успешный запрос. Результат - JSON представление Звонка с указанным id.
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
{
"meta": {
"href": "https://api.moysklad.ru/api/phone/1.0/call/7944ef04-f831-11e5-7a69-971500188b19",
"type": "call",
"mediaType": "application/json"
},
"id": "89fc07ad-2c8d-11e6-8a84-bae500000051",
"externalId": "AkjhDlkJDlkjD09D",
"number": "+74959999999",
"counterparty": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
"type": "counterparty",
"mediaType": "application/json"
},
"counterpartyowner": {
"extention": "100",
"meta": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
}
},
"extension": "100",
"comment": "example comment",
"employee": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
},
"isIncoming": true,
"startTime": "2017-01-01 00:00:05.000",
"endTime": "2017-01-01 00:00:05.000",
"duration": 0,
"recordUrl": [
"http://some_url.ru"
]
}
Получить звонокGET/call/{id}
Возвращает JSON представление Звонка с указанным id.
- id
string
(required) Example: 89fc07ad-2c8d-11e6-8a84-bae500000051id Звонка.
Изменить звонок ¶
Headers
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
Content-Type: application/json
В теле запроса можно указать только те поля, которые необходимо изменить у звонка
Успешное обновление. Результат - JSON представление обновлённого звонка.
Headers
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
Content-Type: application/json
{
"meta": {
"href": "https://api.moysklad.ru/api/phone/1.0/call/89fc07ad-2c8d-11e6-8a84-bae500000051",
"type": "call",
"mediaType": "application/json"
},
"id": "89fc07ad-2c8d-11e6-8a84-bae500000051",
"externalId": "AkjhDlkJDlkjD09D",
"number": "+74959999999",
"counterparty": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
"type": "counterparty",
"mediaType": "application/json"
},
"comment": "updated call comment",
"extension": "100",
"employee": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000051",
"type": "employee",
"mediaType": "application/json"
},
"isIncoming": true,
"startTime": "2017-01-01 00:00:05.000",
"endTime": "2017-01-01 00:00:05.000",
"duration": 0,
"recordUrl": [
"http://some_url.ru"
]
}
Изменить звонокPUT/call/{id}
Описание
Обновляется представление Звонка с указанным id. В теле запроса можно указать только те поля, которые необходимо изменить у Звонка. Поля, которые не были указаны в JSON запроса, не изменяются, поля уже заполненные у сущности не перезаписываются (за исключением comment). Поле recordUrl добавляет данные к сущности. Поле comment обновляется, только если не null. Поле employee, при его заполнении, приоритетнее чем extension. Поле endTime, при его заполнении, приоритетнее чем duration.
-
extension - Добавочный номер пользователя, который совершил звонок, или который привязан к звонку
-
employee - Сотрудник, с которым связан звонок, в формате Метаданных
-
endTime - Время окончания разговора: время в ISO формате (yyyy-MM-dd HH:mm:ss.SSS)
-
duration - Продолжительность вызова в миллисекундах
-
recordUrl - Массив URL записей разговоров
-
events - Список событий карточки звонка для обработки
- eventType -
Необходимое
Тип события- SHOW - Показать карточку звонка
- STARTTIME - Запустить таймер карточки
- HIDE - Скрыть карточку звонка
- HIDE_ALL - Скрыть карточки для всех участников звонка
- extension -
Необходимое
Добавочный номер. Для типа события HIDE_ALL не является обязательным - sequence -
Необходимое
Порядковый номер события - employee - Сотрудник, которому предназначена нотификация, в формате Метаданных
- eventType -
-
comment - Комментарий к звонку. Может быть обновлен любое количество раз, null - не обновлять поле.
- id
string
(required) Example: 89fc07ad-2c8d-11e6-8a84-bae500000051id Звонка.
Изменить звонок по внешнему ID ¶
В теле запроса можно указать только те поля, которые необходимо изменить у звонка
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
{
"extension": "100",
"employee": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ad-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
},
"endTime": "2017-01-01 00:00:05.000",
"recordUrl": [
"http://some_url.ru"
],
"comment": "updated call comment",
"events": [
{
"eventType": "SHOW",
"extension": "101",
"sequence": 1,
"employee": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ad-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
}
}
]
}
Успешное обновление. Результат - JSON представление обновлённого звонка.
Headers
Content-Type: application/json
{
"meta": {
"href": "https://api.moysklad.ru/api/phone/1.0/call/89fc07ad-2c8d-11e6-8a84-bae500000051",
"type": "call",
"mediaType": "application/json"
},
"id": "89fc07ad-2c8d-11e6-8a84-bae500000051",
"externalId": "AkjhDlkJDlkjD09D",
"number": "+74959999999",
"counterparty": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
"type": "counterparty",
"mediaType": "application/json"
},
"comment": "updated call comment",
"extension": "100",
"employee": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000051",
"type": "employee",
"mediaType": "application/json"
},
"isIncoming": true,
"startTime": "2017-01-01 00:00:05.000",
"endTime": "2017-01-01 00:00:05.000",
"duration": 0,
"recordUrl": [
"http://some_url.ru"
]
}
Изменить звонок по внешнему IDPUT/call/extid/{extid}
Описание
Обновляется представление Звонка с указанным extid. В теле запроса можно указать только те поля, которые необходимо изменить у Звонка. Поля, которые не были указаны в JSON запроса, не изменяются, поля уже заполненные у сущности не перезаписываются (за исключением comment). Поле recordUrl добавляет данные к сущности. Поле comment обновляется, только если не null.
-
extension - Добавочный номер пользователя, который совершил звонок, или который привязан к звонку
-
employee - Сотрудник, с которым связан звонок, в формате Метаданных
-
endTime - Время окончания разговора: время в ISO формате (yyyy-MM-dd HH:mm:ss.SSS)
-
duration - Продолжительность вызова в миллисекундах
-
recordUrl - Массив URL записей разговоров
-
events - Список событий карточки звонка для обработки
- eventType -
Необходимое
Тип события- SHOW - Показать карточку звонка
- STARTTIME - Запустить таймер карточки
- HIDE - Скрыть карточку звонка
- HIDE_ALL - Скрыть карточки для всех участников звонка
- extension -
Необходимое
Добавочный номер. Для типа события HIDE_ALL не является обязательным - sequence -
Необходимое
Порядковый номер события - employee - Сотрудник, которому предназначена нотификация, в формате Метаданных
- eventType -
-
comment - Комментарий к звонку. Может быть обновлен любое количество раз, null - не обновлять поле.
- extid
string
(required) Example: AjllkmSAkmlВнешний id Звонка.
Событие карточки звонка по внутреннему id ¶
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
{
"eventType": "SHOW",
"extension": "101",
"sequence": 1,
"employee": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ad-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
}
}
Успешный запрос.
Headers
Content-Type: application/json
Послать событие карточки звонка по внутреннему idPOST/call/{id}/event
Посылает событие карточки звонка.
-
eventType -
Необходимое
Тип события- SHOW - Показать карточку звонка
- STARTTIME - Запустить таймер карточки
- HIDE - Скрыть карточку звонка
- HIDE_ALL - Скрыть карточки для всех участников звонка
-
extension -
Необходимое
Добавочный номер. Для типа события HIDE_ALL не является обязательным -
sequence -
Необходимое
Порядковый номер события -
employee - Сотрудник, которому предназначена нотификация, в формате Метаданных
- id
string
(required) Example: 7944ef04-f831-11e5-7a69-971500188b19id Звонка.
Событие карточки звонка по внешнему id ¶
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
{
"eventType": "SHOW",
"extension": "101",
"sequence": 1,
"employee": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/88fc07ad-2c8d-11e6-8a84-bae500000050",
"type": "employee",
"mediaType": "application/json"
}
}
Успешный запрос.
Headers
Content-Type: application/json
Послать событие карточки звонка по внешнему idPOST/call/extid/{extid}/event
Посылает событие карточки звонка.
-
eventType -
Необходимое
Тип события- SHOW - Показать карточку звонка
- STARTTIME - Запустить таймер карточки
- HIDE - Скрыть карточку звонка
- HIDE_ALL - Скрыть карточки для всех участников звонка
-
extension -
Необходимое
Добавочный номер. Для типа события HIDE_ALL не является обязательным -
sequence -
Необходимое
Порядковый номер события -
employee - Сотрудник, которому предназначена нотификация, в формате Метаданных
- extid
string
(required) Example: AjllkmSAkmlВнешний id Звонка.
Сотрудники ¶
Средствами JSON API можно получать список сотрудников, обладающих добавочным номером, с возможностью фильтрации результата.
Найти сотрудников с добавочным номером ¶
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
Успешный поиск. Результат - JSON представление сотрудника.
Headers
Content-Type: application/json
{
"employees": [
{
"meta": {
"href": "https://api.moysklad.ru/api/remap/1.2/entity/employee/7bac6104-1c79-11e8-5bec-bccf0000002a",
"type": "employee",
"mediaType": "application/json"
},
"extention": "1234"
}
]
}
Найти сотрудников с добавочным номеромGET/employee?filter={filter}
Ищем сотрудников с добавочным номером с возможностью фильтрации в запросе по нему. Тело запроса пусто. Параметры фильтрации описаны в разделе фильтрации
- filter
string
(optional) Example: extention=1234фильтр в запросе.
Требования к провайдеру телефонии ¶
В рамках интеграции провайдеру телефонии необходимо реализовать обработку запроса для инициации исходящего вызова. В http заголовке передается подпись, которая генерируется на основе алгоритма md5, на вход которого подается конкатенация ключа доступа пользователя и значений параметров запроса.
Исходящий вызов ¶
Пример полного запроса для создания Звонка.
Headers
Content-Type: application/json
Lognex-Content-MD5: 802EFD4A933386248031D2928612A13F
{
"srcNumber": "100",
"destNumber": "+74959999999",
"uid": "admin@companyname"
}
Успешный запрос.
Headers
Content-Type: application/json
Исходящий вызовPOST/some_url
-
srcNumber - номер, с которого производится исходящий вызов
-
destNumber - номер телефона, на который происходит звонок
-
uid - логин сотрудника, совершающего вызов