Протокол SOAP

Взаимодействие с API Яндекс Директа по протоколу SOAP.

API Яндекс Директа поддерживает протокол SOAP (Simple Object Access Protocol) версии 1.1. Обмен данными по этому протоколу ведется посредством XML-сообщений.

Существует множество библиотек, реализующих протокол SOAP. Некоторые из них перечислены ниже:

WSDL

WSDL (Web Services Description Language) — это язык описания веб-сервисов, основанный на XML. На нем описываются методы, входные и результирующие структуры данных, типы данных, сетевые адреса для обращения к сервису и другое.

Описание API Яндекс Директа на WSDL доступно по адресу:

Версия 4
https://api.direct.yandex.ru/v4/wsdl/
Версия Live 4
https://api.direct.yandex.ru/live/v4/wsdl/

Первоначально WSDL был разработан компаниями IBM, Microsoft и Ariba для использования вместе с протоколом SOAP. Наиболее функциональные библиотеки SOAP используют WSDL-описания для формирования запросов к сервисам и проверки передаваемых данных. Библиотеки скачивают WSDL-описание, анализируют его и формируют структуры данных, необходимые для вызова методов. Приложению остается заполнить эти структуры данными и выполнить запрос. Информация из ответного XML-сообщения так же выдается в виде структуры, свойственной языку программирования. Все это избавляет приложение от необходимости обрабатывать XML.

Примечание.

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

Запросы в формате SOAP

Данные в формате SOAP передаются методом HTTP POST. Запросы отправляют на адрес API Яндекс Директа:

Версия 4
https://api.direct.yandex.ru/v4/soap/
Версия Live 4
https://api.direct.yandex.ru/live/v4/soap/

Способ отправки запросов зависит от SOAP-библиотеки. Если библиотека поддерживает WSDL, достаточно указать адрес WSDL-файла. Из него библиотека получает адрес API Яндекс Директа и выполняет необходимые действия для отправки запроса. Если библиотека не поддерживает WSDL, необходимо явно указывать адрес API.

Сообщение SOAP состоит из заголовка — элемент SOAP-ENV:Header (см. пример ниже) и основной части — элемент SOAP-ENV:Body. Заголовок может содержать метаданные, относящиеся к сообщению в целом. В теле сообщения передается элемент params с входными параметрами метода. Формат элемента params отличается для разных методов.

Пример запроса в формате SOAP

Вызов метода GetClientInfo для получения данных о пользователе «agrom». Заголовок содержит элемент locale, устанавливающий русский язык для ответных сообщений, и элемент token — авторизационный токен, выданный OAuth-сервером Яндекса с согласия пользователя (подробнее см. Авторизационные токены).

POST /v4/soap/ HTTP/1.1
Content-Length: 686
Content-Type: text/xml; charset=utf-8
SOAPAction: "API#GetClientInfo"
Host: api.direct.yandex.ru

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:ns0="API"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Header>
    <locale>ru</locale>
    <token>0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f</token>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <ns0:GetClientInfo SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <params soapenc:arrayType="xsd:string[]">
        <xsd:string>agrom</xsd:string>
        <Login>agrom</Login>
      </params>
    </ns0:GetClientInfo>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Пример ответа в формате SOAP

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:namesp2="http://namespaces.soaplite.com/perl"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <namesp3:GetClientInfoResponse xmlns:namesp3="API">
      <SOAP-ENC:Array xsi:type="namesp2:ArrayOfClientInfo" SOAP-ENC:arrayType="namesp2:ClientInfo[1]">
        <item xsi:type="namesp2:ClientInfo">
          <SendAccNews xsi:type="xsd:string">Yes</SendAccNews>
          <Discount xsi:nil="true" xsi:type="xsd:float"/>
          <Login xsi:type="xsd:string">agrom</Login>
          <Email xsi:type="xsd:string">agrom@yandex.ru</Email>
          <Role xsi:type="xsd:string">Client</Role>
          <FIO xsi:type="xsd:string">Andrew Smith</FIO>
          <DateCreate xsi:type="xsd:date">2011-01-06</DateCreate>
          <StatusArch xsi:type="xsd:string">No</StatusArch>
          <SendNews xsi:type="xsd:string">Yes</SendNews>
          <Phone xsi:nil="true" xsi:type="xsd:string"/>
          <NonResident xsi:type="xsd:string">No</NonResident>
          <SendWarn xsi:type="xsd:string">Yes</SendWarn>
        </item>
      </SOAP-ENC:Array>
    </namesp3:GetClientInfoResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Язык ответных сообщений

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

  • ru — русский;
  • ua — украинский;
  • en — английский.

Если элемент locale отсутствует, подразумевается английский язык.

Доступ к финансовым методам

Для вызова финансовых методов CreateInvoice, TransferMoney, GetCreditLimits, PayCampaigns необходимо дополнительно указывать номер финансовой операции и финансовый токен в элементах operation_num и finance_token соответственно, как показано в следующем примере. Об их формировании рассказывается в разделе Доступ к финансовым методам.

Пример вызова финансового метода

Вызов финансового метода GetCreditLimits. Финансовый токен и номер операции указаны в заголовке сообщения.

POST /v4/soap/ HTTP/1.1
Content-Length: 686
Content-Type: text/xml; charset=utf-8
SOAPAction: "API#GetCreditLimits"
Host: api.direct.yandex.ru

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:ns0="API"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Header>
    <finance_token>07c2fbae9722634918bb00a70d2c467cf1bd07255012008ff249ba41b7a5cd6c</finance_token>
    <operation_num>123<operation_num>
    <token>0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f</token>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <ns0:GetCreditLimits SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <params/>
    </ns0:GetCreditLimits>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Сообщения об ошибках

При возникновении ошибки обработка запроса прекращается и возвращается сообщение об ошибке в формате SOAP. Пример сообщения показан ниже. 

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:namesp8="http://xml.apache.org/xml-soap"
                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
                   xmlns:namesp4="http://namespaces.soaplite.com/perl"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode xsi:type="xsd:string">SOAP-ENV:53</faultcode>
      <faultstring xsi:type="xsd:string">Authorization error</faultstring>
      <detail xsi:type="xsd:string"/>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Элемент faultcode содержит код ошибки, faultstring — краткое описание ошибки, detail — дополнительные пояснения, если имеются. Краткое описание и дополнительное пояснение могут выводиться на разных языках, что определяется элементом locale.