МойСклад Phone API 1.0

API интергации для телефонных провайдеров

Общие Сведения

Аутентификация

Для того чтобы успешно взаимодействовать с Phone API онлайн-сервиса МойСклад необходимо аутентифицироваться в системе. МойСклад поддерживает аутентификацию через передачу в заголовке параметра Lognex-Phone-Auth-Token со значением ключа аутентификации, который генерируется для клиента при подключении Phone API на странице Приложений.

Замечания по разработке клиентских приложений

При разработке клиентского приложения необходимо учитывать следующие моменты:

  • Структура ответов и типы полей поддерживаются нами неизменными

  • Может быть добавлено новое поле без нарушения структуры ответа

  • Может быть добавлен новый ресурс

Ограничения

Для 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.

2010

  • Сообщение: Ошибка формата: отсутствует href для meta поля ‘{доп. сообщение}’
  • Описание: В переданном объекте метаданных отсутствует поле href. Проверьте тело запроса.

2011

  • Сообщение: Ошибка формата: отсутствует type для meta поля ‘{доп. сообщение}’
  • Описание: В переданном объекте метаданных отсутствует поле type. Проверьте тело запроса.

2013

  • Сообщение: Ошибка формата: неправильное значение href для meta поля ‘{доп. сообщение}’
  • Описание: Переданный href указывает на несуществующий объект. Убедитесь в корректности ссылки. Ошибка может быть в версии API, типе ресурса (entity/pos/report), ключевом слове сущности/(отчёта), id сущности.

3000

  • Сообщение: Ошибка сохранения объекта: поле ‘{имя поля}’ не может быть пустым или отсутствовать
  • Описание: Необходимое поле не может содержать пустого значения или отсутствовать. Все необходимые поля можно посмотреть в документации по сущности, с которой вы работаете, под заголовком “Атрибуты сущности”. Такие поля помечены как Необходимое.

3005

  • Сообщение: Ошибка сохранения объекта: неверное значение ‘{значение}’ поля ‘{имя поля}’. Допустимые значения: {список значений}
  • Описание: Вы пытаетесь присвоить несуществующее значение полю типа “перечисление”(enum). Проверить все возможные значения этого поля вы можете в документации по данной сущности в разделе “Атрибуты сущности”.

3006

  • Сообщение: Ошибка сохранения объекта: нарушено ограничение уникальности параметра ‘{имя параметра}’
  • Описание: У указанного поля/параметра должно быть уникальное значение в системе. Например, если включена проверка на уникальность номеров операций, name у разных документов не может быть одинаковым.

3007

  • Сообщение: Ошибка валидации сохраняемого объекта: ‘{доп. сообщение}’
  • Описание: Ошибка при обмене. Проверьте, соблюдает ли все условия передаваемый вами объект.

Создание и обновление объекта

При создании объекта достаточно заполнить только поля, помеченные Необходимое. Данные поля используются только при создании, при обновлении они не требуются. Поля, помеченные Только для чтения, игнорируются при создании/обновлении объекта.

Пустые поля

Если какое-то из полей сущности не было заполнено и, при этом оно не является обязательным, оно не будет выдано в 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, состоящий из следующих шагов:

  • Создание сущности звонка

  • Рассылка событий карточки звонка (нотификации)

  • Обновление сущности звонка при его завершении/добавлении записи

Создать звонок

POST https://online.moysklad.ru/api/phone/1.0/call
RequestsПример 1Пример 2

Пример запроса для создания Звонка.

Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
BodyСкрытьПоказать
{
  "externalId": "AkjhDlkJDlkjD09D",
  "number": "+74959999999",
  "extension": "101",
  "isIncoming": true,
  "startTime": "2017-01-01 00:00:05.000",
  "comment": "example comment"
}
Responses200

Успешный запрос. Результат - JSON представление созданного звонка.

Headers
Content-Type: application/json
BodyСкрытьПоказать
{
  "meta": {
    "href": "https://online.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://online.moysklad.ru/api/remap/1.1/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
    "type": "counterparty",
    "mediaType": "application/json"
  },
  "counterpartyowner": {
    "extention": "100",
    "meta": {
      "href": "https://online.moysklad.ru/api/remap/1.1/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
      "type": "employee",
      "mediaType": "application/json"
    }
  },
  "comment": "example comment",
  "extension": "100",
  "employee": {
    "href": "https://online.moysklad.ru/api/remap/1.1/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
BodyСкрытьПоказать
{
  "externalId": "AkjhDlkJDlkjD09D",
  "number": "+74959999999",
  "extension": "101",
  "isIncoming": true,
  "startTime": "2017-01-01 00:00:05.000",
  "events": [
    {
      "eventType": "SHOW",
      "extension": "101",
      "sequence": 1
    }
  ]
}
Responses200

Успешный запрос. Результат - JSON представление созданного звонка.

Headers
Content-Type: application/json
BodyСкрытьПоказать
{
  "meta": {
    "href": "https://online.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://online.moysklad.ru/api/remap/1.1/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
    "type": "counterparty",
    "mediaType": "application/json"
  },
  "counterpartyowner": {
    "extention": "100",
    "meta": {
      "href": "https://online.moysklad.ru/api/remap/1.1/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
      "type": "employee",
      "mediaType": "application/json"
    }
  },
  "comment": "example comment",
  "extension": "100",
  "employee": {
    "href": "https://online.moysklad.ru/api/remap/1.1/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.

POST https://online.moysklad.ru/api/phone/1.0/call/7944ef04-f831-11e5-7a69-971500188b19/event
RequestsПример
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
BodyСкрытьПоказать
{
  "eventType": "SHOW",
  "extension": "101",
  "sequence": 1
}
Responses204

Успешный запрос.

Headers
Content-Type: application/json

Послать событие карточки звонка
POST/call/{id}/event

Показываем нотификацию клиенту о том что начался звонок

URI Parameters
СкрытьПоказать
id
string (required) Example: 7944ef04-f831-11e5-7a69-971500188b19

id Звонка.

Изменить звонок

PUT https://online.moysklad.ru/api/phone/1.0/call/89fc07ad-2c8d-11e6-8a84-bae500000051
RequestsПример

В теле запроса можно указать только те поля, которые необходимо изменить у звонка

Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
BodyСкрытьПоказать
{
  "endTime": "2017-01-01 00:01:05.000",
  "recordUrl": [
    "http://some_url.ru"
  ],
  "comment": "updated example comment",
  "events": [
    {
      "eventType": "HIDE",
      "extension": "101",
      "sequence": 2
    }
  ]
}
Responses200

Успешное обновление. Результат - JSON представление обновлённого Контрагента.

Headers
Content-Type: application/json
BodyСкрытьПоказать
{
  "meta": {
    "href": "https://online.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://online.moysklad.ru/api/remap/1.1/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
    "type": "counterparty",
    "mediaType": "application/json"
  },
  "counterpartyowner": {
    "extention": "100",
    "meta": {
      "href": "https://online.moysklad.ru/api/remap/1.1/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
      "type": "employee",
      "mediaType": "application/json"
    }
  },
  "comment": "updated example comment",
  "extension": "101",
  "employee": {
    "href": "https://online.moysklad.ru/api/remap/1.1/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}

Обновляем звонок при его завершении/добавлении записи. Одновременно скрываем нотификаю.

URI Parameters
СкрытьПоказать
id
string (required) Example: 89fc07ad-2c8d-11e6-8a84-bae500000051

id Звонка.

Найти сотрудников с добавочным номером

GET https://online.moysklad.ru/api/phone/1.0/employee?filter=extention~=12
RequestsПример
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
Responses200

Успешный поиск. Результат - JSON представление сотрудника.

Headers
Content-Type: application/json
BodyСкрытьПоказать
{
  "employees": [
    {
      "meta": {
        "href": "https://online.moysklad.ru/api/remap/1.1/entity/employee/7bac6104-1c79-11e8-5bec-bccf0000002a",
        "type": "employee",
        "mediaType": "application/json"
      },
      "extention": "1234"
    }
  ]
}

Найти сотрудников с добавочным номером
GET/employee?filter={filter}

Ищем сотрудников с добавочным номером с возможностью фильтрации в запросе по нему

URI Parameters
СкрытьПоказать
filter
string (optional) Example: extention~=12

фильтр в запросе.

Звонок

Средствами JSON API можно создавать и обновлять сведения о звонках, а так же направлять события карточки звонка.

Создать звонок

POST https://online.moysklad.ru/api/phone/1.0/call
RequestsПример 1

Пример полного запроса для создания Звонка.

Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
BodyСкрытьПоказать
{
  "externalId": "AkjhDlkJDlkjD09D",
  "number": "+74959999999",
  "counterparty": {
    "href": "https://online.moysklad.ru/api/remap/1.1/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
    "type": "counterparty",
    "mediaType": "application/json"
  },
  "extension": "100",
  "employee": {
    "href": "https://online.moysklad.ru/api/remap/1.1/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://online.moysklad.ru/api/remap/1.1/entity/employee/88fc07ad-2c8d-11e6-8a84-bae500001325",
        "type": "employee",
        "mediaType": "application/json"
      }
    }
  ]
}
Responses200

Успешный запрос. Результат - JSON представление созданного звонка.

Headers
Content-Type: application/json
BodyСкрытьПоказать
{
  "meta": {
    "href": "https://online.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://online.moysklad.ru/api/remap/1.1/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
    "type": "counterparty",
    "mediaType": "application/json"
  },
  "counterpartyowner": {
    "extention": "100",
    "meta": {
      "href": "https://online.moysklad.ru/api/remap/1.1/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
      "type": "employee",
      "mediaType": "application/json"
    }
  },
  "extension": "100",
  "comment": "example comment",
  "employee": {
    "href": "https://online.moysklad.ru/api/remap/1.1/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 - Сотрудник, которому предназначена нотификация, в формате Метаданных
  • comment - Комментарий к звонку. Строка, не более 4096 символов (слишком длинная строка обрезается).

Получить звонок

GET https://online.moysklad.ru/api/phone/1.0/call/89fc07ad-2c8d-11e6-8a84-bae500000051
Responses200

Успешный запрос. Результат - JSON представление Звонка с указанным id.

Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
BodyСкрытьПоказать
{
  "meta": {
    "href": "https://online.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://online.moysklad.ru/api/remap/1.1/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
    "type": "counterparty",
    "mediaType": "application/json"
  },
  "counterpartyowner": {
    "extention": "100",
    "meta": {
      "href": "https://online.moysklad.ru/api/remap/1.1/entity/employee/88fc07ac-2c8d-11e6-8a84-bae500000050",
      "type": "employee",
      "mediaType": "application/json"
    }
  },
  "extension": "100",
  "comment": "example comment",
  "employee": {
    "href": "https://online.moysklad.ru/api/remap/1.1/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.

URI Parameters
СкрытьПоказать
id
string (required) Example: 89fc07ad-2c8d-11e6-8a84-bae500000051

id Звонка.

Изменить звонок

PUT https://online.moysklad.ru/api/phone/1.0/call/89fc07ad-2c8d-11e6-8a84-bae500000051
RequestsПример
Headers
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
Content-Type: application/json
BodyСкрытьПоказать
В теле запроса можно указать только те поля, которые необходимо изменить у звонка
Responses200

Успешное обновление. Результат - JSON представление обновлённого звонка.

Headers
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
Content-Type: application/json
BodyСкрытьПоказать
{
  "meta": {
    "href": "https://online.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://online.moysklad.ru/api/remap/1.1/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
    "type": "counterparty",
    "mediaType": "application/json"
  },
  "comment": "updated call comment",
  "extension": "100",
  "employee": {
    "href": "https://online.moysklad.ru/api/remap/1.1/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 - Сотрудник, которому предназначена нотификация, в формате Метаданных
  • comment - Комментарий к звонку. Может быть обновлен любое количество раз, null - не обновлять поле.

URI Parameters
СкрытьПоказать
id
string (required) Example: 89fc07ad-2c8d-11e6-8a84-bae500000051

id Звонка.

Изменить звонок по внешнему ID

PUT https://online.moysklad.ru/api/phone/1.0/call/extid/AjllkmSAkml
RequestsПример

В теле запроса можно указать только те поля, которые необходимо изменить у звонка

Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
BodyСкрытьПоказать
{
  "extension": "100",
  "employee": {
    "href": "https://online.moysklad.ru/api/remap/1.1/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://online.moysklad.ru/api/remap/1.1/entity/employee/88fc07ad-2c8d-11e6-8a84-bae500000050",
        "type": "employee",
        "mediaType": "application/json"
      }
    }
  ]
}
Responses200

Успешное обновление. Результат - JSON представление обновлённого звонка.

Headers
Content-Type: application/json
BodyСкрытьПоказать
{
  "meta": {
    "href": "https://online.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://online.moysklad.ru/api/remap/1.1/entity/counterparty/88fc07ad-2c8d-11e6-8a84-bae500000050",
    "type": "counterparty",
    "mediaType": "application/json"
  },
  "comment": "updated call comment",
  "extension": "100",
  "employee": {
    "href": "https://online.moysklad.ru/api/remap/1.1/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"
  ]
}

Изменить звонок по внешнему ID
PUT/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 - Сотрудник, которому предназначена нотификация, в формате Метаданных
  • comment - Комментарий к звонку. Может быть обновлен любое количество раз, null - не обновлять поле.

URI Parameters
СкрытьПоказать
extid
string (required) Example: AjllkmSAkml

Внешний id Звонка.

Событие карточки звонка по внутреннему id

POST https://online.moysklad.ru/api/phone/1.0/call/7944ef04-f831-11e5-7a69-971500188b19/event
RequestsПример
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
BodyСкрытьПоказать
{
  "eventType": "SHOW",
  "extension": "101",
  "sequence": 1,
  "employee": {
    "href": "https://online.moysklad.ru/api/remap/1.1/entity/employee/88fc07ad-2c8d-11e6-8a84-bae500000050",
    "type": "employee",
    "mediaType": "application/json"
  }
}
Responses204

Успешный запрос.

Headers
Content-Type: application/json

Послать событие карточки звонка по внутреннему id
POST/call/{id}/event

Посылает событие карточки звонка.

  • eventType - Необходимое Тип события

    • SHOW - Показать карточку звонка
    • STARTTIME - Запустить таймер карточки
    • HIDE - Скрыть карточку звонка
    • HIDE_ALL - Скрыть карточки для всех участников звонка
  • extension - Необходимое Добавочный номер. Для типа события HIDE_ALL не является обязательным

  • sequence - Необходимое Порядковый номер события

  • employee - Сотрудник, которому предназначена нотификация, в формате Метаданных

URI Parameters
СкрытьПоказать
id
string (required) Example: 7944ef04-f831-11e5-7a69-971500188b19

id Звонка.

Событие карточки звонка по внешнему id

POST https://online.moysklad.ru/api/phone/1.0/call/extid/AjllkmSAkml/event
RequestsПример
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
BodyСкрытьПоказать
{
  "eventType": "SHOW",
  "extension": "101",
  "sequence": 1,
  "employee": {
    "href": "https://online.moysklad.ru/api/remap/1.1/entity/employee/88fc07ad-2c8d-11e6-8a84-bae500000050",
    "type": "employee",
    "mediaType": "application/json"
  }
}
Responses204

Успешный запрос.

Headers
Content-Type: application/json

Послать событие карточки звонка по внешнему id
POST/call/extid/{extid}/event

Посылает событие карточки звонка.

  • eventType - Необходимое Тип события

    • SHOW - Показать карточку звонка
    • STARTTIME - Запустить таймер карточки
    • HIDE - Скрыть карточку звонка
    • HIDE_ALL - Скрыть карточки для всех участников звонка
  • extension - Необходимое Добавочный номер. Для типа события HIDE_ALL не является обязательным

  • sequence - Необходимое Порядковый номер события

  • employee - Сотрудник, которому предназначена нотификация, в формате Метаданных

URI Parameters
СкрытьПоказать
extid
string (required) Example: AjllkmSAkml

Внешний id Звонка.

Сотрудники

Средствами JSON API можно получать список сотрудников, обладающих добавочным номером, с возможностью фильтрации результата.

Найти сотрудников с добавочным номером

GET https://online.moysklad.ru/api/phone/1.0/employee?filter=extention=1234
RequestsПример
Headers
Content-Type: application/json
Lognex-Phone-Auth-Token: d03627d59c1948a0f9a6aa1e267c954bfd0301ec
Responses200

Успешный поиск. Результат - JSON представление сотрудника.

Headers
Content-Type: application/json
BodyСкрытьПоказать
{
  "employees": [
    {
      "meta": {
        "href": "https://online.moysklad.ru/api/remap/1.1/entity/employee/7bac6104-1c79-11e8-5bec-bccf0000002a",
        "type": "employee",
        "mediaType": "application/json"
      },
      "extention": "1234"
    }
  ]
}

Найти сотрудников с добавочным номером
GET/employee?filter={filter}

Ищем сотрудников с добавочным номером с возможностью фильтрации в запросе по нему. Тело запроса пусто. Параметры фильтрации описаны в разделе фильтрации

URI Parameters
СкрытьПоказать
filter
string (optional) Example: extention=1234

фильтр в запросе.

Требования к провайдеру телефонии

В рамках интеграции провайдеру телефонии необходимо реализовать обработку запроса для инициации исходящего вызова. В http заголовке передается подпись, которая генерируется на основе алгоритма md5, на вход которого подается конкатенация ключа доступа пользователя и значений параметров запроса.

Исходящий вызов

POST https://some.domain//some_url
RequestsПример 1

Пример полного запроса для создания Звонка.

Headers
Content-Type: application/json
Lognex-Content-MD5: 802EFD4A933386248031D2928612A13F
BodyСкрытьПоказать
{
  "srcNumber": "100",
  "destNumber": "+74959999999",
  "uid": "admin@companyname"
}
Responses200

Успешный запрос.

Headers
Content-Type: application/json

Исходящий вызов
POST/some_url

  • srcNumber - номер, с которого производится исходящий вызов

  • destNumber - номер телефона, на который происходит звонок

  • uid - логин сотрудника, совершающего вызов