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

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

SOAP Endpoint: SaveDocuments Обновлено: 2026-05-19

Endpoint: SaveDocuments
SOAP-метод: Возвраты - SaveDocuments
Группа: SaveDocuments
Создано: 16.04.2026 · Обновлено: 19.05.2026

Описание

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

Параметры запроса

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

Описание параметра parameters

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

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

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

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

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

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

xml

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

xml

<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 Планируемая дата доставки

Пример запроса (XML Request)

xml

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

Пример ответа (XML Response)

xml

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

Смежные методы

Заказы - SaveDocuments

Функция сохраняет новые документы в систему «Карго».