Try it — Возвраты - SaveDocuments
SOAP Request

Отредактируйте параметры запроса и нажмите Выполнить для отправки запроса на сервер

SaveDocuments: Возвратные накладные

  • Создано 16.04.2026
  • Обновлено 19.05.2026
  • Endpoint: SaveDocuments
  • Soap-method: Возвраты - SaveDocuments
Описание

Функция позволяет сохранить возвратную накладную на основании доставочной в систему «Карго»

Параметры запроса
Параметр Тип Обязательно Описание
login string Логин пользователя
password string Пароль
data Element Список данных сохраняемых документов
parameters Element Список параметров
Описание параметра parameters

Параметр parameters содержит настройки запроса в виде иерархической структуры, соответствующей XML-представлению.

Он должен включать:

Key: строка со значением parameters (обязательное);

List: непустой массив элементов, каждый из которых представляет отдельный параметр и сам является структурой с тремя полями:

  • Key: имя параметра (например, DocumentType);
  • Value: значение параметра указывающая на то какой parameters  описывается;
  • ValueType: тип значения — строка, указывающая тип Value(string, int и т.д.).

Пример одного элемента из List:

<m:List>
   <m:Key>DocumentType</m:Key>
   <m:Value xsi:type="xs:string">waybill</m:Value>
   <m:ValueType>string</m:ValueType>
</m:List>

Каждый такой элемент — независимый узел внутри parameters. Если List отсутствует или пуст — запрос отклоняется.

Иерархия структуры parameters:

parameters → List (массив) → каждый элемент List → Key, Value, ValueType.

Параметр Тип Обязательно Описание
DocumentType string Тип сохраняемых документов, для возвратов должно быть равно «Waybill»
WaybillType string Тип накладной для возвратов нужно использовать значение 1 – возвратная
Описание параметра data

Параметр data содержит данные одной или нескольких возвратных накладных.

Он должен включать:

Key: строка со значением ReturnWaybills  для возвратов (обязательное);

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

  • Key: строка с обозначением какой именно параметр передается (обязательно для каждого элемента);
  • Properties: массив пар «ключ — значение», описывающих основные реквизиты накладной (например, клиент, номер);
  • Fields: массив пар «ключ — значение», описывающих дополнительные поля (например, вес, комментарий, тип груза).

Каждый элемент внутри Properties и Fields содержит:

  • Key: имя поля (например, ClientNumber);
  • Value: значение поля (строка, число, десятичное и т.д.);
  • ValueType: тип значения — строка, указывающая тип Value (string, int и т.п.).

Пример одного элемента из List:

<m:List>
     <m:Key>ReturnWaybill</m:Key>
     <m:Properties>
        <m:Key>ClientNumber</m:Key>
        <m:Value xsi:type="xs:string">123458697</m:Value>
        <m:ValueType>string</m:ValueType>
      </m:Properties>
      <m:Fields>
         <m:Key>Weight</m:Key>
         <m:Value xsi:type="xs:decimal">2</m:Value>
         <m:ValueType>float</m:ValueType>
       </m:Fields>
</m:List>
Каждый такой элемент — независимый узел внутри data. Если List отсутствует или пуст — запрос отклоняется.

Иерархия структуры data:

data → List (массив) → каждый элемент List → Key + Properties (массив) + Fields (массив) → каждый элемент Properties/Fields → Key, Value, ValueType.

Параметр Тип Обязательно Описание
Key string Заголовок информации о документе, для возвратов всегда заполнено «ReturnWaybill»
Fields Element Реквизиты документа
Properties Element Параметры документа
Описание параметра Properties

Список возможных сохраняемых реквизитов документа в Properties

Параметр Тип Обязательно Описание
ClientNumber string Клиентский номер сохранённого документа (если есть) - уникален в рамках клиента
AgentNumber string Номер агента сохранённого документа (если есть)
WaybillNumber string Номер доставочной накладной
TypeOfRecipient string Признак кто является получателем (0 – отправитель из доставочной накладной, 1 – офис КСЭ)
Описание элементов параметра Fields

Список возможных сохраняемых реквизитов документа в Fields

Параметр Тип Обязательно Описание
Comment string Общий комментарий к возвратному документу
TypeOfCargo string GUID (Globally Unique Identifier) вида груза (получение списка видов грузов см. GetReferenceData: виды грузов)
Weight float Вес груза в кг
Height float Высота груза в см
Length float Длина груза в см
Width float Ширина груза в см
CargoDescription string Описание груза
CargoPackageQty float Количество мест, целое неотрицательное число
Возвращаемые параметры

Параметр Element в ответе содержит информацию о сохранённых документах.

Он включает:

Key: строка со значением SaveDocuments;

List: непустой массив элементов, каждый из которых представляет один сохранённый документ и сам является структурой с блоками Properties

Properties: массив реквизитов документа (например, номер клиента, дата создания);

  • Key: имя реквизита (например, ClientNumber);
  • Value: значение реквизита (строка, дата и т.д.);
  • ValueType: тип значения — строка, указывающая тип Value (string, dateTime и т.п.).

Структура ответа иерархична:

Element → Key + List (массив) → каждый элемент List → Key + Properties (массив) → каждый элемент Properties/Fields  → Key, Value, ValueType.

Если во время запроса произошла ошибка, информация о ней будет отражена в свойстве Properties (см. метод GetReferenceData: ErrorCodes — Коды ошибок). 

Параметр Тип Обязательно Описание
Key string Заголовок информации о документе, всегда заполнено «Order»
Properties Element Свойства сохранённого документа, или информация об ошибке для конкретного документа (см. раздел Errors)
Описание возможных возвращаемых параметров properties
Параметр Тип Обязательно Описание
Number string Номер сохранённого в базе документа
ClientNumber string Клиентский номер сохранённого документа (если есть)
AgentNumber string Агентский номер сохранённого документа (если есть)
CreateDate dateTime Дата и время созданного документа
DeliveryDate dateTime DeliveryDate dateTime Планируемая дата доставки
Примеры запроса/ответа 
<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header/>
  <soap:Body>
    <m:SaveDocuments
      xmlns:m="http://www.cargo3.ru">
      <m:login
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">test
      
      </m:login>
      <m:password
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">2016
      
      </m:password>
      <m:data
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <m:Key>ReturnWaybills</m:Key>
        <m:List>
          <m:Key>ReturnWaybill</m:Key>
          <m:Properties>
            <m:Key>ClientNumber</m:Key>
            <m:Value xsi:type="xs:string">123458697</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Properties>
          <m:Properties>
            <m:Key>WaybillNumber</m:Key>
            <m:Value xsi:type="xs:string">888-0006983-00006639</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Properties>
          <m:Properties>
            <m:Key>TypeOfRecipient</m:Key>
            <m:Value xsi:type="xs:string">0</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Properties>
          <m:Fields>
            <m:Key>Comment</m:Key>
            <m:Value xsi:type="xs:string">Комментарий общий</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>TypeOfCargo</m:Key>
            <m:Value xsi:type="xs:string">4aab1fc6-fc2b-473a-8728-58bcd4ff79ba</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>Weight</m:Key>
            <m:Value xsi:type="xs:decimal">2</m:Value>
            <m:ValueType>float</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>CargoDescription</m:Key>
            <m:Value xsi:type="xs:string">Описание груза</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>CargoPackageQty</m:Key>
            <m:Value xsi:type="xs:decimal">2</m:Value>
            <m:ValueType>int</m:ValueType>
          </m:Fields>
        </m:List>
      </m:data>
      <m:parameters
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <m:Key>Parameters</m:Key>
        <m:List>
          <m:Key>DocumentType</m:Key>
          <m:Value xsi:type="xs:string">waybill</m:Value>
          <m:ValueType>string</m:ValueType>
        </m:List>
        <m:List>
          <m:Key>waybillType</m:Key>
          <m:Value>1</m:Value>
          <m:ValueType>int</m:ValueType>
        </m:List>
      </m:parameters>
    </m:SaveDocuments>
  </soap:Body>
</soap:Envelope>
<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <m:SaveDocumentsResponse
      xmlns:m="http://www.cargo3.ru">
      <m:return
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <m:Key>SaveDocuments</m:Key>
        <m:List>
          <m:Key>ReturnWaybill</m:Key>
          <m:Properties>
            <m:Key>WaybillNumber</m:Key>
            <m:Value xsi:type="xs:string">888-0006983-00006639</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Properties>
          <m:Properties>
            <m:Key>ClientNumber</m:Key>
            <m:Value xsi:type="xs:string">123458697</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Properties>
          <m:Properties>
            <m:Key>TypeOfRecipient</m:Key>
            <m:Value xsi:type="xs:string">0</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Properties>
          <m:Properties>
            <m:Key>Number</m:Key>
            <m:Value xsi:type="xs:string">888-0006983-00006647</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Properties>
          <m:Properties>
            <m:Key>CreateDate</m:Key>
            <m:Value xsi:type="xs:dateTime">2017-09-07T14:27:26</m:Value>
            <m:ValueType>dateTime</m:ValueType>
          </m:Properties>
        </m:List>
      </m:return>
    </m:SaveDocumentsResponse>
  </soap:Body>
</soap:Envelope>