Единичный доступ

Режим Единичного доступа позволяет за одно обращение к Сервису отслеживания получить информацию по одному регистрируемому почтовому отправлению (РПО). Возможны следующие запросы:

  • получение подробной информации обо всех операциях, совершенных над отправлением (метод getOperationHistory). Информация об одной операции включает время и место проведения операции, код и атрибут операции, название операции и другие поля;
  • получение информации об операциях с наложенным платежом, который связан с отправлением (метод PostalOrderEventsForMail).

 

Протокол Единичного доступа реализован на основе SOAP (Simple Object Access Protocol).

1. Основная информация по использованию API

Адрес сервисаhttps://tracking.russianpost.ru/rtm34
WSDLhttps://tracking.russianpost.ru/rtm34?wsdl
МетодыgetOperationHistory возвращает историю операций над отправлением
PostalOrderEventsForMail возвращает историю операций с наложенным платежом
Базовый протоколSOAP 1.2
Параметры доступамогут быть получены в разделе Настройки доступа зарегистрированного пользователя, у которого подключен доступ к API
Примеры кодаПримеры кода для работы с API

2. Метод getOperationHistory

Метод getOperationHistory используется для получения информации о конкретном отправлении. Метод возвращает подробную информацию по всем операциям, совершенным над отправлением.

2.1. Запрос

Элемент

Описание

Обязательность

OperationHistoryRequest

Содержит элементы Barcode, MessageType, Language.

 

 

Barcode

Идентификатор регистрируемого почтового отправления в одном из форматов:

- внутрироссийский, состоящий из 14 символов (цифровой);

- международный, состоящий из 13 символов (буквенно-цифровой) в формате S10.

Да

MessageType

Тип сообщения. Возможные значения:

0 - история операций для отправления;

1 - история операций для заказного уведомления по данному отправлению.

Да

Language

Язык, на котором должны возвращаться названия операций/атрибутов и сообщения об ошибках. Допустимые значения:

RUS – использовать русский язык (используется по умолчанию);

ENG – использовать английский язык.

Нет

AuthorizationHeader

Содержит элементы login и password.

Атрибут soapenv:mustUnderstand элемента AuthorizationHeader должен содержать значение 1.

 

 

login

Логин для доступа к API Сервиса отслеживания. Может быть получен в разделе Настройки доступа.

Да

password

Пароль для доступа к API Сервиса отслеживания. Может быть получен в разделе Настройки доступа.

Да

 

2.2. Ответ

Ответ метода getOperationHistory содержит список элементов historyRecord. Каждый из них содержит информацию об одной операции над отправлением. Если над отправлением еще не зарегистрировано ни одной операции, то возвращается пустой список элементов historyRecord.

По каждой операции в ответе обязательно присутствует следующая информация:
- Дата операции (OperDate);
- Место проведения операции (OperationAddress);
- Операция (OperType) и ее атрибут (OperAttr).

Прочая информация возвращается при её наличии в Сервисе отслеживания. 

 

Элемент

Описание

AddressParameters

Содержит адресные данные с операцией над отправлением.

 

DestinationAddress

Содержит адресные данные места назначения пересылки отправления.

 

Index

Почтовый индекс места назначения. Не возвращается для зарубежных операций.

Description

Адрес и/или название места назначения. Пример значения.

 

OperationAddress

Содержит адресные данные места проведения операции над отправлением.

 

Index

Почтовый индекс места проведения операции. Не возвращается для зарубежных операций.

Description

Адрес и/или название места проведения операции.

MailDirect

Содержит данные о стране места назначения пересылки отправления.

 

Id

Код страны. Возможные коды приведены в поле "Код" справочника стран.

Code2A

Двухбуквенный идентификатор страны. Возможные идентификаторы приведены в поле "Alpha2 код" справочника стран.

Code3A

Трехбуквенный идентификатор страны. Возможные идентификаторы приведены в поле "Alpha3 код" справочника стран.

NameRu

Российское название страны. Возможные названия приведены в поле "Наименование страны пересылки" справочника стран.

NameEN

Международное название страны. Возможные названия приведены в поле «Английское наименование страны пересылки» справочника стран.

CountryFrom

Содержит данные о стране приема почтового отправления.

 

Id

Код страны. Возможные коды приведены в поле "Код" справочника стран.

Code2A

Двухбуквенный идентификатор страны. 

Двухбуквенный идентификатор страны. Возможные идентификаторы приведены в поле "Alpha2 код" справочника стран.

Code3A

Трехбуквенный идентификатор страны. Возможные идентификаторы приведены в поле "Alpha3 код" справочника стран.

NameRu

Российское название страны. Возможные названия приведены в поле "Наименование страны пересылки" справочника стран.

NameEN

Международное название страны. Возможные названия приведены в поле «Английское наименование страны пересылки» справочника стран.

CountryOper

Содержит данные о стране проведения операции над почтовым отправлением.

 

Id

Код страны. Возможные коды приведены в поле "Код" справочника стран.

Code2A

Двухбуквенный идентификатор страны. Возможные идентификаторы приведены в поле "Alpha2 код" справочника стран.

Code3A

Трехбуквенный идентификатор страны. Возможные идентификаторы приведены в поле "Alpha3 код" справочника стран.

NameRu

Российское название страны. Возможные названия приведены в поле "Наименование страны пересылки" справочника стран.

NameEN

Международное название страны. Возможные названия приведены в поле «Английское наименование страны пересылки» справочника стран.

FinanceParameters

Содержит финансовые данные, связанные с операцией над почтовым отправлением.

 

Payment

Сумма наложенного платежа в копейках.

Value

Сумма объявленной ценности в копейках.

MassRate

Общая сумма платы за пересылку наземным и воздушным транспортом в копейках.

InsrRate

Сумма платы за объявленную ценность в копейках.

AirRate

Выделенная сумма платы за пересылку воздушным транспортом из общей суммы платы за пересылку в копейках.

Rate

Сумма дополнительного тарифного сбора в копейках.

CustomDuty

Сумма таможенного платежа в копейках.

ItemParameters

Содержит данные о почтовом отправлении.

 

Barcode

Идентификатор почтового отправления, текущий для данной операции.

Internum

Служебная информация, идентифицирующая отправление, может иметь значение ДМ квитанции, связанной с отправлением или иметь значение <null>

ValidRuType

Признак корректности вида и категории отправления для внутренней пересылки

ValidEnType

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

ComplexItemName

Содержит текстовое описание вида и категории отправления.

MailRank

Содержит информацию о разряде почтового отправления.

 

Id

Код разряда почтового отправления.

Name

Название разряда почтового отправления.

PostMark

Содержит информацию об отметках почтовых отправлений.

 

Id

Код отметки почтового отправления.

Name

Наименование отметки почтового отправления.

MailType

Содержит данные о виде почтового отправления.

 

Id

Код вида почтового отправления.

Name

Название вида почтового отправления.

MailCtg

Содержит данные о категории почтового отправления.

 

Id

Код категории почтового отправления.

Name

Название категории почтового отправления.

Mass

 

Вес отправления в граммах.

MaxMassRu

 

Значение максимально возможного веса для данного вида и категории отправления для внутренней пересылки.

MaxMassEn

 

Значение максимально возможного веса для данного вида и категории отправления для международной пересылки.

OperationParameters

Cодержит параметры операции над отправлением

 

OperType

Содержит информацию об операции над отправлением.

 

 

Id

Код операции.

Name

Название операции.

OperAttr

Содержит информацию об атрибуте операции над отправлением.

 

Id

Код атрибута.

Name

Название атрибута.

OperDate

Содержит данные о дате и времени проведения операции над отправлением.

Пример значения: 2015-01-08T14:50:00.000+03:00

UserParameters

Содержит данные субъектов, связанных с операцией над почтовым отправлением.

 

SendCtg

Содержит информацию о категории отправителя.

 

Id

Идентификатор категории отправителя.

Name

Название категории отправителя.

Sndr

 

Содержит данные об отправителе.

Пример значения: ИВАНОВ А Н

Rcpn

 

Содержит данные о получателе отправления.

Пример значения: ПЕТРОВ И.К.

 

2.3. Возможные ошибки

Вид ошибки

Описание

Ошибка авторизации

 

При обращении к Сервису отслеживания произошла ошибка авторизации.

Элемент AuthorizationFault cодержит подробное описание ошибки.

Ошибка получения информации об отправлении

При попытке получить информацию об отправлении произошла ошибка.

Элемент OperationHistoryFault cодержит подробное описание ошибки.

Заданный язык не поддерживается

В запросе был указан недопустимый идентификатор языка.

Элемент LanguageFault cодержит подробное описание ошибки.

 

2.4. Пример запроса и ответа

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

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:oper="http://russianpost.org/operationhistory" xmlns:data="http://russianpost.org/operationhistory/data" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Header/>
   <soap:Body>
      <oper:getOperationHistory>
         <data:OperationHistoryRequest>
            <data:Barcode>RA644000001RU</data:Barcode>
            <data:MessageType>0</data:MessageType>
            <data:Language>RUS</data:Language>
         </data:OperationHistoryRequest>
         <data:AuthorizationHeader soapenv:mustUnderstand="1">
            <data:login>my_login</data:login>
            <data:password>my_password</data:password>
         </data:AuthorizationHeader>
      </oper:getOperationHistory>
   </soap:Body>
</soap:Envelope>

 

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

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
   <S:Body>
      <ns7:getOperationHistoryResponse xmlns:ns2="http://russianpost.org/sms-info/data" xmlns:ns3="http://russianpost.org/operationhistory/data" xmlns:ns4="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns5="http://www.russianpost.org/custom-duty-info/data" xmlns:ns6="http://www.russianpost.org/RTM/DataExchangeESPP/Data" xmlns:ns7="http://russianpost.org/operationhistory">
         <ns3:OperationHistoryData>
            <ns3:historyRecord>
               <ns3:AddressParameters>
                  <ns3:DestinationAddress>
                     <ns3:Index>663300</ns3:Index>
                     <ns3:Description>Норильск Почтамт</ns3:Description>
                  </ns3:DestinationAddress>
                  <ns3:OperationAddress>
                     <ns3:Index>111555</ns3:Index>
                     <ns3:Description>Москва 555</ns3:Description>
                  </ns3:OperationAddress>
                  <ns3:MailDirect>
                     <ns3:Id>643</ns3:Id>
                     <ns3:Code2A>RU</ns3:Code2A>
                     <ns3:Code3A>RUS</ns3:Code3A>
                     <ns3:NameRU>Российская Федерация</ns3:NameRU>
                     <ns3:NameEN>Russian Federation</ns3:NameEN>
                  </ns3:MailDirect>
                  <ns3:CountryOper>
                     <ns3:Id>643</ns3:Id>
                     <ns3:Code2A>RU</ns3:Code2A>
                     <ns3:Code3A>RUS</ns3:Code3A>
                     <ns3:NameRU>Российская Федерация</ns3:NameRU>
                     <ns3:NameEN>Russian Federation</ns3:NameEN>
                  </ns3:CountryOper>
               </ns3:AddressParameters>
               <ns3:FinanceParameters>
                  <ns3:Payment>2500000</ns3:Payment>
                  <ns3:Value>2500000</ns3:Value>
                  <ns3:MassRate>152000</ns3:MassRate>
                  <ns3:InsrRate>25000</ns3:InsrRate>
                  <ns3:AirRate>0</ns3:AirRate>
                  <ns3:Rate>0</ns3:Rate>
               </ns3:FinanceParameters>
               <ns3:ItemParameters>
                  <ns3:Barcode>EA123456789RU</ns3:Barcode>
                  <ns3:ValidRuType>true</ns3:ValidRuType>
                  <ns3:ValidEnType>false</ns3:ValidEnType>
                  <ns3:PostMark>
                     <ns3:Id>0</ns3:Id>
                     <ns3:Name>Без отметки</ns3:Name>
                  <ns3:MailRank>
                     <ns3:Id>0</ns3:Id>
                     <ns3:Name>Без разряда</ns3:Name>
                  </ns3:MailRank>
                  <ns3:PostMark>
                     <ns3:Id>0</ns3:Id>
                     <ns3:Name>Без отметки</ns3:Name>
                  </ns3:PostMark>
                  <ns3:MailType>
                     <ns3:Id>7</ns3:Id>
                     <ns3:Name>Отправление EMS</ns3:Name>
                  </ns3:MailType>
                  <ns3:MailCtg>
                     <ns3:Id>4</ns3:Id>
                     <ns3:Name>С объявленной ценностью и наложенным платежом</ns3:Name>
                  </ns3:MailCtg>
                  <ns3:Mass>2281</ns3:Mass>
               </ns3:ItemParameters>
               <ns3:OperationParameters>
                  <ns3:OperType>
                     <ns3:Id>1</ns3:Id>
                     <ns3:Name>Прием</ns3:Name>
                  </ns3:OperType>
                  <ns3:OperAttr>
                     <ns3:Id>1</ns3:Id>
                     <ns3:Name>Единичный</ns3:Name>
                  </ns3:OperAttr>
                  <ns3:OperDate>2015-07-09T18:08:00.000+03:00</ns3:OperDate>
               </ns3:OperationParameters>
               <ns3:UserParameters>
                  <ns3:SendCtg>
                     <ns3:Id>1</ns3:Id>
                     <ns3:Name>Население</ns3:Name>
                  </ns3:SendCtg>
                  <ns3:Sndr>ИВАНОВ И Н</ns3:Sndr>
                  <ns3:Rcpn>ПЕТРОВ Н И</ns3:Rcpn>
               </ns3:UserParameters>
            </ns3:historyRecord>
             <ns3:historyRecord>
             …
             </ns3:historyRecord>
             …
         </ns3:OperationHistoryData>
      </ns7:getOperationHistoryResponse>
   </S:Body>
</S:Envelope>

 

3. Метод PostalOrderEventsForMail 

Метод PostalOrderEventsForMail позволяет получить информацию об операциях с наложенным платежом, который связан с конкретным почтовым отправлением.

3.1. Запрос

Элемент

Атрибут

Описание

Обязательность

AuthorizationHeader

 

Содержит элементы login и password.

Атрибут soapenv:mustUnderstand элемента AuthorizationHeader должен содержать значение 1.

 

 

login

 

Логин для доступа к API Сервиса отслеживания. Может быть получен в разделе Настройки доступа.

Да

password

 

Пароль для доступа к API Сервиса отслеживания. Может быть получен в разделе Настройки доступа.

Да

PostalOrderEventsForMailInput

 

Содержит атрибуты Barcode, и Language.

Да

 

Barcode

Идентификатор РПО в  одном из форматов:

- внутрироссийский, состоящий из 14 символов (цифровой);

- международный, состоящий из 13 символов (буквенно-цифровой) в формате S10.

 

Language

Язык, используемый в ответных сообщениях. Возможные значения:

RUS – русский (используется по умолчанию)

ENG – английский

 

 

3.2. Ответ

Элемент

Атрибут

Описание

PostalOrderEventNumberНомер почтового перевода наложенного платежа.
EventDateTimeДата и время операции в формате YYYY-MM-DDTHH:mm:ss.SSSZ
Пример значения: 2015-12-11T15:04:37.000+03:00
EventTypeКод операции с наложенным платежом
EventNameНазвание операции
IndexToПочтовый индекс получателя
IndexEventПочтовый индекс отделения почтовой связи, в котором была совершена операция
SumPaymentForwardСумма наложенного платежа в копейках
CountryEventCodeДвухбуквенный идентификатор страны, в которой была совершена операция. Возможные идентификаторы приведены в поле "Alpha2 код" справочника стран.
CountryToCode

Двухбуквенный идентификатор страны получателя наложенного платежа. Возможные идентификаторы приведены в поле "Alpha2 код" справочника стран.

 

3.3. Возможные ошибки

Вид ошибки

Описание

Ошибка авторизации

 

При обращении к Сервису отслеживания произошла ошибка авторизации.

 

3.4. Пример запроса и ответа

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

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:oper="http://russianpost.org/operationhistory" xmlns:data="http://russianpost.org/operationhistory/data" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:data1="http://www.russianpost.org/RTM/DataExchangeESPP/Data">
   <soap:Header/>
   <soap:Body>
      <oper:PostalOrderEventsForMail>
         <data:AuthorizationHeader soapenv:mustUnderstand="1">
            <data:login>my_login</data:login>
            <data:password>my_password</data:password>
         </data:AuthorizationHeader>
         <data1:PostalOrderEventsForMailInput Barcode="14102192069353" Language="ENG"/>
      </oper:PostalOrderEventsForMail>
   </soap:Body>
</soap:Envelope>

 

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

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
   <S:Body>
      <ns7:PostalOrderEventsForMailResponse xmlns:ns2="http://russianpost.org/sms-info/data" xmlns:ns3="http://russianpost.org/operationhistory/data" xmlns:ns4="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns5="http://www.russianpost.org/custom-duty-info/data" xmlns:ns6="http://www.russianpost.org/RTM/DataExchangeESPP/Data" xmlns:ns7="http://russianpost.org/operationhistory">
         <ns6:PostalOrderEventsForMaiOutput>
            <PostalOrderEvent Number="96598" EventDateTime="2015-12-11T15:04:37.000+03:00" EventType="1" EventName="Приём" IndexTo="141021" IndexEvent="298300" SumPaymentForward="234000" CountryEventCode="RU" CountryToCode="RU"/>
            <PostalOrderEvent Number="96598" EventDateTime="2015-12-12T16:49:13.000+03:00" EventType="3" EventName="Оплата" IndexTo="141021" IndexEvent="141021" SumPaymentForward="234000" CountryEventCode="RU" CountryToCode="RU"/>
         </ns6:PostalOrderEventsForMaiOutput>
      </ns7:PostalOrderEventsForMailResponse>
   </S:Body>
</S:Envelope>