Общие параметры для всех API сервисов


Содержание

стандартизация контактных данных

Подсказки для адреса

API учетной записи

Программный интерфейс (API) нашего сервиса позволяет использовать функции по обработке контактных данных непосредственно в вашем приложении или на вашем веб-сайте. Например, если у вас есть интернет-магазин, то с помощью API вы сможете организовать коррекцию почтовых адресов, фамилий, имен и отчеств ваших покупателей при заполнении формы заказа.

Посредством API можно обрабатывать контактные данные в реальном времени, например, при непосредственном их вводе. Также API позволяет выполнять стандартизацию уже существующих баз данных с контактной информацией о клиентах и контрагентах.

Принципы взаимодействия с сервисом

Для обработки данных через API вашему приложению или веб-сайту необходимо отсылать сервису соответствующие HTTP-запросы. В ответ на эти запросы сервис возвращает HTTP-сообщения, в теле которых содержится сам результат обработки. Запросы можно отсылать методом GET или POST.

В простейшем случае запрос сервису содержит обычную строку, например с почтовым адресом, стандартизацию которого необходимо выполнить. При использовании метода GET обрабатываемые данные в большинстве команд передаются с помощью параметра query в рамках URL запроса. При использовании метода POST данные передаются с помощью того же параметра query, но уже в рамках тела HTTP-запроса.

Кодировка обрабатываемых данных

Передаваемые на обработку данные должны быть закодированы с использованием процентной схемы кодирования URL-encoding (http://en.wikipedia.org/wiki/Urlencode).

До преобразования в URL-encoding обрабатываемые данные должны быть представлены либо кодировкой UTF-8, либо кодировкой windows-1251. По умолчанию сервис полагает, что данные на обработку представлены в UTF-8. Чтобы сообщить сервису о том, что исходные данные представлены в windows-1251, необходимо использовать URL-параметр input со следующим значением input= cp1251.

Использование API-токена

Кроме обрабатываемых данных в запросе необходимо отсылать API-токен. С помощью этого токена сервис идентифицирует пользователя, от которого получен запрос. Если сервис получит некорректный API-токен, он не будет выполнять обработку запроса, а вместо этого вернет сообщение с соответствующей ошибкой.

API-токен представляет собой строку из латинских букв и цифр. Токен присваивается пользователю при регистрации на сервисе, его можно посмотреть в своем личном кабинете в разделе «Аккаунт».

При отправке запросов сервису API-токен должен передаваться в параметре user.

Формат и кодировка ответа сервиса

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

Для получения ответов от сервиса в формате JSON необходимо в исходном запросе использовать URL-параметр output= json. Для получения ответов в формате XML в рамках URL исходного запроса необходимо использовать параметр output= xml. Использование одного из двух указанных значений параметра output является обязательным. Сервис не сможет выполнить обработку полученных данных без явного указания одного из двух поддерживаемых форматов.

Сервис использует кодировку UTF-8 для представления результатов обработки данных. При использовании формата XML можно запросить ответ в кодировке windows-1251. Для этого используется параметр output со следующим значением: output= xml| cp1251. Здесь для разделения двух значений параметра output используется вертикальная черта.

При формировании ответа в формате JSON сервис по умолчанию не выполняет его форматирования, так что ответ представлен в виде одной сплошной строки без переносов строк, отступов и пробельного прореживания. Для удобства отладки и знакомства с ответами сервиса в формате JSON непосредственно в окне браузера можно попросить сервис выполнить форматирование и представить JSON-ответ в гуманном виде. Для этого необходимо использовать параметр output со следующим значением output= json| pretty.

Пример обработки адреса

Для иллюстрации использования API и всех изложенных выше параметров рассмотрим пример обработки одного почтового адреса. Предположим, что требуется привести к стандартному виду адрес «москва ул. ткацкая, д. 5» . В случае использования UTF-8 данная строка в схеме URL-encoding будет иметь следующий вид.

В случае использования windows-1251 данная строка в схеме URL-encoding будет иметь следующий вид.

Дальше будем полагать, что используется UTF-8 версия этого запроса. Для его обработки необходимо сформировать следующий URL-запрос нашему сервису.

Данный запрос содержит следующие важные компоненты:

  • cleanse/address – команда стандартизации почтового адреса, благодаря этой информации сервис понимает, что от него требуется выполнить обработку одного почтового адреса;
  • user= demotoken – параметр user посредством которого сообщаем сервису наш API-токен. При отправке реального запроса вместо значения demotoken нужно подставить токен из вашего личного кабинета;
  • output= json| pretty – параметр output указывает сервису, что результат стандартизации адреса необходимо вернуть в формате JSON, при этом требуется выполнить его форматирование для нужд отладки;
  • query= длинная строка с кучей процентных символов «%» — параметр, в котором сервису передается почтовый адрес «москва ул. ткацкая, д. 5» , который необходимо исправить и привести к стандартному виду. Адрес представлен в кодировке UTF-8 с использованием процентной схемы кодирования URL-encoding.

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

Здесь сервис вернул JSON-объект, поле » addresses » которого содержит массив с вариантами стандартизации обработанного адреса. Если адрес распознан однозначно, то данный массив будет содержать один вариант стандартизации адреса, как это имеет место в приведенном примере. В массиве » fields » стандартизованного адреса приведены компоненты адреса с разбивкой на отдельные поля, начиная с региона и заканчивая почтовым индексом.

Кроме адресных полей сервис может возвращать дополнительную информацию об адресе: географические координаты адреса (GPS-координаты), коды по справочникам (например, код КЛАДР), показатели качества адреса, отражающие то, насколько правильно и корректно записаны исходные обработанные адресные данные, разметку исходной строки в рамках которой отмечены фрагменты исходной строки, использованные при распознавании адреса и др. Включить вывод всей этой дополнительной информации в ответ сервиса можно либо с помощью соответствующих дополнительных опций параметра output, либо с помощью настроек в личном кабинете пользователя в разделе «Профиль». Дополнительные опции параметра output изложены в описаниях для каждой команды API, ссылки на которые приведены в конце данной статьи.

Для обработки этого же адреса и получения результата в формате XML необходимо отправить сервису следующий URL-запрос.

В отличие от предыдущего примера в данном запросе параметр output имеет значение output= xml, в остальном данный запрос совпадает с запросом из предыдущего примера. Ответ сервиса на данный запрос будет выглядеть следующим образом.

Здесь по аналогии с JSON-ответом адрес разбит на отдельные компоненты, каждый из которых записан в отдельном XML-элементе Field , начиная с адресного поля региона и заканчивая полем с почтовым индексом.

Более подробно параметры и возможности команды API по стандартизации почтового адреса приведены по следующей ссылке: cleanse/address.

Детальное описание всех команд

API стандартизации

Подробное описание всех API-команд сервиса по стандартизации, исправлению и обогащению контактных данных приведено по следующим ссылкам:

  • Команда по стандартизации одного адреса: cleanse/address
  • Команда по стандартизации одного телефона: cleanse/phone
  • Команда по стандартизации фамилии, имени и отчества персоны: cleanse/person
  • Команда по стандартизации записи из нескольких элементов разного типа: cleanse/record
  • Команда по стандартизации пакета из нескольких записей: cleanse/chunk

API подсказок

Подробное описание API-команд сервиса по формированию в реальном времени подсказок при вводе почтовых адресов и ФИО персон приведено по следующим ссылкам:

  • Команда по формированию подсказок при вводе почтового адреса одной строкой: suggest/address
  • Команда по формированию подсказок при вводе ФИО одной строкой: suggest/person/solid
  • Команда по стандартизации фамилии, имени и отчества персоны: suggest/person/discrete

Общие параметры для всех API сервисов

13 ноября 2020 года. Опубликовано в разделах: Азбука терминов. 10015

Что значит API

Простейшей аналогией использования API будет процесс работы на калькуляторе для сложных вычислений. Допустим, у вас есть задача, вы можете понимать её суть, строить уравнения и графики, но не умеете совершать арифметические действия с цифрами. Рядом с вами лежит калькулятор, умеющий делать эти операции с легкостью. Вы не знаете, что происходит внутри вычислительной машины, да и знать это не обязательно. Вы отдаёте информацию в одном виде, а получаете в другом, нужном для ваших целей.

По такому принципу работает любое API. Вам все равно, как программа получает ответ, какой путь проходит запрос внутри неё, как производятся вычисления. Вы уверены только в одном – в ответ будет выдана стандартизированная информация об успехе операции или её ошибке.

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

Плюсы:

  • Экономия на разработке своего интерфейса.
  • Нет необходимости разбираться в нюансах вопроса.
  • API разрабатывают профессионалы и учитывают все факторы внутренних процессов, о которых вы можете не знать, создавая свое решение.
  • Позволяет общаться с закрытыми через другие протоколы сервисами.

Минусы:

  • В случае обновления целевого сервиса, API не всегда мгновенно получает полный функционал.
  • Вы не можете отловить ошибки и не знаете, как проходит процесс в чужом коде.
  • Не всегда API даёт максимально оптимизированный результат по времени, так как предназначено для обработки общих случаев, а не частных.

Примеры API

API интеграция – это процесс подключения приложения к внешнему интерфейсу данных. Работа с API начинается с изучения документации и используемых протоколов, а далее непосредственной интеграции вашей программы к интерфейсу. Рассмотрим самые популярные сервисы, имеющие собственное API.

VKAPI

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

После слэша идёт наименование используемого API-метода и передаются GET-параметры запроса. Ответ так же приходит по HTTPS в формате JSON.

TELEGRAM BOT API

Одно из самых популярных API. С его помощью осуществляется контроль ботов в мессенджере Telegram. После создания бота через @botfather и получения необходимых ключей доступа, вы можете начать взаимодействие с внутренним интерфейсом.

Где вместо bot0000000 ставится уникальный идентификатор вашего бота, а token выражает секретный ключ.

Запросы посылаются через HTTPS соединения, название метода указывается через слэш к основному адресу. Ответ приходит в формате JSON.

OPEN WEATHER MAP API

Зачастую бывает необходимо получить информацию о погоде, не задействуя сторонние виджеты и платные приложения. На помощь приходит сервис OpenWeatherMap с открытым и бесплатным API. После регистрации и получения идентификационных данных вы можете отправлять с серверных скриптов запросы на погоду по всему миру. В ответ на ID города ресурс возвращает максимально подробную информацию о текущей погоде и дает прогноз на ближайшее время.

Формат работа: HTTP передача по api.openweathermap.org/data/2.5/weather? >

GOOGLE MAPS API

Что может быть приятнее, чем интерактивная карта мира на сайте? Особенно, если это не шаблонная вставка из Google Maps, а ваша персональная редакция популярной карты с личными кластерами маркеров. Карта будет взаимодействовать с другими скриптами на сайте, посылая информацию о кликах и координатах.

Подобные возможности предлагает JavaScript API Google Maps. Модуль полностью скриптовой и работает на стороне браузера, поэтому HTTP-запросы из PHP и формирование заголовков на стороне сервера, как было в других API, нам не нужно.

Например, выставление метки на карте будет выглядеть так:

var mark = new google.maps.Marker( <
position: myPOS,
map: map,
title:»Hello!»
>);

Для чего нужно и чем полезно использование API

Полезных функций довольно много.

Первый аспект

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

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

Второй аспект

Если вы владелец сложных вычислительных мощностей, популярного сервиса или хранилища данных для открытого или полуприватного доступа, то хорошим ходом будет поднять собственное API. Что это даст:

  • Большой поток клиентов.
  • Упрощенный доступ к вашим услугам для партнеров.
  • Удобство статистического анализа использования сервиса.

Третий аспект

Почти тот же, что и второй. Но без необходимости реализовывать API для открытого доступа. Если у вас есть портал, и вы хотите создать под него мобильное приложение на Android/IOS, то переписать систему под единое API – лучшее решение. Вся структура данных систематизируется. Сайт и приложение будут работать через единые каналы данных.

– Только качественный трафик из Яндекса и Google
– Понятная отчетность о работе и о планах работ
– Полная прозрачность работ

Общие параметры для всех API сервисов

API (application programming interface) — это набор готовых классов, функций, процедур, структур и констант. Вся эта информация предоставляется самим приложением (или операционной системой). При этом пользователю не обязательно понимать, что это API технология обеспечивает взаимодействие модулей. Цель предоставленной информации – использование этих данных при взаимодействии с внешними программами.

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

В общем случае данный механизм применяется с целью объединения работы различных приложений в единую систему. Это достаточно удобно для исполнителей. Ведь в таком случае к другому приложению можно обращаться как к «черному ящику». При этом не имеет значения его внутренний механизм – программист может вообще не знать, что такое API.

Функции API

В процессе работы элементы механизма API организуют многоуровневую иерархию. При этом подчиненные компоненты также получают подобную структуру. Внутри стандартной сетевой модели OSI выделяют как минимум 7 внутренних уровней. Они классифицируются от физического уровня трансляции бит до приложений, таких как протоколы HTTP и IMAP. Таким образом API верхнего использует функциональность нижнего.

Одним из важных компонентов организации информации при описании API являются библиотеки функций и классов. В их состав входят описания сигнатур и семантики. Здесь API функции – это просто часть механизма интерфейса.

В этом случае сигнатура выступает как часть общего объявления функции. С ее помощью выполняется идентификация элемента. В различных языках написания программ она представлена разным способом. Тем самым определяется возможностями ее перезагрузки.

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

Эти компоненты дают возможность компилятору опознать функцию в языке C++. В тех случаях, когда она является методом определенного класса, ее сигнатура включается в имя этого класса.

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

Типы API

Классификация программных интерфейсов тесно связана с назначением и возможностями приложений, которые через них управляются. Фактически при работе сложной системы часто существуют альтернативные API, позволяющие решить такие же задачи другими средствами.

В отдельные группы выделяют интерфейсы управления графическими компонентами программных модулей (API графических интерфейсов wxWidgets, Qt, GTK и т. п.), операционными системами (Amiga ROM Kernel, Cocoa, Linux Kernel APIruen, OS/2 API, POSIX, Windows API), звуковые (DirectMusic/DirectSound, OpenAL), оконные интерфейсы и так далее. Здесь их разделение определяется уровнем приложения в иерархии и функциональностью. Пользователи компьютерных игр обычно не подозревают, что это графический API обеспечивает им такую быструю отрисовку картинки и поразительную яркость изображений.

К глобальным API часто относят интерфейсы отдельных языков программирования. Но с их помощью можно управлять решением вполне конкретных и локальных задач. Все зависит от реализации определенного алгоритма.

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

  1. Трудности портирования кода программы при переходе от одной API к другой. Они часто появляются при переносе модулей в другие операционные системы.
  2. Снижения объема функциональности интерфейса при переходе к управлению с более низкого уровня на высокий. В этом случае облегчается выполнение строго определенного класса задач. При этом возможности доступа к элементам управления другими регуляторами теряются. Ведь более низкий уровень позволяет легко управлять базовыми компонентами программы.

API вебмастеров / поисковых систем

Для вебмастеров и программистов особенно важны Web API. Такие системы управления включают в себя комплект HTTP-запросов. В результате получения таких запросов модуль генерирует строго определенную структуру HTTP-ответов. Для транспортировки информации между ними принято использовать форматы XML или JSON.

Фактически в этом случае название Web API будет синонимом обозначения веб-службы. Иными словами, это определенные программные системы со своими интерфейсами. Для получения конкретного доступа к ним используется идентификация в сети по веб-адресу. Например, при передаче данный на сервер применяется серверный API.

В случае построения программных систем на основе сервис-ориентированной архитектуры именно веб-служба является уровнем формирования модулей.

Для обычных пользователей такие службы являются синонимами абсолютно обычных решений в Интернете. Это может быть почта, поисковая система, сервис хранения файлов, социальных закладок и так далее. В случае необходимости тестирования веб-службы на больших объемах разнообразных данных соответствующий API testing предоставляет механизм для такой объемной работы.

При правильной организации любой клиент может использовать такие службы вне зависимости от типа компьютера, вида браузера и места своего нахождения в сети.

Примером использования в рекламе является API Яндекс.Директа. На его базе разработчики создают модули для управления рекламными кампаниями. При обращении к системам продвижения сайтов для повышения параметров SEO API предоставляет механизмы информационного взаимодействия.

Обычно порядок работы интерфейса стараются передать в его названии. Мы можем не найти в поиске, что такое syngestureapisampleapp application. Но из названия понятно, что это пример работы интерфейса для единичного пользователя.

При этом нужно учитывать изменения в интерфейсах, произошедшие после массового внедрения стандартов Web 2.0. В результате был выполнен переход протокола обмена структурированными данными в распределенной вычислительной среде SOAP (от англ. Simple Object Access Protocol — простой протокол доступа к объектам) к архитектурному стилю взаимодействия компонентов распределенного приложения в сети REST (сокр. от англ. Representational State Transfer — «передача состояния представления»). Для многих веб-служб, в число которых входят поисковые системы и интернет-магазины, данный переход привел к упрощению архитектуры и ускорению выполнения задач. Правильная организация информационных потоков приводит к тому, что API сайта предоставляет широкие возможности автоматизации последнего.

При этом отдельные компоненты REST функционируют примерно таким же образом, как взаимодействуют между собой серверы и клиенты в Интернете. Хотя работа систем на архитектуре REST до сих пор не имеет единого стандарта, большинство RESTful-реализаций используют конкретные стандарты, такие как HTTP, URL, JSON и XML. Здесь особенно важно, что открытый API – это возможность дополнения и расширения системы взаимодействия.

Илон Маск рекомендует:  Оформление элементов HTML при помощи CSS

Что такое API и как интегрировать свой сайт с SendPulse

API позволяет сервисам и приложениям быстро и точно обмениваться информацией. Для маркетологов API это еще и возможность выбирать самое подходящее сочетание платформ и не опасаться сложностей с совместимостью форматов разных систем.

Рекомендуем показать эту статью разработчику, который будет настраивать передачу данных. В ней мы расскажем как использовать API email сервиса SendPulse, а также на примере покажем, как создать новостную рассылку и получить по ней статистику.

Что такое API

API расшифровывается как Application Programming Interface, что в переводе означает «интерфейс программирования приложений». API — это интерфейс, в котором приложения взаимодействуют между собой, выполняя общую задачу.

API создан для передачи данных между приложениями и сервисами. Поэтому он не имеет привычной панели с кнопками, в отличие от интерфейсов, созданных для пользователей программ. API представляет собой набор готовых классов, функций, процедур, структур и констант.

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

Чем API может помочь маркетологу

Маркетологам приходится проявлять гибкость в получении данных. Они собирают информацию из разных каналов, а те часто не предлагают привычный интерфейс. При передаче информации через API из одной системы в другую не важны интерфейсы этих систем. Главное, что обе стороны признают общие параметры запросов и ответов. Так информация передается быстро. И это важно для задач, требующих точности и оперативности.

Чтобы понять насколько маркетологу будет полезен API того или иного сервиса, необходимо выяснить, какие данные доступны по его API и как их получить. Попросите веб-разработчика посмотреть на интересующий вас API и обсудите с ним возможности интеграции.

Что можно сделать с помощью API в SendPulse

По API SendPulse совершают операции с адресными книгами и отправителями, кампаниями и шаблонами писем, работают с черным списком, проверяют баланс пользователя и получают информацию о рассылке.

Полная документация по API SendPulse находится на нашем сайте. В ней описаны требования для разработчиков по созданию интеграции.

Как использовать сервис SendPulse c применением API

Для тестирования и иллюстраций API в этой статье мы использовали Postman, инструмент для тестирования API. Данная программа доступна для пользователей Mac, Windows и Linux и не требует изучения языков программирования. Программа работает в режимах запуска, тестирования, документации и отслеживания. Вы можете пользоваться любым похожим приложением.

Сейчас мы рассмотрим пример того, как создать новостную рассылку и получить по ней статистику через API.

1. Авторизируемся в сервисе

Для этого получаем токен-ключ авторизации, используя метод из документации SendPulse. Возьмите значения API ID и API Secret из настроек вашего аккаунта SendPulse.

Значения API ID и API Secret из настроек аккаунта в SendPulse

Отправьте по API запрос на получение токена с этими значениями. В ответе сервиса будет предоставлен access token и указан его тип.

Ответ сервиса SendPulse с указанием access token и его типа

Этот токен понадобится для подписи каждого запроса по API. Учтите: после генерации токен действует час, потом придется обновить его — повторить первый шаг. Также в настройках аккаунта обновляйте значения API ID и Secret в целях безопасности. После этого тоже нужно сгенерировать новый токен.

2. Создаем адресную книгу

3. Получаем ID адресной книги

Используйте метод API для получения подробной информации по доступным адресным книгам. Важно сохранить значения ID, они нужны для идентификации списков получателей в дальнейших операциях.

Значения ID адресных книг в ответе API email сервиса SendPulse

4. Загружаем адреса в адресную книгу

При добавлении адресов в адресную книгу передаются и переменные — в данном случае это переменная <> со значением <>.


Добавление через API email адресов в адресную книгу

5. Загружаем шаблон письма

Если у вас уже есть шаблон письма рассылки, загрузите его в сервис, используя метод описанный в документации SendPulse.

Загрузка шаблона письма по API email сервиса SendPulse

Перед тем, как создать рассылку, определите ID загруженного шаблона. Получив список всех шаблонов, найдите ID нужного вам шаблона по имени.

ID загруженного шаблона в ответе API email сервиса SendPulse

Если готового шаблона у вас нет, создайте его в блочном редакторе SendPulse.

6. Создаем рассылку по адресной книге

Вместо параметра «body» подставьте параметр «template_id» со значением из предыдущего шага.

Передача значения параметра «template_id» по API сервиса SendPulse

7. Получаем информацию об отправленной кампании

Для маркетолога важно знать данные о статусе кампании. По API email сервиса SendPulse можно получить информацию по рассылке. На иллюстрации ниже мы видим данные о кампании: имя и адрес отправителя, тему и содержимое письма, количество писем в рассылке, статус и дату отправки.

Информация об отправленной кампании, полученная по API email сервиса SendPulse

Благодаря применению разных методов API мы создали рассылку по шаблону пользователя и получили по ней информацию.

Подробную аналитику по вашим email рассылкам удобно просматривать непосредственно в аккаунте SendPulse.

8. Смотрим как письмо выглядит в ящике получателя

Как видно на примере ниже, в хедере письма отображается имя подписчика, которое мы передали с помощью переменной <>, когда добавляли адреса получателей в адресную книгу.

Значение переменной передалось при добавлении контакта в адресную книгу по API email сервиса SendPulse

9. Если нужно отправить авторассылку

После пятого шага, где вы добавляете готовый шаблон письма, можно отправить подписчикам цепочку авторассылки. Для старта цепочки возьмем дату. Например, годовщину первой покупки, а первым элементом цепочки укажем email со спецпредложением.

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

Цепочка авторассылки в Automation 360 от SendPulse

Таким образом вы можете настроить передачу данных о действиях подписчиков с рассылкой и передать результаты в вашу систему. Эти результаты пригодятся вам для дальнейшей работы с клиентами.

Что в итоге

API упрощает сложные операции между системами. Не нужно отдельно работать с большим объемом данных для каждой системы, потому что API позволяет им взаимодействовать и облегчает работу маркетолога. Покажите эту статью веб-разработчику и приступайте к интеграции SendPulse со своим проектом через API.

API для всех и каждого: создаем мощный парсер веб-сайтов без единой строки кода

Содержание статьи

Часто возникает задача периодически парсить какой-нибудь сайт на наличие новой информации. Например, если ты пишешь агрегатор контента с новостного сайта или форума, в котором нет поддержки RSS. Проще всего написать скрепер на Питоне и разобрать полученный HTML через beautifulsoup или регулярками. Однако есть более элегантный способ — самому сделать недостающие API для сайта и получать ответы в привычном JSON, как будто бы у сайта есть нативный API.

Не будем далеко ходить за примером и напишем парсер контента с «Хакера». Как ты знаешь, сайт нашего журнала сейчас не предоставляет никакого API для программного получения статей, кроме RSS. Однако RSS не всегда удобен, да и выдает далеко не всю нужную информацию. Исправим это!

Постановка задачи

Итак, наша задача: сделать API вида GET /posts , который бы отдавал десять последних статей с «Хакера» в JSON. Также нам нужно иметь возможность задавать сдвиг, то есть раз за разом получать следующие десять постов.

Ответ должен быть таким:

Также нужно иметь возможность получать следующие десять постов — со второй страницы, третьей и так далее. Это делается через GET-параметр вида GET /posts?page=2 . Если page в запросе не указан, считаем его равным 1 и отдаем посты с первой страницы «Хакера». В общем, задача ясна, переходим к решению.

Фреймворк для веба

WrapAPI — это довольно новый (пара месяцев от роду) сервис для построения мощных кастомных парсеров веба и предоставления к ним доступа по API. Не пугайся, если ничего не понял, сейчас поясню на пальцах. Работает так:

  1. Указываешь WrapAPI страницу, которую нужно парсить (в нашем случае главную «Хакера» — https://xakep.ru/).
  2. Говоришь, с какими параметрами обращаться к серверу, каким HTTP-методом (GET или POST), какие query-параметры передавать, какие POST-параметры в body, куки, хедеры. Короче, все, что нужно, чтобы сервер вернул тебе нормальную страничку и ничего не заподозрил.
  3. Указываешь WrapAPI, где на полученной странице ценный контент, который надо вытащить, в каком виде его представлять.
  4. Получаешь готовый URL для API вида GET /posts , который вернет тебе все выдранные с главной «Хакера» посты в удобном JSON!

Немного о приватности запросов

Ты наверняка уже задумался о том, насколько безопасно использовать чужой сервис и передавать ему параметры своих запросов с приватными данными. Тем более что по умолчанию для каждого нового API-проекта будет создаваться публичный репозиторий и запускать API из него сможет любой желающий. Не все так плохо:

  1. Каждый API-репозиторий (а соответственно, и все API-запросы в нем) можно сделать приватным. Они не будут показываться в общем списке уже созданных API на платформе WrapAPI. Просто выбери достаточно сложное имя репозитория, и шанс, что на него кто-то забредет случайно, сведется к минимуму.
  2. Любой запрос к WrapAPI требует специального токена, который нужно получить в своей учетке WrapAPI. То есть просто так узнать URL к твоему репозиторию и таскать через него данные не получится. Токены подразделяются на два типа: серверные и клиентские, для использования прямо на веб-страничке через JavaScript. Для последних нужно указать домен, с которого будут поступать запросы.
  3. Ну и наконец, в скором времени разработчик обещает выпустить self-hosted версию WrapAPI, которую ты сможешь поставить на свой сервер и забыть о проблеме утечек данных (конечно, при условии, что в коде WrapAPI не будет бэкдоров).

Приготовления

Несколько простых шагов перед началом.

  1. Идем на сайт WrapAPI, создаем новую учетку и логинимся в нее.
  2. Устанавливаем расширение для Chrome (подойдет любой Chromium-based браузер), открываем консоль разработчика и видим новую вкладку WrapAPI .
  3. Переходим на нее и логинимся.

Это расширение нам понадобится для того, чтобы перехватывать запросы, которые мы собираемся эмулировать, и быстро направлять их в WrapAPI для дальнейшей работы. По логике работы это расширение очень похоже на связку Burp Proxy + Burp Intruder.

Для работы с WrapAPI нужно повторно авторизоваться еще и в расширении в консоли разработчика Chrome

Отлавливаем запросы

Теперь нужно указать WrapAPI, какой HTTP-запрос мы будем использовать для построения нашего API. Идем на сайт «Хакера» и открываем консоль разработчика, переключившись на вкладку WrapAPI.

Для получения постов я предлагаю использовать запрос пагинации, он доступен без авторизации и может отдавать по десять постов для любой страницы «Хакера», возвращая HTML в объекте JSON (см. ниже).

Запросы, которые генерятся по нажатию на ссылки пагинатора, будем использовать как образец

Чтобы WrapAPI начал перехватывать запросы, нажми Start capturing requests и после этого выполни целевой запрос (на пагинацию). Плагин поймает POST-запрос к странице https://xakep.ru/wp-admin/admin-ajax.php с кучей form/urlencoded-параметров в теле, в том числе и номером страницы. Ответом на запрос будет JSON-объект с параметром content , содержащий закешированный HTML-код с новыми постами. Собственно, этот блок и нужно парсить WrapAPI.

Запрос пойман, сохраняем его на сервер WrapAPI

Конфигурируем WrapAPI

После того как ты выбрал нужное имя для твоего репозитория (я взял test001 и endpoint posts ) и сохранил его на сервер WrapAPI через расширение для Chrome, иди на сайт WrapAPI и открывай репозиторий. Самое время настраивать наш API.

Обзор нашего будущего API

Переходи на вкладку Inputs and request. Здесь нам понадобится указать, с какими параметрами WrapAPI должен парсить запрашиваемую страницу, чтобы сервер отдал ему валидный ответ.

Конфигурируем входные параметры запроса

Аккуратно перебей все параметры из пойманной WrapAPI полезной нагрузки (POST body payload) в поле слева. Для всех параметров, кроме paginated , выставь тип Constant . Это означает, что в запросы к серверу будут поставляться предопределенные значения, управлять которыми мы не сможем (нам это и не нужно). А вот для paginated выставляй Variable API , указав имя page . Это позволит нам потом обращаться к нашему API по URL вида GET /posts?page=5 (с query-параметром page ), а на сервер уже будет уходить полноценный POST со всеми перечисленными параметрами.

Заголовки запроса ниже можно не трогать, я использовал стандартные из Chromium. Если парсишь не «Хакер», а данные с какого-нибудь закрытого сервера, можешь подставить туда нужные куки, хедеры, basic-auth и все, что нужно. Одним словом, ты сможешь настроить свой запрос так, чтобы сервер безо всяких подозрений отдал тебе контент.

Выставляем необходимые POST-параметры в формате form/urlencoded, чтобы наш запрос отработал правильно

Учим WrapAPI недостающим фичам

Теперь нужно указать WrapAPI, как обрабатывать полученный результат и в каком виде его представлять. Переходи на следующую вкладку — Outputs and response.

Продолжение доступно только участникам

Вариант 1. Присоединись к сообществу «Xakep.ru», чтобы читать все материалы на сайте

Членство в сообществе в течение указанного срока откроет тебе доступ ко ВСЕМ материалам «Хакера», увеличит личную накопительную скидку и позволит накапливать профессиональный рейтинг Xakep Score! Подробнее

Как правильно работать с REST API

Коротко обо мне

Меня зовут Зел, я разработчик-фрилансер из Сингапура. В свободное от работы время я люблю разбираться в коде и попутно публиковать в своем блоге те интересности, которые я обнаружил или изучил.

Вступление

Скорее всего вам уже приходилось слышать о таком термине, как REST API, особенно если вы сталкивались с необходимостью получения данных из другого источника (такого как Twitter или Github). Но что же все-таки это такое? Что мы можем с этим делать и как мы можем это использовать?

В данной статье вы узнаете все о REST API для того, чтобы работать с ними и читать связанную с ними документацию.

Что же такое REST API?

Давайте представим, что вы пытаетесь найти фильмы о Бэтмене на YouTube. Вы открываете сайт, вбиваете в форму поиска слово «Бэтмен», жмакаете «Окей» и видите список фильмов о супергерое. Похожим образом работает и WEB API. Вы ищите что-то и получаете список результатов от запрашиваемого ресурса.

Дословно API расшифровывается как Application Programming Interface. Это набор правил, позволяющий программам «общаться» друг с другом. Разработчик создает API на сервере и позволяет клиентам обращаться к нему.

REST – это архитектурный подход, определяющий, как API должны выглядеть. Читается как «Representational State Transfer». Этому набору правил и следует разработчик при создании своего приложения. Одно из этих правил гласит, что при обращении к определенному адресу, вы должны получать определенный набор данных (ресурс).

Каждый адрес маршрутом, пакет данных — запросом, в то время как результатирующий ресурс – ответом.

Анатомия запроса

Важно понимать структуру запроса:

  1. Маршрут отправки
  2. Тип метода
  3. Заголовки
  4. Тело (или данные)

Маршрут – это адрес, по которому отправляется ваш запрос. Его структура примерно следующая:

Root-endpoint — это точка приема запроса на стороне сервера (API). К примеру, конечная точка GitHub – https://api.github.com.

Путь определяет запрашиваемый ресурс. Это что-то вроде автоответчика, который просит вас нажать 1 для одного сервиса, 2 для другого и так далее.

Для понимания того, какие именно пути вам доступны, вам следует просмотреть документацию. К примеру, предположим, вы хотите получить список репозиториев для конкретного пользователя на Git. Согласно документации, вы можете использовать следующий путь для этого:

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

Последняя часть маршрута – это параметры запроса. Технически запросы не являются частью REST-архитектуры, но на практике сейчас все строится на них. Так что давайте поговорим о них более детально. Параметры запроса позволяют использовать в запросе наборы пар «ключ-значение». Они всегда начинаются знаком вопроса. Каждая пара параметров после чего разделяется амперсантом (что-то вроде этого):

Как только вы пытаетесь получить список репозиториев для пользователя, вы добавляете эти три опциональных параметра и после чего получаете следующий результат:

Если же вы желаете получить список моих недавно запушеных репозиториев, вам следует ввести следующее:

Итак, как же понять, что маршруты рабочие? Что ж, пришло время проверить их на практике!

Тестирование при помощи Curl

Вы моете отправить запрос при помощи любого языка программирования. JavaScript может использовать методы вроде Fetch API или JQuery`s Ajax Method. Руби использует другое. И так далее.

В этой статье я буду использовать такую утилитку, как Curl. Дело в том, что она указана в официальной документации для веб-сервисов. Если вы поймете, как использовать эту утилиту, вы поймете, как работать с API. После чего вы можете производить запросы любым удобным для вас языком.

Перед тем, как продолжить, вам следует убедится, что Curl установлен на вашей машине.

Ели же он не установлен, самое время установить. В таком случае вы получите ошибку «command not found».

Для того, чтобы использовать утилиту, необходимо ввести следующее (по примеру):

И как только вы подтверждаете ввод, вы получаете ответ (наподобие этого):

Чтобы получить список пользовательских репозиториев, вам следует изменить запрос по тому же принципу, который был оговорен ранее. К примеру, чтобы получить список моих репозиториев, вам следует ввести следующее:

Если же вы желаете включить параметры запросов, убедитесь, что вы их экранируете. Дело в том, что без экранирования знаки вопроса и равно расцениваются системой как спец. символы и выполнение команды произойдет с ошибкой.

Также попробуйте другие команды и произведите запросы! В результате вы получаете похожие ответы.

JSON

JSON – JavaScript Object Notation – общий формат для отправки и приема данных посредством REST API. Ответ, отправляемый Github, также содержится в формате JSON.

Содержание объекта этого формата примерно следующее:

Возвращаемся к анатомии запроса

Вы изучили, что запрос состоит из четырех частей:

  1. Маршрут отправки
  2. Тип метода
  3. Заголовки
  4. Тело (или данные)

Теперь же давайте попробуем разобраться с остальным.

Тип метода

Метод обозначает тип производимого запроса, де-факто он является спецификацией операции, которую должен произвести сервер. Всего существует пять типов запросов:

GET – используется для получения со стороны севера определенного ресурса. Если вы производите этот запрос, сервер ищет информацию и отправляет ее вам назад. По сути, он производит операцию чтения на сервере. Дефолтный тип запросов.

POST – нужен для создания определенного ресурса на сервере. Сервер создает в базе данных новую сущность и оповещает вас, был ли процесс создания успешным. По сути, это операция создания.

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

DELETE – как и следует из названия, удаляет указанную сущность из базы или сигнализирует об ошибке, если такой сущности в базе не было.

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

GET запрос в этом случае необходим, чтобы получить список всех репозиториев указанного пользователя. Также можно использовать curl:

Попробуйте отправить этот запрос. В качестве ответа вы получите требование об аутентификации.

Заголовки

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

Заголовки представляют из себя пары ключей-значений. Пример:

Также пример с использованием curl:

(Примечание: заголовок Content-Type в случае Github для работы не является обязательным. Это всего лишь пример использования заголовка в запросе, ничего более.)

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

Здесь звездочка относится к дополнительной информации, предоставленной посредством curl. > относится к заголовкам запроса, а

Application Programming Interface (API)

Интерфе́йс программи́рования приложе́ний (Application Programming Interface, API [эй‐пи‐ай]; по-русски чаще произносят [апи́]) — набор методов (функций), который программист может использовать для доступа к функциональности программного компонента (программы, модуля, библиотеки). API является важной абстракцией, описывающей функциональность «в чистом виде», безотносительно того, как реализована эта функциональность.

Содержание

API как средство интеграции приложений

API определяет функциональность, которую предоставляет программа (модуль, библиотека), при этом API позволяет абстрагироваться от того, как именно эта функциональность реализована.

Если программу (модуль, библиотеку) рассматривать как чёрный ящик, то API — это множество «ручек», которые доступны пользователю данного ящика, которые он может вертеть и дёргать.

Программные компоненты взаимодействуют друг с другом посредством API. При этом обычно компоненты образуют иерархию — высокоуровневые компоненты используют API низкоуровневых компонентов, а те, в свою очередь, используют API ещё более низкоуровневых компонентов.

По такому принципу построены протоколы передачи данных по Internet. Стандартный протокол Internet (сетевая модель OSI) содержит 7 уровней (от физического уровня передачи пакетов бит до уровня протоколов приложений, подобных протоколам HTTP и IMAP). Каждый уровень пользуется функциональностью предыдущего уровня передачи данных и, в свою очередь, предоставляет нужную функциональность следующему уровню.

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

API библиотеки функций и классов включает в себя описание сигнатур и семантики функций.

Application Programming Interface (API) программный интерфейс взаимодействия между системами, позволяющий:

  • Получать доступ к бизнес-сервисам предприятия
  • Обмениваться информацией между системами и приложениями
  • Упростить взаимодействие между компаниями, партнерами, разработчиками и клиентами

Open API стратегия

API стратегия включает в себя:

  • Разработку бизнес-продуктов на основе существующих API
  • Предоставление внутренних сервисов разработчикам
  • Модели монетизации API для построения мультиканального взаимодействия и повышения прибыли


Реализация концепции Open API помогает трансформировать бизнес, встраивать его в гибкую проектную экосистему игроков рынка, создавать условия для постоянной генерации новых идей и формирования дополнительной ценности при управлении массивами корпоративных данных.

Рынок интеграционных решений развивается в контексте эволюции API — от EDI и SOAP до Web 2.0, с которого началась эра публичных API. Число таких интерфейсов в ближайшие 3 года может вырасти более чем в 50 раза и достичь 1 миллиона. Это связано с мультиканальностью: каналы взаимодействия с клиентами должны меняться вместе с ними. Непрерывный рост количества потребителей и объема данных привел к появлению экономики API, помогающей на основе открытых интерфейсов создавать инновационные бизнес-модели использования корпоративных активов и сервисов.

Илон Маск рекомендует:  Что такое код ifx_close

Сигнатура функции

Сигнатура функции — часть общего объявления функции, позволяющая средствам трансляции идентифицировать функцию среди других. В различных языках программирования существуют разные представления о сигнатуре функции, что также тесно связано с возможностями перегрузки функции в этих языках.

Иногда различают сигнатуру вызова и сигнатуру реализации функции. Сигнатура вызова обычно составляется по синтаксической конструкции вызова функции с учётом сигнатуры области видимости данной функции, имени функции, последовательности фактических типов аргументов в вызове и типе результата. В сигнатуре реализации обычно участвуют некоторые элементы из синтаксической конструкции объявления функции: спецификатор области видимости функции, её имя и последовательность формальных типов аргументов.

Например, в языке программирования Си++ простая функция однозначно опознаётся компилятором по её имени и последовательности типов её аргументов, что составляет сигнатуру функции в этом языке. Если функция является методом некоторого класса, то в сигнатуре будет учаcтвовать и имя класса.

В языке программирования Java сигнатуру метода составляет его имя и последовательность типов параметров; тип значения в сигнатуре не участвует.

Семантика функции

Семантика функции — это описание того, что данная функция делает. Семантика функции включает в себя описание того, что является результатом вычисления функции, как и от чего этот результат зависит. Обычно результат выполнения зависит только от значений аргументов функции, но в некоторых модулях есть понятие состояния. Тогда результат функции может зависеть от этого состояния, и, кроме того, результатом может стать изменение состояния. Логика этих зависимостей и изменений относится к семантике функции. Полным описанием семантики функций является исполняемый код функции или математическое определение функции.

API операционных систем. Проблемы, связанные с многообразием API

Практически все операционные системы (Unix, Windows, MacOS, и т. д.) имеют API, с помощью которого программисты могут создавать приложения для этой операционной системы. Главный API операционных систем — это множество системных вызовов.

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

С другой стороны, отличия в API различных операционных систем существенно затрудняют перенос приложений между платформами. Существуют различные методы обхода этой сложности — написание «промежуточных» API (API графических интерфейсов Qt, Gtk, и т. п.), написание библиотек, которые отображают системные вызовы одной ОС в системные вызовы другой ОС (такие среды исполнения, как Wine, cygwin, и т. п.), введение стандартов кодирования в языках программирования (например, стандартная библиотека [[Си языка C), написания интерпретируемых языков, реализуемых на разных платформах (sh, perl, php, tcl, Java, и т. д.)

Также необходимо отметить, что в распоряжении программиста часто находится несколько различных API, позволяющих добиться одного и того же результата. При этом каждый API обычно реализован с использованием API программных компонент более низкого уровня абстракции.

Например: для того, чтобы увидеть в браузере строчку «Hello, world!» достаточно лишь создать HTML-документ с минимальным заголовком, и простейшим телом, содержащим данную строку. Что произойдёт, когда браузер откроет этот документ? Программа-браузер передаст имя файла (или уже открытый дескриптор файла) библиотеке, обрабатывающей HTML-документы, та, в свою очередь, при помощи API операционной системы прочитает этот файл, и разберётся в его устройстве, повызывает через API библиотеки стандартных графических примитивов операции типа «очистить окошко», «написать выбранным шрифтом Hello, world!», при этих операциях библиотека графических примитивов обратится к библиотеке оконного интерфейса с соответствующими запросами, уже эта библиотека обратится к API операционной системы с запросами вида «а положи-ка мне в буфер видеокарты вот это».

При этом практически на каждом из уровней реально существует несколько возможных альтернативных API. Например: мы могли бы писать исходный документ не на HTML, а на LaTeX, для отображения могли бы использовать любой браузер. Различные браузеры, вообще говоря, используют различные HTML-библиотеки, и, кроме того, всё это может быть (вообще говоря) собрано с использованием различных библиотек примитивов и на различных операционных системах.

Основными сложностями существующих многоуровневых систем API, таким образом, являются:

  • Сложность портирования программного кода с одной системы API на другую (например, при смене ОС);
  • Потеря функциональности при переходе с более низкого уровня на более высокий. Грубо говоря, каждый «слой» API создаётся для облегчения выполнения некоторого стандартного набора операций. Но при этом реально затрудняется, либо становится принципиально невозможным выполнение некоторых других операций, которые предоставляет более низкий уровень API.

Основные типы API

  • Доступ к API предоставляется только внутренним разработчикам
  • Приложения нацелены на сотрудников предприятия
  • Консистентность разработки
  • Снижение затрат
  • Повышение эффективности разработки
  • API доступны только ограниченному набору бизнес-партнеров
  • Приложения предназначены для конечных потребителей и для бизнес-пользователей
  • Автоматизация процесса разработки
  • Развитие партнерских отношений
  • Оптимизация процесса взаимодействия с партнерами

Доступ предоставляется любому внешнему разработчику Приложения нацелены на конечных пользователей

  • Разработка новых сервисов
  • Развитие экосистемы
  • Мультиканальное взаимодействие

Где проектировать Restful API?

Это фреймоворки для проектировния API. По сути предоставляют свой DSL для описания и ДОКУМЕНТИРОВАНИЯ (!) API. К большинству из них идут инструменты по генерации читабельных доков и всякие mock-инструменты и генераторы клиентов-загрушек и сервисов-заглушек (для тестирования сервисов и клиентов соответственно). Вот например тулзы для Сваггера: swagger.io/swagger-codegen :

The Swagger codegen project allows generation of both client libraries and server stubs from a Swagger definition.

vREST — более комплексный продукт, включающий автоматизацию тестирования, есть платные возможности.
Mashape — большой продукт для предоставления API, используется многими крупными компаниями (напр., Близзы его юзают).

P.S. Есть еще различные модели гипермедийных API (JSON-LD, HAL, Siren, и т.д.), но это пока не очень популярные вещи, поэтому если не готовы быть одним из первопроходцев, лучше попробуйте их потом, когда наберут популярность (если наберут).

Не пользовался и не разбираюсь в теме. Не попадалась вам обзорная информацяи, что это и зачем нужно?

Вы порекомендовали RAML. Там есть туториалы, как описывать с его помощью апи. А зачем? Я могу и так описать свои апи детально, без посторонних интсрументов. Под него есть генераторы кода?

pygame
> Под него есть генераторы кода?
Пользовался генератором под ASP.Net WebAPI, вполне выполняет свою функцию: в студию ставится Extension, в webapi проект добавляется raml-файл, по нему генерится код контроллеров на шарпе, содержащий методы и атрибуты с маршрутами из вашего API. Эти методы-заглушки вызывают парные им методы, где вы уже пишете конкретную реализацию.

Почему это удобно? Потому что RAML-файл становится основным документом-договором по API. Т.к. из него генерится код, то при изменении его описания при сборке webapi-проекта сразу же всплывают все проблемы, связанные с изменением «договора», например нереализованные экшены контроллера, или изменившийся список параметров. Лично я очень люблю, когда инструмент мне гарантированно скажет хотя бы о некоторых проблемах (поэтому и пользуюсь в основном компилируемыми языками). При этом, тут же в RAML файле вы пишете описание экшенов и передаваемых в обе стороны параметров и данных, можно даже JSON-схему для запросов и ответов указывать. То есть по тому же самому RAML-файлу вы можете сгенерить и доки для чтения человеком.

Поэтому вывод очень простой: эти инструменты хороши, потому что а) они решают важнейшую проблему всей информатики — синхронизацию информации об одном и том же объекте в нескольких местах. Вместо рукописных доков и кода, за соответствием которых надо следить, у вас остается ОДИН авторитетный источник и для человеческой документации, и для «компиляторской» документации в виде кода для клиента и сервера. б) они решают проблему стандартизации. Очевидно, что для текстового человеческого описания без всякого синтаксиса невозможно сгенерить,например, тестовый сервис-заглушку, или клиент-заглушку. в) добавляя стандартизацию, они добавляют семантику, в том числе и в документацию. Для тех же целей создаются и другие форматы, например DocBook. Только в докбуке вы оперируете понятиями «параграф», «глава» и «фрагмент кода», а тут сущности еще более высокоуровневые: «описание экшена», «описание ресурса» и т.д.

Разумеется, возникает стандартная дилемма: усложнить процесс разработки и пользоваться подобными тулзами, или не усложнять, и писать все на Markdown и не заморачиваться. Это каждый решает сам в каждом отдельном проекте.

Полезные API сервисы

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

Хорошо, давайте же перейдем к обзору подобных сервисов.

Платежные системы

API Яндекс.Кошелька — позволяет частным лицам использовать возможности сервиса Яндекс.Денег.

API Яндекс.Кассы — инструмент для интеграции с Яндекс.Кассой, который позволяет принимать платежи, делать возвраты, узнавать о статусе операций и многое другое.

API WebMoney — различные варианты приема платежей и управления средствами.

API PayPal — международная система для осуществления платежей и денежных переводов с банковского счета или карточки, подключенных к системе.

API QIWI Кошелька позволяет автоматизировать получение информации о вашем счёте в сервисе QIWI Кошелек и проводить операции с его помощью.

API PayMaster — техническая информация, которая поможет Вам настроить интерфейс приема платежей.

API Единая касса — универсальная система приема платежей на сайте (118 способов оплаты).

API Interkassa — представляет программный интерфейс, который позволяет любому мерчанту автоматически принимать платежи в режиме онлайн.

API ROBOKASSA — сервис, позволяющий клиентам принимать платежи от покупателей.

API Тинькофф Оплата — представляет платежи для вашего бизнеса.

API RBKmoney — является базовой и единственной точкой взаимодействия с платежной платформой.

API Сбербанк Эквайринг — приём к оплате платёжных карт в качестве средства оплаты товара, работ и услуг.

Погода

API OpenWeatherMap — бесплатное API для получения сведений о погодных условиях.

API Яндекс.Погода — позволяет получать погодные данные в автоматизированном режиме (бесплатно лимит запросов 50 в сутки).

API Gismeteo — сервис, который предоставляет прогноз погоды в городах России и мира.

API IP Geolocation — бесплатный сервис для некоммерческого использования без ключа API. Легко интегрируется и поддерживает JSON, XML, CSV, Newline и PHP .

API IPAPI — простой и быстрый программный поиск IP-адреса для вашего веб-сайта и мобильного приложения.

API Ipify — простое публичное API для IP-адреса.

Социальные сети

API instagram — популярная социальная сеть, позволяющая хранить фотографии пользователей и делиться ими.

API MediaWiki — веб-служба, обеспечивающая доступ к таким функциям вики, как аутентификация, операции над страницами и поиск по вики.

API Вконтакте — документация по авторизации на базе протокола OAuth, стандартная схема формирования запросов, распространение контента ВКонтакте и другое.

API Facebook — обширная документация по взаимодействию с сервисами Facebook.

API Одноклассники — официальная документация по взаимодействию с социальной сетью Одноклассники.

Страны

API REST Countries — получите информацию о странах через RESTful API.

Данная статья постоянно пополняется новыми полезными API-сервисами. Если Вы знакомы с интересным сервисом, будем рады любым комментариям.

До новых встреч.

Если вы нашли ошибку, пожалуйста, выделите фрагмент текста и нажмите Ctrl+Enter.

API для обслуживающих организаций

Версия API 1.0.3

API службы поддержки предоставляет возможность работы через SOAP и REST веб-сервисы. Примеры использования веб-сервисов показаны в конфигурации 1C:Библиотека интеграции со службой поддержки . В ней реализована подсистема для встраивания в конфигурации партнеров. Подсистема включает в себя набор команд, форм и модулей, необходимых для встраивания пользовательского интерфейса службы поддержки в другие конфигурации. Библиотека интеграции предоставляет набор процедур и функций, облегчающих работу с API. Вызовы процедур и функций для работы с API будут рассмотрены в примерах.

Содержание

REST-сервис API-XML

Сервис используется для интеграции приложения 1С:Управление службой поддержки с другими приложениями. Примеры работы с веб-сервисом приведены в конфигурации 1С:Библиотека интеграции со службой поддержки . Ответы веб-сервиса формируются в формате XML. Также в формате XML нужно формировать запросы при отправке объектов на запись и изменение. Для упрощения работы, веб-сервис предоставляет модель описания фабрики объектов.
Пример использования в 1С:Предприятии:

SOAP-сервис API-SOAP

Сервис используется для интеграции приложения 1С:Управление службой поддержки с другими приложениями. Синхронная интеграция применяется для реализации пользовательского интерфейса и онлайн взаимодействия интегрированных приложений.

Операция execute

Обрабатывает переданный запрос и возвращает результат обработки.
Возвращаемое значение: Response

Параметр Тип Описание
request Request Содержит запрос на выполнение операции, например GetVersionRequest.

Пример вызова этой операции в 1С:Предприятии:

Тот же пример с использованием средств библиотеки:

Запросы к сервисам

Запросы к REST сервису

Получение версии сервиса REST

Получение модели описания для фабрики объектов REST

Модель описания может использоваться для создания, чтения и работы с объектами.
Запрос:

Получение данных авторизованного пользователя REST

Возвращает данные авторизованного пользователя.
Запрос:

Получение списка объектов REST

В качестве запроса передается имя класса.
Доступно для объектов всех классов-потомков от класса Object.
Шаблон запроса:

По умолчанию возвращается только ссылка. Можно определить состава выводимых колонок с помощью параметра columns.
В качестве выводимых колонок можно использовать все доступные поля класса, возможные для вывода в списке.
Доступно для объектов всех классов-потомков от класса Object.
Пример запроса:

Возможна установка отборов на получаемый список. Для этого нужно использовать параметр filter.
Фильтр можно накладывать на все доступные поля класса, возможные для вывода в списке.
Пример запроса:

Можно установить лимит количество получаемых записей. Для этого нужно использовать параметр limit.
Можно использовать параметры columns, filter и limit в одном запросе.
Для объектов, поддерживающих дополнительные реквизиты, можно осуществлять отбор, используя в качестве имени реквизита идентификатор дополнительного реквизита, например:

Получает список Абонентов с отбором по значению дополнительного реквизита.
В запросе можно использовать большие и маленькие буквы в именах классов и свойств.
Пример запроса:

Получение списка подчиненных объектов REST

Можно получать подчиненные объекты от основного объекта.
Шаблон получения подчиненных объектов:

Пример получения взаимодействий и файлов по обращению:

Доступно для предметов:

Доступно для подчиненных объектов

  • File — присоединенные файлы
  • Interaction — все типы взаимодействий по предмету
  • PhoneCall — телефонный звонок
  • ServiceUserComment — комментарий пользователя сервиса
  • IncomingEMail — входящее электронное письмо
  • OutgoingEMail — исходящее электронное письмо

Получение объекта REST

Доступно для всех объектов классов-потомков от класса Object.

Получение экземпляра нового объекта REST

Запрос доступен для:

Получение экземпляра нового подчиненного объекта REST

Доступно для предметов:

Доступно для подчиненных объектов:

  • ActualWork — запись о трудозатратах
  • PhoneCall — телефонный звонок
  • OutgoingEMail — исходящее электронное письмо
  • Order — поручение

Добавление объекта REST

Объект передается в теле запроса в формате XML. Объект должен соответствовать описанию класса в модели.
Шаблон запроса:

Запрос доступен для:

Для старта процесса «Поручение» нужно указать дополнительные действия при добавлении объекта:

Если дополнительное действие не будет указано, то процесс будет добавлен, но не будет стартован.

Добавление подчиненного объекта REST

Данные подчиненного объекта передаются в теле запроса в формате XML.
Шаблон запроса:

Пример добавления файлов к обращению:

Доступно для предметов:

Доступно для объектов:

  • IncidentComment — комментарий обращения
  • ArticleComment — комментарий карточки базы знаний
  • ActualWork — запись фактических трудозатрат
  • File — присоединенный файл

Обновление объекта REST

Объект передается в теле запроса.
Пример запроса:

Запрос доступен для:

  • Incident — обращения
  • Consultation — консультации
  • Suggestion — пожелание
  • PhoneCall — телефонный звонок
  • OutgoingEMail — исходящее электронное письмо
  • Order — поручение
  • Task — задача исполнителя

Для взаимодействий этот запрос доступен с действием Consider .
При выполнении такого запроса у взаимодействий устанавливается признак Рассмотрено.
При использовании параметра action тело запроса может не устанавливаться.
Пример запроса:

  • IncomingEMail — входящее электронное письмо
  • ServiceUserComment — комментарий пользователя
  • OutgoingEMail — исходящее электронное письмо
  • PhoneCall — телефонный звонок

Перенаправление объекта REST


Параметры перенаправления передаются в теле запроса.
Шаблон запроса:

Запрос доступен для объектов:

Принятие задачи к исполнению REST

Принятие задачи выполняется так же как и перенаправление.
В качестве исполнителя в теле запроса устанавливается текущий пользователь.
Примет запроса:

Выполнение задачи REST

Для выполнения задач используется отдельный запрос.
Шаблон запроса:

Комментарий выполнения задачи передается в теле запроса.
При выполнении задачи возможно указание дополнительных действий:

  • CompleteTask — выполнить задачу по умолчанию
  • ReturnOnСompletion — вернуть на доработку
  • CancelOrder — отменить поручение

Удаление объекта REST

Запрашивается тип объекта и уникальный идентификатор объекта.
Пример запроса:

Доступно для объектов:

Запросы к SOAP сервису

Получение версии сервиса SOAP

Версия сервиса помогает определить внешней системе доступную функциональность сервиса.
Для получения версии сервиса нужно отправить запрос класса GetVersionRequest. Возвращается ответ класса GetVersionResponse, содержащий номер версии сервиса. Пример использования:

Класс GetVersionRequest

Базовый класс: Request
Запрос для получения текущей версии веб-сервиса.

Класс GetVersionResponse

Базовый класс: Response
Ответ на запрос GetVersionResponse. Возвращает текущую версию веб-сервиса.

Свойство Тип Обязательное Описание
version string Да Номер версии web-сервиса. Строка вида 1.0.1.1

Получение данных авторизованного пользователя SOAP

Для получения данных авторизованного пользователя нужно отправить запрос класса GetCurrentUserRequest. Возвращается ответ класса GetCurrentUserResponse, содержащий данные текущего пользователя.
Пример использования:

Результат запроса кэшируется на время сеанса.

Класс GetCurrentUserRequest

Базовый класс: Request
Запрашивает данные авторизованного пользователя.

Класс GetCurrentUserResponse

Базовый класс: Response
Возвращается в результате выполнения запроса GetCurrentUserRequest. Содержит в теле значение авторизованного пользователя.

Свойство Тип Обязательное Описание
object Object Да Авторизованный пользователь

Получение списка объектов SOAP

Получение списка объектов выполняется с помощью запроса класса GetListRequest. В качестве параметров запросу передаются строка с типом объекта и условия, включающие, набор колонок и отборы. При удачном выполнении запроса возвращается объект класса GetListResponse, содержащий список объектов запрошенного типа с указанными колонками. В случае ошибки возвращается Error.
С помощью этого запроса можно получить списки всех типов объектов из производных классов класса Object.
Пример использования:

Класс GetListRequest

Базовый класс: Request
Запрашивает список объектов (элементов справочника, документов, бизнес-процессов, задач или значений перечисления), удовлетворяющих указанному условию.

Свойство Тип Обязательное Описание
query ListQuery Параметры запроса.
type string Да Указывает тип объектов, список которых нужно получить. Например, Incident.
Класс GetListResponse

Базовый класс: Response
Возвращается в результате успешной обработки запроса GetListRequest.

Свойство Тип Обязательное Список Описание
items ListItem Да Список объектов.
tooManyObjects boolean Признак того, что в выборке больше объектов, чем запрашивалось.
Свойства запроса
Класс ListQuery
Свойство Тип Обязательное Список Описание
columns string Да Имена свойств, которые нужно заполнить у запрошенных объектов.
filter ListFilter Да Набор условий отбора.
limit integer Предельное количество выбираемых объектов.
Класс ListFilter

Условие отбора для запроса GetListRequest.

Свойство Тип Обязательное Описание
comparisonOperator ComparisonOperator Оператор сравнения. Если не заполнено, то используется значение «=».
property string Да Имя поля для отбора.
value любой тип Да Значение поля отбора.
Класс ComparisonOperator

Оператор сравнения для указания сложных условий в условии ListFilter запроса GetListRequest.

  • = – равно
  • > – больше
  • = – больше или равно
  • – не равно
  • LIKE – подобно
  • IN – в
  • IN HIERARCHY – в иерархии
Свойства ответа

Каждый объект оборачивается в объект типа ListItem, содержащий сам объект, а также дополнительные свойства, для удобства отображения в списках и получения дочерних элементов.

Класс ListItem

Описывает элемент списка объектов.

Свойство Тип Обязательное Описание
canHaveChildren boolean Да Признак того, что данный объект может содержать дочерние (т.е. является веткой дерева).
isFolder boolean Да Признак того, что данный объект является группой.
object Object Да Объект УСП.
parentId ObjectId Указывает на объект, который является родительским для данного объекта в контексте списка объектов.

Получение списка подчиненных объектов SOAP

Получение списка подчиненных объектов, например взаимодействий, выполняется с помощью запроса класса GetSubListRequest. В качестве параметров запросу передаются ссылка на предмет взаимодействия и условия, включающие, набор колонок и отборы. При удачном выполнении запроса возвращается объект класса GetSubListResponse, содержащий список объектов запрошенного типа с указанными колонками. В случае ошибки возвращается Error.
Пример использования при получении взаимодействий:

При получении взаимодействий можно использовать имена типов взаимодействий, либо имя Interaction, для получения списка взаимодействий всех типов.
Пример получения списка файлов:

Класс GetSubListRequest

Базовый класс: Request
Запрашивает список объектов по предмету.
Доступно для предметов

Доступно для подчиненных объектов

  • File — присоединенные файлы
  • Interaction — все типы взаимодействий по предмету
  • PhoneCall — телефонный звонок
  • ServiceUserComment — комментарий пользователя сервиса
  • IncomingEMail — входящее электронное письмо
  • OutgoingEMail — исходящее электронное письмо
Свойство Тип Обязательное Список Описание
columns string Да Набор свойств объекта, которые необходимо заполнить. Если список пуст или не указан, то заполняются все свойства.
targetId ObjectId Да Ссылка на предмет:
  • Incident — обращение
  • Consultation — консультация
  • Problem — ошибка
  • Suggestion — пожелание
type string Да Тип объекта. При получении взаимодействий можно указать тип Interaction для получения взаимодействий всех типов.
Класс GetSubListResponse

Базовый класс: Response
Возвращается в результате успешной обработки запроса GetSubListRequest.

Свойство Тип Обязательное Список Описание
records Record Да Полученные записи.

Получение списка сведений по пользователям SOAP

Получение списка сведений по пользователям выполняется с помощью запроса GetServiceUserInfoListRequest. При удачном выполнении запроса возвращается объект класса GetServiceUserInfoListResponse, содержащий список сведений по пользователям сервиса. В случае ошибки возвращается Error.

Класс GetServiceUserInfoListRequest

Базовый класс: Request
Запрос для получения списка пользователей сервисов с дополнительной информацией. В параметрах можно указать частичные значения для поиска. Количество букв в строковых парамтрах не должно быть меньше 3.

Свойство Тип Обязательное Список Описание
applicationCode int Номер приложения
dynamicAttributes DynamicAttribute Да Параметры отборов по дополнительным реквизитам
serviceId ObjectId Да Ссылка на сервис
serviceUserEMail string Адрес электронной почты пользователя сервиса
serviceUserLogin string Логин пользователя сервиса
subscriberCode int Код абонента
Класс GetServiceUserInfoListResponse

Базовый класс: Response
Ответ на запрос получения списка пользователей с расширенной информацией. Содержит запрашиваемый список.

Свойство Тип Обязательное Список Описание
items ServiceUserInfoItem Да Элементы списка с расширенной информацией по пользователям сервиса

Получение объекта SOAP

Для получения объектов используется запрос класса GetRequest. В качестве параметров в запросе передаются список ссылок на требуемые объекты и набор колонок, которые требуется получить. В случае удачного выполнения запроса возвращается ответ класса GetResponse, содержащий требуемые объекты. В случае ошибки возвращается Error.
Пример использования:

Илон Маск рекомендует:  Функции в Delphi
Класс GetRequest

Базовый класс: Request
Получает массив указанных объектов.

Свойство Тип Обязательное Список Описание
columns string Да Массив имен свойств, которые должны быть заполнены. Если массив не указан или пустой, то заполняются все свойства.
objectIds ObjectId Да Ссылки на объекты.
Класс GetResponse

Базовый класс: Response
Возвращается в результате успешной обработки запроса GetRequest.

Свойство Тип Обязательное Список Описание
records Record Да Да Массив записей.

Получение экземпляра нового объекта SOAP

Можно получить экземпляр нового объекта с предварительно заполненными по умолчанию полями. Это удобно при создании новых объектов. Для получения экземпляра объекта отправляется запрос класса GetNewRequest. В качестве параметра в запросе передается строка с именем типа требуемого объекта. При успешном выполнении запроса возвращается ответ класса GetNewResponse, который содержит новый объект, заполненные по умолчанию. При возникновении ошибки возвращается Error.
Пример использования:

Класс GetNewRequest

Базовый класс: Request
Запрашивает новый объект указанного типа, заполненный значениями по умолчанию.
Доступно для объектов:

Класс GetNewResponse

Базовый класс: Response
Возвращается в результате успешной обработки запроса GetNewRequest и производных от него запросов.

Свойство Тип Обязательное Описание
record Record Да Новая запись, заполненная по умолчанию.

Получение экземпляра нового подчиненного объекта SOAP

Для получения экземпляра нового взаимодействия отправляется запрос класса GetNewSubRequest. В качестве параметра в запросе передается ссылка на предмет и строка с именем типа требуемого объекта. При успешном выполнении запроса возвращается ответ класса GetNewSubResponse, который содержит новый объект, заполненные по умолчанию. При возникновении ошибки возвращается Error.
Пример использования:

Класс GetNewSubRequest

Базовый класс: GetNewRequest
Запрашивает новый объект взаимодействия указанного типа, заполненный значениями по умолчанию.
Доступно для объектов:

  • PhoneCall — телефонный звонок
  • OutgoingEMail — исходящее электронное письмо
  • ActualWork — запись фактических трудозатрат
  • Order — поручение
Свойство Тип Обязательное Описание
action GetNewSubActions Действие при получении нового объкта
targetId ObjectId Да Ссылка на предмет взаимодействия:
  • Incident — обращение
  • Consultation — консультация
  • Problem — ошибка
  • Suggestion — пожелание
Класс GetNewSubResponse

Базовый класс: GetNewResponse
Возвращается в результате успешной обработки запроса GetNewSubRequest.

Свойства запроса
Класс GetNewSubActions

Описывает возможные действия при получении нового подчиненного объекта.

  • Answer – ответить
  • AnswerToAll – ответить всем
  • Transfer – переслать
  • FillFromArticle – заполнить по карточке базы знаний

Добавление объекта SOAP

Для создания объекта используется запрос класса PostRequest. В качестве параметра передается список объектов с пустыми ссылками. При удачном выполнении запроса возвращается ответ класса PostResponse, содержащий созданные объекты. В случае неудачи возвращается Error.
Пример использования:

Для добавления нескольких объектов одним запросом следует использовать функцию:

При записи процесса можно указать, что он должен быть стартован:

Класс PostRequest

Базовый класс: Request
Добавляет новые объекты в приложение.
Запрос доступен для:

    Inc >

    Свойство Тип Обязательное Список Описание
    action PostActions Дополнительное действие при записи объекта
    objects Object Да Содержит объекты, который требуется создать.
Класс PostResponse

Базовый класс: Response
Возвращается в случае успешного добавления объекта вызовом PostRequest.

Свойство Тип Обязательное Список Описание
objects Object Да Созданные объекы.
Свойства запроса
Класс PostActions

Описывает дополнительные действия при добавлении объектов.

  • StartProcess – стартовать процесс

Добавление подчиненного объекта SOAP

Добавление подчиненных объектов осуществляется с помощью запроса класса PostSubRequest.Запросом передается ссылка на предмет и информация о записываемом объекте. При удачном выполнении запроса возвращается ответ класса PostSubResponse. В случае ошибки возвращается ответ класса Error.
Пример использования при записи файла:

Класс PostSubRequest

Базовый класс: Request
Добавляет новый объект или запись к указанному объекту.
Доступно для предметов:

Доступно для объектов:

  • Inc >
    Свойство Тип Обязательное Описание
    record Record Да Добавляемая запись.
    Для объекта типа File должны быть обязательно заполнены свойства:
    • binaryData
    • text
    • name
    • extension
    • modificationDateUniversal
    • size
    targetId ObjectId Да Ссылка на объект, например, Incident, к которому будет привязан созданный объект или запись.
    Класс PostSubResponse

    Базовый класс: Response
    Возвращается в случае успешной обработки запроса PostSubRequest.

    Свойство Тип Обязательное Описание
    record Record Да Описание записи, которая были добавлена в УСП.

    Обновление объекта SOAP

    Для обновления объекта используется запрос класса PutRequest. В качестве параметров запроса передаются объекты, которые требуется обновить. В случае удачного выполнения запроса возвращается ответ класса PutResponse, содержащий все измененные объекты. В случае ошибки возвращается Error.
    Пример использования:

    Для обновления нескольких объектов одним запросом следует использовать функцию:

    Для установки признака Рассмотрено следует использовать функцию библиотеки:

    Класс PutRequest

    Базовый класс: Request
    Запрос на изменение объектов (например, справочники, документы, бизнес-процессы, задачи).
    Доступно для объектов:

    Объекты, для которых можно установить признак Рассмотрено (action=Consider):

    Свойство Тип Обязательное Список Описание
    action Новый PutActions Дополнительное действие при изменении объекта
    objects Object Да Да Список объектов, которые нужно обновить.
    Класс PutResponse

    Базовый класс: Response
    Возвращается в результате успешной обработки запроса PutRequest.

    Свойство Тип Обязательное Список Описание
    objects Object Да Да Список обновленных объектов.
    Класс PutActions Новый

    Описывает действия при изменении объектов.


    • Consider – При указании дествия для объектов типа IncomingEmail, OutgoingEmail, PhoneCall, ServiceUserComment у перечисленных объектов будет устанавливаться признак Рассмотрено.

    Перенаправление объекта SOAP

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

    Пример перенаправления на линию поддержки:

    Класс PutRedirectRequest

    Базовый класс: Request
    Выполняет перенаправление объекта. В случае удачного выполнения возвращается OK, в случае ошибки Error.
    Доступно для объектов:

      Inc >

      Свойство Тип Обязательное Описание
      query RedirectQuery Да Параметры перенаправления.
      targetId ObjectId Да Ссылка на перенаправляемый объект.
    Свойства запроса
    Класс RedirectQuery

    Описывает параметры перенаправления.

    Свойство Тип Обязательное Описание
    comment string Комментарий перенаправления — обязательное заполнение при перенаправлении другому партнеру или за рамки своей линии поддержки.
    performerId ObjectId Да Новый ответственный. Возможные значения:
    • SupportLine — линия поддержки
    • User — пользователь

    Принятие задачи к исполнению SOAP

    Класс PutAcceptRequest

    Базовый класс: Request
    Выполняет принятие задачи к исполнению. В случае удачного выполнения возвращается OK, в случае ошибки Error.

    Свойство Тип Обязательное Описание
    targetId ObjectId Да Ссылка на задачу

    Выполнение задачи SOAP

    Пример выполнения задачи:

    Пример выполнения задачи с возвратом на исполнение:

    Класс PutCompleteTaskRequest

    Базовый класс: Request
    Запрос на выполнение задачи исполнителя.

    Свойство Тип Обязательное Описание
    action PutСompleteTaskActions Дополнительное действие при выполнении задачи
    comment string Комментарий выполнения
    targetId ObjectId Да Ссылка на задачу
    Свойства запроса
    Класс PutСompleteTaskActions

    Описывает дополнительные действия при выполнении задачи
    Значения перечисления:

    • CompleteTask – выполнить здачу
    • ReturnOnCompletion – вернуть на исполнение
    • CancelOrder – отменить задачу

    Удаление объекта SOAP

    Пометка на удаление выполняется с помощью запроса класса DeleteRequest. В качестве параметров запроса передаются ссылки на объекты. Можно пометить на удаление несколько объектов. Пометка удаления выполняется в транзакции. В случае успешного выполнения запроса возвращается ответ класса DeleteResponse. В случае неудачи возвращается Error.
    Пример использования:

    Для удаления нескольких объектов следует использовать функцию:

    Класс DeleteRequest

    Базовый класс: Request
    Помечает объекты на удаление.
    Доступно только для объектов типа:

    Свойство Тип Обязательное Список Описание
    objectIds ObjectId Да Да Список ссылок на объекты, которые нужно пометить на удаление.
    Класс DeleteResponse

    Базовый класс: Response
    Возвращается в случае успешной обработки запроса DeleteRequest.

    Обращения

    Пример использования в библиотеке интеграции:
    Обработки.СлужбаПоддержки.Формы.Обращение

    Класс Incident

    Базовый класс: Object
    Описывает обращение в УСП.

    Свойство Тип Список Описание
    comments IncidentComment Да Комментарии исполнителей
    component Component Компонент
    date dateTime Дата
    deadline dateTime Срок обработки
    description string Описание
    descriptionHTML HTMLObject Описание в формате HTML с картинками
    dynamicAttributes DynamicAttribute Да Дополнительные реквизиты
    eMailForCorrespondence string Адрес для переписки
    hasNewInteractions boolean Наличие новых взаимодействий
    importance Importance Важность
    initiator ServiceUser Инициатор
    knowledgeBaseArticle KnowledgeBaseArticle Карточка базы знаний
    modifiedDate dateTime Дата изменения
    number string Номер
    objectVersion string Версия объекта — обязательна при записи существующего объекта
    partner Partner Обслуживающая организация
    recievingChannel RecievingChannel Канал получения
    responsible Object Ответственный
    section Section Раздел
    service Service Сервис
    status IncidentStatus Состояние
    subject string Тема
    subscriber Subscriber Абонент
    subscriberPartner Subscriber Обслуживающая организация абонента
    supportLine SupportLine Линия поддержки
    type IncidentType Тип обращения

    Свойства класса

    Класс IncidentType

    Базовый класс: Object
    Описывает тип обращения в УСП.
    Значения перечисления:

    Класс IncidentStatus

    Базовый класс: Object
    Описывает состояния обращения.
    Значения перечисления:

    • Новое
    • Расследование
    • Исправление
    • ОжиданиеИнициатора
    • Закрыто

    Класс Importance

    Базовый класс: Object
    Описывает варианты важности.
    Значения перечисления:

    • ВысокаяВажность — высокая важность
    • ОбычнаяВажность — обычная важность
    • НизкаяВажность — низкая важность

    Класс RecievingChannel

    Базовый класс: Object
    Описывает каналы получения обращений.

    Свойство Тип Описание
    code string Код

    Класс IncidentComment

    Базовый класс: Record
    Описывает список комментариев исполнителей к обращению.

    Свойство Тип Описание
    author User Автор комментария
    comment string Текст комментария
    date dateTime Дата и время комментария
    supportLine SupportLine Линия поддержки автора

    Специальные отборы при получении списка

    Для быстрого отбора обращений можно использовать фильтры:

    • onMy — отбор по текущему пользователю
    • onMyLine — отбор по линии поддержки текущего пользователя
    • onMyCollegues — отбор по сотрудникам линии текущего пользователя

    Взаимодействия

    Пример получения списка взаимодействий по объекту в библиотеке интеграции:
    Обработки.СлужбаПоддержки.Формы.Взаимодействия.
    Для работы с взаимодействиями можно использовать общие запросы:

    • Получение объекта
    • Обновление объекта
    • Удаление объекта

    Так как взаимодействия принадлежат какому либо предмету, для получения списка взаимодействий и для получения экземпляра нового взаимодействия используются запросы:

    • Получение списка подчиненных объектов
    • Получение эклемпляра нового подчиненного объекта
    • Добавление подчиненного объекта

    Телефонный звонок

    Пример использования в библиотеке интеграции:
    Обработки.СлужбаПоддержки.Формы.ТелефонныйЗвонок

    Класс PhoneCall

    Базовый класс: Object
    Описывает телефонный звонок

    Свойство Тип Описание
    callCode string Код звонка
    considered boolean Рассмотрено
    contact Subscriber Абонант — контакт
    creationDate dateTime Дата создания
    description string Описание
    incoming boolean Входящий
    internal boolean Флаг внутренней переписки
    objectVersion string Версия объекта — обязательна при записи существующего объекта
    subject string Тема
    target Object Предмет:
    • Incident — обращение
    • Consultation — консультация
    • Problem — ошибка
    • Suggestion — пожелание

    Комментарий пользователя сервиса

    Пример использования в библиотеке интеграции:
    Обработки.СлужбаПоддержки.Формы.КомментарийПользователя

    Класс ServiceUserComment

    Базовый класс: Object
    Описывает комментарий пользователя к обращению. Создается в случае создания сообщения пользователем из приложения.

    Свойство Тип Описание
    author Object Автор
    considered boolean Рассмотрено
    creationDate dateTime Дата создания
    description string Описание
    descriptionHTML HTMLObject Описание в формате HTML
    responsible User Ответственный
    subject string Тема
    target Object Предмет:
    • Incident — обращение
    • Consultation — консультация
    • Problem — ошибка
    • Suggestion — пожелание

    Электронное письмо входящее

    Класс IncomingEMail

    Базовый класс: Object
    Описывает входящее электронное письмо.

    Свойство Тип Список Описание
    attachments File Да Вложения
    body string Текст
    bodyHTML HTMLObject Текст HTML
    bodyType EMailBodyType Тип текста
    considered boolean Рассмотрено
    containsAttachments boolean Содержит вложения
    creationDate dateTime Дата создания
    importance InteractionImportance Важность
    internal boolean Флаг внутренней переписки
    recipients string Получатели
    recipientsOfCopies string Получатели копий
    sender string Отправитель
    subject string Тема
    target Object Предмет:
    • Incident — обращение
    • Consultation — консультация
    • Problem — ошибка
    • Suggestion — пожелание

    Электронное письмо исходящее

    Класс OutgoingEMail

    Базовый класс: Object
    Описывает исходящее электронное письмо.

    Свойство Тип Список Описание
    account EMailAccount Учетная запись
    attachments File Да Вложения
    baseId string Идентификатор основания
    body string Текст
    bodyHTML HTMLObject Текст в формате HTML с картинками
    bodyType EMailBodyType Тип текста
    considered boolean Рассмотрено
    containsAttachments boolean Содержит вложения
    creationDate dateTime Дата создания
    dateSent dateTime Дата и время отправки
    importance InteractionImportance Важность
    internal boolean Флаг внутренней переписки
    recipients string Получатели
    recipientsOfBlindCopies string Получатели скрытых копий
    recipientsOfCopies string Получатели копий
    status OutgoingEMailStatus Состояние
    subject string Тема
    target Object Предмет:
    • Incident — обращение
    • Consultation — консультация
    • Problem — ошибка
    • Suggestion — пожелание

    Свойства класса

    Класс OutgoingEMailStatus

    Базовый класс: Object
    Описывает состояния исходящего письма.
    Значения перечисления:

    • Черновик — письмо записано но не отправлено
    • Отправлено — письмо отправлено
    • Исходящее — письмо находится в состоянии отправки
    Класс EMailAccount

    Базовый класс: Object
    Описывает учетную запись электронной почты.

    Свойство Тип Описание
    useForReceiving boolean Использовать для получения
    useForSending boolean Использовать для отправки

    Общие свойства взаимодействий

    Класс InteractionImportance

    Базовый класс: Object
    Описывает варианты важности взаимодействий.
    Значения перечисления:

    • Высокая — высокая важность
    • Обычная — обычная важность
    • Низкая — низкая важность

    Класс EMailBodyType

    Базовый класс: Object
    Описывает перечисление Типы текстов электронных писем.
    Значения перечисления:

    • HTML
    • HTMLСКартинками
    • ПростойТекст
    • РазмеченныйТекст

    Карточки базы знаний

    Класс KnowledgeBaseArticle

    Абстрактный класс. Объекты этого класса не могут быть созданы.
    Базовый класс: Object
    Базовый класс для описания карточек базы знаний.

    Свойство Тип Список Описание
    code string Код
    comments ArticleComment Да Комментарии
    components Component Да Компоненты
    creationDate dateTime Дата регистрации
    description string Описание
    descriptionHTML HTMLObject Описание в формате HTML с картинками
    modifiedDate dateTime Дата изменения
    name string Наименование
    objectVersion string Версия объекта — обязательна при записи существующего объекта
    sections Section Да Разделы
    services Service Да Сервисы

    Общие свойства карточек базы знаний

    Класс ArticleComment

    Базовый класс: Record
    Описывает комментарий к карточке базы знаний.

    Свойство Тип Описание
    author User Автор
    comment string Текст комментария
    date dateTime Дата
    supportLine SupportLine Линия поддержки

    Консультации

    Пример использования в библиотеке интеграции:
    Обработки.СлужбаПоддержки.Формы.Консультация

    Класс Consultation

    Базовый класс: KnowledgeBaseArticle
    Описывает карточку Консультации.

    Свойство Тип Описание
    status ConsultationStatus Состояние консультации

    Свойства класса

    Класс ConsultationStatus

    Базовый класс: Object
    Описывает перечисление Состояния консультаций.
    Значения перечисления:

    Ошибки

    Пример использования в библиотеке интеграции:
    Обработки.СлужбаПоддержки.Формы.Ошибка

    Класс Problem

    Базовый класс: KnowledgeBaseArticle
    Описывает карточку ошибки.

    Свойство Тип Описание
    bypass string Обходной путь
    bypassHTML HTMLObject Обходной путь в формате HTML с картинками
    critical boolean Критичная
    playback string Воспроизведение
    playbackHTML HTMLObject Воспроизведение в формате HTML с картинками
    solution string Решение
    solutionHTML HTMLObject Решение в формате HTML с картинками
    status ProblemStatus Состояние

    Свойства класса

    Класс ProblemStatus

    Базовый класс: Object
    Описывает перечисление Состояния ошибок.
    Значения перечисления:

    • Запланирована
    • Расследование
    • На исправлении
    • Исправлена

    Пожелания

    Пример использования в библиотеке интеграции:
    Обработки.СлужбаПоддержки.Формы.Пожелание

    Класс Suggestion

    Базовый класс: KnowledgeBaseArticle
    Описывает Пожелание.

    Свойство Тип Описание
    status SuggestionStatus Состояние

    Свойства класса


    Класс SuggestionStatus

    Базовый класс: Object
    Описывает перечисление Состояния пожеланий.
    Значения перечисления:

    • Принято
    • Запланировано
    • Реализовано
    • Отклонено

    Файлы

    Пример использования в библиотеке интеграции:
    Обработки.СлужбаПоддержки.Формы.ПрисоединенныеФайлы.
    Для работы с файлами можно использовать общие запросы для работы с объектами, такие как:

    • Получение объекта
    • Обновление объекта
    • Удаление объекта

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

    • Получение списка подчиненных объекта.
    • Добавление подчиненного объекта.

    Класс File

    Базовый класс: Object
    Описывает присоединенный файл.

    Свойство Тип Описание
    author User Автор файла.
    binaryData base64Binary Двоичные данные файла.
    creationDate dateTime Дата создания файла.
    deletionMark boolean Пометка удаления.
    description string Описание.
    extension string Расширение файла.
    modificationDateUniversal dateTime Всемирное координированное время (UTC) изменения файла.
    name string Имя файла.
    owner Object Владелец файла.
    size integer Размер файла в байтах.
    text string Текст, извлеченный из файла.

    Трудозатраты

    Трудозатраты могут добавляться по объектам:

    При работе с трудозатратами можно использовать запросы:

    • Получение списка подчиненных объектов.
    • Получение экземпляра нового подчиненного объекта.
    • Добавление подчиненного объекта.

    Класс ActualWork

    Базовый класс: Record
    Описывает запись фактических трудозатрат.

    Свойство Тип Описание
    addDate dateTime Дата добавления
    description string Описание
    duration int Длительность в секундах
    partner Partner Обслуживающая организация (определяется при записи автоматически)
    source Object Источник
    Типы:
    • Incident — обращение
    • Consultation — консультация
    • Problem — ошибка
    • Suggestion — пожелание
    supportLine SupportLine Линия поддержки (определяется при записи автоматически)
    user User Пользователь (если не заполнено, определяется при записи автоматически)

    Процессы и задачи

    Поручение

    Пример использования в библиотеке интеграции:
    Обработки.СлужбаПоддержки.Формы.Поручение

    Класс Order

    Базовый класс: Object
    Описывает Поручение

    Свойство Тип Описание
    author User Автор
    creationDate dateTime Дата создания
    deadline dateTime Срок исполнения
    description string Описание
    descriptionHTML HTMLObject Описание в формате HTML с картинками
    endDate dateTime Дата завершения
    importance TaskImportance Важность
    name string Наименование
    number string Номер
    objectVersion string Версия объекта — обязательна при записи существующего объекта
    performer TaskPerformer Исполнитель
    reviewer TaskPerformer Проверяющий
    reviewPeriod dateTime Срок проверки
    runtimeComments string Комментарий выполнения
    status ProcessStatus Состояние
    target Object Предмет

    Свойства класса

    Класс ProcessStatus

    Базовый класс: Object
    Описывает состояния процесса:

    Класс OrderRoutePoint

    Базовый класс: RoutePoint
    Описывает точки маршрута процесса Поручение
    ▲ в начало

    Задача исполнителя

    Пример использования в библиотеке интеграции:
    Обработки.СлужбаПоддержки.Формы.Задача

    Класс Task

    Базовый класс: Object
    Описывает задачу исполнителя

    Свойство Тип Описание
    acceptDate dateTime Дата принятия к исполнению
    accepted boolean Принята к исполнению
    author User Автор
    creationDate dateTime Дата создания
    deadline dateTime Срок исполнения
    description string Описание
    done boolean Выполнено
    endDate dateTime Дата исполнения
    importance TaskImportance Важность
    myTask boolean Задача направлена текущему пользователю
    name string Наименование
    number string Номер
    objectVersion string Версия объекта — обязательна при записи существующего объекта
    performer TaskPerformer Исполнитель
    performerComment string Коментарий исполнения
    process Order Процесс
    routePoint RoutePoint Точка маршрута
    startDate dateTime Дата начала выполнения
    status ProcessStatus Состояние
    target Object Предмет

    Свойства класса

    Класс TaskImportance

    Базовый класс: Object
    Описывает важность задачи:

    Класс TaskPerformer

    Описывает исполнителя задачи

    Свойство Тип Описание
    mainAddressingObject TaskAddressingObject Основной объект адресации
    role TaskPerformerRole Роль исполнителя
    secondaryAddressingObject TaskAddressingObject Дополнительный объект адресации
    user User Пользователь
    Класс TaskPerformerRole

    Базовый класс: Object
    Описывает роль исполнителя задачи
    ▲ в начало

    Класс TaskAddressingObject

    Базовый класс: Object
    Описывает объект адресации задач
    ▲ в начало

    Общие объекты

    Сервисы

    Класс Service

    Базовый класс: Object
    Описывает список Сервисов.

    Свойство Тип Описание
    code string Код
    tariffsEnabled boolean Признак использования тарифов

    Используется в обращениях и карточках базы знаний.
    ▲ в начало

    Компоненты сервисов

    Класс Component

    Базовый класс: Object
    Описывает справочник Компоненты сервиса.

    Свойство Тип Описание
    code string Код
    service Service Сервис

    Используется в обращениях и карточках базы знаний.
    ▲ в начало

    Разделы

    Класс Section

    Базовый класс: Object
    Описывает список Разделов.

    Свойство Тип Список Описание
    code string Код
    components Component Да Компоненты
    services Service Да Сервисы

    Используется в обращениях и карточках базы знаний.
    ▲ в начало

    Структура поддержки

    Обслуживающие организации

    Используется в обращениях и карточках базы знаний.

    Класс Partner

    Базовый класс: Object
    Описывает обслуживающую организацию (партнера) в УСП.

    Свойство Тип Описание
    code string Код
    firstSupportLine SupportLine Первая линия поддержки
    interactionEnabled boolean Разрешено взаимодействие — если установлено, возможно перенаправление обращения этому партнеру.

    Линии поддержки

    Используется в обращениях и карточках базы знаний.

    Класс SupportLine

    Базовый класс: Object
    Описывает линию поддержки в УСП.

    Свойство Тип Описание
    interactionEnabled boolean Разрешено взаимодействие — если установлено, возможно перенаправление обращения этой линии поддержки.
    partner Partner Обслуживающая организация (партнер)

    Пользователи

    Используется в обращениях и карточках базы знаний.

    Класс User

    Базовый класс: Object
    Описывает пользователя Службы поддержки.

    Свойство Тип Описание
    interactionEnabled boolean Разрешено взаимодействие — если установлено, возможно перенаправление обращения этому пользователю.
    partner Partner Обслуживающая организация (партнер)
    supportLine SupportLine Линия поддержки

    Объекты обслуживания

    Абоненты

    Класс Subscriber

    Базовый класс: Object
    Описывает Абонента сервиса.

    Свойство Тип Список Описание
    code string Номер абонента
    dynamicAttributes DynamicAttribute Да Дополнительные реквизиты. Возможно получение только для объекта.
    service Service Сервис
    serviceUsers ServiceUser Да Пользователи абонента. Возможно получение только для объекта.

    Пользователи сервисов

    Используется в обращениях в качестве инициатора обращения.

    Класс ServiceUser

    Базовый класс: Object
    Описывает пользователя сервиса.

    Свойство Тип Описание
    eMails string Адреса электронной почты
    fullName string Полное имя
    login string Логин
    phone string Номер телефона
    service Service Сервис
    Класс ServiceUserInfoItem

    Информация о пользователе сервиса.

    Свойство Тип Описание
    applicationsCodes string Номера приложений пользователя сервиса
    serviceUser ServiceUser Пользователь сервиса
    subscriber Subscriber Абонент
    subscriberPartner Subscriber Обслуживающая организация абонента

    Приложения

    Класс Application

    Базовый класс: Object
    Описывает приложение в сервисе

    Свойство Тип Описание
    code string Номер приложения
    service Service Сервис

    Прочее

    Класс Type

    Описывает тип объекта API

    Свойство Тип Описание
    presentation string Представление класса
    xdtoClassName string Имя класса

    Класс ObjectId

    Описывает ссылку на объект УСП. Используется в качестве параметра во многих запросах.
    Является основным свойством объекта Object.

    Свойство Тип Обязательное Описание
    id string Да Идентификатор объекта в УСП. Если объект представляет собой элемент справочника или документа, задачу исполнителя или бизнес-процесс, то значением свойства является уникальный идентификатор (UUID) объекта. Если объект представляет собой значение перечисления, то в свойство записывается строковое представление значения перечисления.
    navRef string Навигационная ссылка, заполняется только при получении объекта.
    type string Да Имя класса XDTO, который соответствует данному объекту УСП.
    view string Сроковое представление ссылки.

    Класс Error

    Базовый класс: Response
    Предназначен для информирования внешнего приложения о произошедшей ошибке, если при обработке запроса произошла исключительная ситуация. Может быть возвращен вместо ответа на любой из запросов.

    Свойство Тип Обязательное Описание
    description string Текстовое описание ошибки, а также отладочная информация.
    subject string Тема сообщения об ошибке.

    Класс OK

    Базовый класс: Response
    Возвращается в случае удачного выполнения некоторых запросов.

    HTML документ

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

    Класс HTMLObject

    Описывает HTML документ с картинками.

    Свойство Тип Обязательное Список Описание
    htmlText string Да Текст документа.
    images HTMLObjectImage Да Картинки, входящие в документ.
    Класс HTMLObjectImage

    Описывает картинку, входящую в состав HTML документа.

    Свойство Тип Обязательное Описание
    data base64Binary Да Двоичные данные картинки.
    name string Да Имя картинки.

    Дополнительные реквизиты

    Класс DynamicAttribute

    Базовый класс: Object
    Описывает дополнительный реквизит объекта.

    Свойство Тип Список Описание
    format string Формат редактирования
    multilineInput int Многострочная строка
    objectValue Object Значение объектного типа
    required boolean Обязательное заполнение
    services Service Да Сервисы, для объектов которых доступен реквизит
    simpleValue любой тип Значение простого типа
    tooltip string Подсказка
    usedIn Type Да Типы объектов, в которых может использоваться этот реквизит
    valueTypes Type Да Возможные типы значений
    Класс DynamicAttributeValue

    Базовый класс: Object
    Описывает значение дополнительного реквизита объекта.

    Свойство Тип Описание
    owner DynamicAttribute Владелец
    Класс DynamicAttributeValueHierarchy

    Базовый класс: Object
    Описывает иерархию значений дополнительных реквизитов объектов.

    Свойство Тип Описание
    owner DynamicAttribute Владелец

    Абстрактные классы

    Класс Request

    Абстрактный класс. Объекты этого класса не могут быть созданы.
    Базовый класс для запросов.

    Класс Response

    Абстрактный класс. Объекты этого класса не могут быть созданы.
    Базовый класс для ответов на запросы.

    Класс Record

    Абстрактный класс. Объекты этого класса не могут быть созданы.
    Базовый абстрактный класс для описания записей УСП.

    Класс Object

    Базовый класс: Record
    Базовый абстрактный класс для описания объектов.

    Свойство Тип Обязательное Описание
    objectId ObjectId Да Ссылка на объект.

    Класс RoutePoint

    Абстрактный класс. Объекты этого класса не могут быть созданы.
    Базовый класс: Object
    Базовый класс для определения точек маршрута процессов
    Производные классы:

Понравилась статья? Поделиться с друзьями:
Кодинг, CSS и SQL