SOAP protocol

Accessing the Yandex Direct API over the SOAP protocol.

The Yandex Direct API supports SOAP (Simple Object Access Protocol) version 1.1. This protocol uses XML messages to exchange information.

There are many libraries that implement SOAP. Some of them are listed below:

Perl: SOAP::Lite and XML::Compile
PHP: nuSOAP and SOAPClient
Python: suds

WSDL

WSDL (Web Services Description Language) is an XML language for describing web services. It describes methods, input and output data structures, data types, network addresses for accessing the service, and more.

There is a WSDL description of the Yandex Direct API at:

Version 4

https://api.direct.yandex.ru/v4/wsdl/

Live 4 version

https://api.direct.yandex.ru/live/v4/wsdl/

WSDL was first developed by IBM, Microsoft and Ariba for use in conjunction with SOAP. The most functional SOAP libraries use WSDL to query services and verify transmissions. These libraries download the WSDL description, analyze it, and form the necessary data structures for making method calls. The application only needs to add data to the structures and send the query. In the same way, the XML response message is output as a structure inherent to the programming language. This frees the application from having to process XML.

Note.

The application can form SOAP queries in XML format by itself, but this is a tedious task that isn't worth the effort, when there are fully-functional SOAP libraries available.

Requests in SOAP format

Data in SOAP format is passed using the HTTP POST method. SOAP requests are sent to the address Yandex Direct API:

Version 4

https://api.direct.yandex.ru/v4/soap/

Live 4 version

https://api.direct.yandex.ru/live/v4/soap/

The method for sending requests depends on the SOAP library. If the library supports WSDL, it is sufficient to specify the address of the WSDL file. The library will use it to get the address of the Yandex Direct API and perform whatever operations are necessary for sending the request. If the library does not support WSDL, the API address must be stated explicitly.

A SOAP message consists of a header, the SOAP-ENV:Header element (see the sample below) and a body, the SOAP-ENV:Body element. The header can contain metadata related to the message as a whole. The message body passes the params element with input parameters for the method. The format of the params element differs for various methods.

Sample request in SOAP format

Calling the GetClientInfo method to get information about the user “agrom”. The header contains the locale element, which sets Russian as the response language, and the token element, which is the access token issued by the Yandex OAuth server with the user's permission (for more information, see Authorization tokens).

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>

Sample response in SOAP format

<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>

Language for responses

The SOAP message header can contain the locale element, which sets the language for response messages. The selected language is used for displaying campaign statuses, the status of banners, and error messages. The locale key may have the following values:

ru — Russian
uk — Ukrainian
en — English

If the locale element is not specified, English is used.

Accessing finance methods

To call the finance methods CreateInvoice, TransferMoney, GetCreditLimits, and PayCampaigns, you must additionally indicate the transaction number and finance token in the operation_num and finance_token elements respectively, as shown in the following example. To learn how they are generated, see Accessing finance methods.

Example of calling a finance method

Calling the GetCreditLimits finance method. The finance token and transaction number are indicated in the message header.

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>

Error messages

If an error occurs, request processing is terminated and an error message is returned in SOAP format. An example of such a message is shown below.

<?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>

The faultcode element contains the error code, faultstring contains a brief description of the error, and detail provides an additional explanation, if available. The brief description and additional explanation can be displayed in various languages; this is determined by the locale parameter.