---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://yandex.ru/dev/direct/doc/en/concepts/soap.md
  - https://yandex.ru/dev/direct/doc/ru/concepts/soap.md
sourcePath: ru/dg/concepts/soap.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/direct/doc/ru/llms.txt

# Протокол SOAP

Во многих языках программирования существуют библиотеки для работы с SOAP. Ниже перечислены рекомендуемые библиотеки для популярных языков.

- **Perl:** [SOAP::Lite](https://metacpan.org/pod/SOAP::Lite) и [XML::Compile](http://search.cpan.org/dist/XML-Compile/);
- **PHP:** [SOAPClient](http://php.net/manual/ref.soap.php);
- **Python:** [suds](https://pypi.python.org/pypi/suds);
- **Java:** [Axis2](http://axis.apache.org/axis2/java/core/), [Metro](http://javaee.github.io/metro/).

## WSDL {#wsdl}

Для каждого сервиса в API Директа разработано описание на языке WSDL (Web Services Description Language), в котором представлены методы, входные и выходные структуры данных, типы данных, адрес для запросов к сервису и другое.

Адрес WSDL указан в документации каждого сервиса.

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

{% note info %}

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

{% endnote %}

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

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

Адрес WSDL и адрес для запросов указаны в документации каждого сервиса.

# Пример запроса

Вызов метода `Ads.add` для добавления объявлений рекламодателю `agrom`, выполняемый от имени рекламного агентства.

```xml translate=no
POST /v5/ads/ HTTP/1.1
Host: api.direct.yandex.com
Authorization: Bearer 0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f
Accept-Language: en
Client-Login: agrom
Content-Type: text/xml; charset=utf-8
SOAPAction: "https://api.direct.yandex.com/v501/ads/add"

`<?xml version="1.0" encoding="UTF-8"?`
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="http://api.direct.yandex.com/v5/ads"
  <SOAP-ENV:Body
    <ns1:AddRequest
      <Ads
        <AdGroupId1234567</AdGroupId
        <TextAd
          <TextСлоны всех пород. Сертифицированный питомник</Text
          <TitleКупи слона!</Title
          <Hrefhttp://exotic-farm.com/elefants</Href
          <MobileNO</Mobile
        </TextAd
      </Ads
      <Ads
        <AdGroupId1234567</AdGroupId
        <TextAd
          <TextНосороги с доставкой. Весенняя распродажа</Text
          <TitleКупи носорога!</Title
          <MobileNO</Mobile
        </TextAd
      </Ads
    </ns1:AddRequest
  </SOAP-ENV:Body
</SOAP-ENV:Envelope
```

# Пример ответа

```xml translate=no
HTTP/1.1 200 OK
Connection:close
Content-Type:text/xml; charset=utf-8
Date:Fri, 28 Nov 2014 17:07:02 GMT
RequestId:1010101010101010101
Units:10/20828/64000
Units-Used-Login:agrom
Server:nginx
Transfer-Encoding:chunked

`<?xml version="1.0" encoding="UTF-8"?`<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  <SOAP-ENV:Body
    <ns3:AddResponse xmlns:ns3="http://api.direct.yandex.com/v5/ads"
      <AddResults
        <Id7654321</Id
      </AddResults<!-- Объявление успешно создано, возвращен его идентификатор --
      <AddResults
        <Errors
          <Code6000</Code
          <MessageНеконсистентное состояние объекта</Message
          <DetailsВ объявлении должна быть указана или визитка или основная ссылка</Details
        </Errors
      </AddResults<!-- Ошибка создания объявления --
    </ns3:AddResponse
  </SOAP-ENV:Body
</SOAP-ENV:Envelope
```

# Пример ошибки

Если выполнение запроса невозможно, возвращается сообщение об ошибке.

```xml translate=no
HTTP/1.1 200 OK
Connection:close
Content-Type:text/xml; charset=utf-8
Date:Fri, 28 Nov 2014 17:07:02 GMT
RequestId:1010101010101010101
Units:10/20828/64000
Units-Used-Login:agrom
Server:nginx
Transfer-Encoding:chunked

`<?xml version="1.0" encoding="UTF-8"?`<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  <SOAP-ENV:Body
    <SOAP-ENV:Fault
      <faultcodeSOAP-ENV:Client</faultcode
      <faultstringНекорректный запрос</faultstring
      <detail
        <ns3:FaultResponse xmlns:ns3="http://api.direct.yandex.com/v5/general"
          <requestId1010101010101010101</requestId
          <errorCode8000</errorCode
          <errorDetailВ TextAd отсутствует обязательное поле Text</errorDetail
        </ns3:FaultResponse
      </detail
    </SOAP-ENV:Fault
  </SOAP-ENV:Body
</SOAP-ENV:Envelope
```

## Узнайте больше

- [SOAP](http://www.w3.org/TR/soap/)
- [WSDL](http://www.w3.org/TR/wsdl/)