При использовании GET-запроса все данные передаются в URL-строке с использованием GET-синтаксиса. Для большинства других методов все необходимые данные передаются в формате XML. Ответы при этом всегда возвращаются в формате XML.

Тело POST-запроса также должно содержать XML, а заголовок MIME-типа запроса должен быть «text/xml».

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

Для доступа к API ExpertSender вы должны передавать ваш API-key в каждом запросе. API-key — это строка из букв и цифр, которая генерируется для каждого субаккаунта ExpertSender.

Вы можете посмотреть свой API-key в панели управления ExpertSender, перейдя в «Настройки - Настройки субаккаунта - API».

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

API-key уникален и позволяет вам автоматически идентифицироваться в системе.

API-key нужно передавать как URL-параметр для GET-запросов или в XML-теле запроса для остальных запросов.

Запрос

Тело запроса — XML в кодировке UTF-8, без XML-хедера (<?xml..), например:

<ApiRequest
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <ApiKey>Ваш ключ API</ApiKey>
  <Data xsi:type="Subscriber">
    <Mode>AddAndUpdate</Mode>
    <Force>true</Force>
    <ListId>1</ListId>
    <Email>ivan.petrov@domain.com</Email>
    <Firstname>Ivan</Firstname>
    <Lastname>Petrov</Lastname>
    <TrackingCode>123</TrackingCode>
    <Vendor>Основной сайт</Vendor>
    <Ip>11.22.33.44</Ip>
    <Properties>
      <Property>
         <Id>2</Id>
        <Value xsi:type="xs:string">Студент</Value>
      </Property>
      <Property>
        <Id>3</Id>
        <Value xsi:type="xs:dateTime">1985-03-12</Value>
      </Property>
    </Properties>
  </Data>
</ApiRequest>

Запрос состоит из двух частей:

  1. ApiKey — ваш API-key, необходимый для авторизации.
  2. Data — данные запроса. Могут меняться в зависимости от того, что необходимо сделать. Типы данных должны быть указаны в атрибуте «xsi:type».

Ответ

Ответ в виде XML вернется в том случае, если будет ошибка или нужно вернуть какие-либо данные, как для метода GET. Content-type ответа — «text/xml», тело ответа содержит XML.

Формат корректного ответа в виде:

<ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Data>
    ...
  </Data>
</ApiResponse>

Содержание элемента Data меняется в зависимости от того, к каким ресурсам мы обращаемся.

Формат ответа с ошибкой:

<ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <ErrorMessage>
    <Code>400</Code>
    <Message>Email is invalid; </Message>
  </ErrorMessage>
</ApiResponse>

Код ошибки (совпадает с HTTP-кодом ответа) возвращается как читаемое сообщение об ошибке.