Try it — CountryCodes

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

GetReferenceData: CountryCodes — Коды стран

  • Создано 16.04.2026
  • Обновлено 18.05.2026
  • Endpoint: GetReferenceData
  • Soap-method: CountryCodes
Описание

Функция позволяет получить список кодов стран в следующих форматах: цифровой, альфа-2, альфа-3. Полученные данные используются при последующих вызовах других функций веб-сервиса.

Режимы работы функции: 

1. Получение всех стран

Условие: параметры Search и InGroup не переданы

Результат: возвращаются все записи справочника «Страны мира» с соответствующими кодами

2. Поиск по наименованию

Условие: передан параметр Search

Результат: возвращаются данные только для страны, наименование которой точно совпадает с указанным в параметре Search. Наименование должно соответствовать названию страны в базе «Карго»

3. Поиск по GUID

Условие: передан параметр InGroup

Результат: Возвращаются данные только для страны, идентификатор которой (GUID) соответствует переданному значению

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

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

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

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

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

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

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

<car:List>
   <car:Key>Reference</car:Key>
   <car:Value>CountryCodes</car:Value>
   <car:ValueType>string</car:ValueType>
</car:List>

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

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

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

Параметр Тип Обязательно Описание
Reference string Имя справочника, должно быть равно «CountryCodes»
Search string Наименование (должно совпадать с наименованием в Карго). При поиске по названию поиск
относительно GUID не выполняется (параметр InGroup игнорируется).
InGroup string GUID страны; представляет собой GUID элемента справочника «Страны мира». Если параметр не указан, или передана пустая строка, в ответе приходят все записи справочника "Страны мира" с кодами.
Возвращаемые параметры

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

Он включает элементы справочника:

Key: идентификатор справочника, к которому относится запись (например, CountryCodes);

List: контейнер записи справочника.

Каждая запись справочника из списка List в виде структуры Element содержит в себе:

  • Key: Уникальный идентификатор записи (GUID) (например, 74573d15-00dd-11e4-8edb-005056b1a128);
  • Value: значение записи (основное наименование);
  • ValueType: тип значения — строка, указывающая тип Value (string, dateTime и т.п.);
  • Fields: набор дополнительных атрибутов записи, повторяющийся элемент.

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

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


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

Параметр Тип Обязательно Описание
Key string Уникальный номер элемента справочника в формате GUID (Globally Unique Identifier)
Value string Полное наименование географического объекта
Fields string Другие свойства элемента справочника
Возвращаемые параметры Fields

Каждый блок Fields описывает одно дополнительное поле текущей записи справочника внутри List:

  • Key: название дополнительного поля (например, FullName,СountryСode);
  • Value:  значение дополнительного поля (может быть пустым);
  • ValueType: тип значения (string, boolean, и т.д.).
Параметр Тип Обязательно Описание
FullName string Полное официальное наименование страны
СountryСode string Цифровой код страны (ISO 3166-1 numeric)
AlfaCode2 string Двухбуквенный код (ISO 3166-1 alpha-2)
AlfaCode3 string Трёхбуквенный код (ISO 3166-1 alpha-3)
Currency string Валюта страны (поле может быть пустым)
CurrencyGuid string GUID валюты в системе
Примеры запроса/ответа
<soap:Envelope
  xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:car="http://www.cargo3.ru">
  <soap:Header/>
  <soap:Body>
    <car:GetReferenceData>
      <car:login>test</car:login>
      <car:password>2016</car:password>
      <car:parameters>
        <car:Key>parameters</car:Key>
        <car:List>
          <car:Key>Reference</car:Key>
          <car:Value>CountryCodes</car:Value>
          <car:ValueType>string</car:ValueType>
        </car:List>
        <car:List>
          <car:Key>Search</car:Key>
          <car:Value>КАЗАХСТАН</car:Value>
          <car:ValueType>string</car:ValueType>
        </car:List>
      </car:parameters>
    </car:GetReferenceData>
  </soap:Body>
</soap:Envelope>
<soap:Envelope
  xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <m:GetReferenceDataResponse
      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>CountryCodes</m:Key>
        <m:List>
          <m:Key>74573d15-00dd-11e4-8edb-005056b1a128</m:Key>
          <m:Value xsi:type="xs:string">КАЗАХСТАН</m:Value>
          <m:ValueType>string</m:ValueType>
          <m:Fields>
            <m:Key>FullName</m:Key>
            <m:Value xsi:type="xs:string">Республика Казахстан</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>СountryСode</m:Key>
            <m:Value xsi:type="xs:string">398</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>AlfaCode2</m:Key>
            <m:Value xsi:type="xs:string">KZ</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>AlfaCode3</m:Key>
            <m:Value xsi:type="xs:string">KAZ</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>Currency</m:Key>
            <m:Value xsi:type="xs:string"/>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>CurrencyGuid</m:Key>
            <m:Value xsi:type="xs:string">00000000-0000-0000-0000-000000000000</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
        </m:List>
      </m:return>
    </m:GetReferenceDataResponse>
  </soap:Body>
</soap:Envelope>