12. Постановка на учет внешнеторгового контракта (УНК)

Информация для тестирования

Для получения статуса "Исполнен" [ACPT] необходимо корректно составить и подписать запрос (пример запроса есть ниже в настоящей документации). Затем необходимо написать на п/я h2h@alfabank.ru с просьбой провести операцию, поскольку все операции с валютой требуют авторизации.

Для получения статуса "Отклонен" [RJCT] достаточно, например, некорректно заполнить один из реквизитов.

URI

POST: /API/v1/ISO20022/Contracts

XSD схема

auth.018.001.01

Алгоритм определения продавца и покупателя

Особенностью схемы auth.018 является возможность заполнения данных по контрагенту (с кем заключается контракт) в разделе Buyr или Sellr на усмотрение пользователя.

  1. ИНН резидента (CtrctRegnReq.GrpHdr.InitgPty.Id.OrgId.Othr.Id), где SchmeNm.Cd = 'TXID' — обязательное поле

  2. Одно из полей ИНН является обязательным (SchmeNm.Cd = 'TXID'):

    • Buyr.PtyId.Id.OrgId.Othr.Id

    • Sellr.PtyId.Id.OrgId.Othr.Id

  3. Если значение ИНН из п.1 равно ИНН из Buyr, то резидент - покупатель. Если из Sellr, то резидент - продавец.

Описание схемы

№ R/
O		 Описание Путь Комментарий/
Пример

Общий путь Document.CtrctRegnReq.GrpHdr

1

R

Уникальный id сообщения

MsgId

Указывается идентификатор сообщения присвоенный во внешней системе

2

R

Дата и время создания сообщения

CreDtTm

Формат даты YYYY-MM-DDThh:mm:ss[.mmm]TZD (В случае, если часовой пояс не указан или указан отличный от московского, то время будет приведено к UTC +3).

3

R

Количество транзакций в сообщении

NbOfItms

Общее число контрактов (секций CtrctRegnOpng) в сообщении

4

R

ИНН организации резидента

InitgPty.Id.OrgId.Othr[1].Id

ИНН, по которому определяется организация-инициатор контракта

5

R

Признак использования ИНН

InitgPty.Id.OrgId.Othr[1].SchmeNm.Cd

Константа 'TXID'

6

R

Номер счета резидента

InitgPty.Id.OrgId.Othr[2].Id

Номер счета, по которому определяется организация-инициатор контракта

7

R

Признак использования счета

InitgPty.Id.OrgId.Othr[2].SchmeNm.Cd

Константа 'ACC'

Общий путь Document.CtrctRegnReq.CtrctRegn

8

R

Уникальный id пакета

CtrctRegnId

Указывается идентификатор группы контрактов

9

R

Наименование резидента

RptgPty.PtyId.Nm

Не более 140 символов

10

R

Секция адрес резидента

RptgPty.PtyId.PstlAdr

-

11

O

Тип адреса

RptgPty.PtyId.PstlAdr.AdrTp

Константа 'ADDR'

12

O

Корпус/строение

RptgPty.PtyId.PstlAdr.Dept

-

13

O

Квартира/офис

RptgPty.PtyId.PstlAdr.SubDept

-

14

O

Улица

RptgPty.PtyId.PstlAdr.StrtNm

-

15

O

Номер дома

RptgPty.PtyId.PstlAdr.BldgNb

-

16

O

Город

RptgPty.PtyId.PstlAdr.TwnNm

-

17

O

Регион

RptgPty.PtyId.PstlAdr.DstrctNm

Щекинский район

18

O

Субъект

RptgPty.PtyId.PstlAdr.CtrySubDvsn

Санкт-Петербург

19

O

Код страны

RptgPty.PtyId.PstlAdr.Ctry

RU

20

O

Полный адрес

RptgPty.PtyId.PstlAdr.AdrLine

Максимум 70 символов

21

R

ИНН организации резидента

RptgPty.PtyId.Id.OrgId.Othr.Id

ИНН, по которому определяется организация-инициатор контракта

22

R

Признак использования ИНН

RptgPty.PtyId.Id.OrgId.Othr.SchmeNm.Cd

Константа 'TXID'

23

O

Код страны резидента

RptgPty.PtyId.CtryOfRes

RU

24

R

ОГРН

RptgPty.LglOrg.Id

-

25

R

Дата регистрации ОГРН

RptgPty.LglOrg.RegnDt

-

26

R

КПП

RptgPty.TaxPty.TaxTp

-

27

R

Код клиринговой системы

RegnAgt.FinInstnId.ClrSysMmbId.ClrSysId.Cd

Константа 'RUCBC'

28

R

БИК банка/отделения обслуживающего счет

RegnAgt.FinInstnId.ClrSysMmbId.MmbId

-

29

R

Наименование банка

RegnAgt.FinInstnId.Nm

Требуется указать филиал банка, где обслуживается организация

Общий путь Document.CtrctRegnReq.CtrctRegn

30

R

Уникальный id контракта

CtrctRegnOpng.CtrctRegnOpngId

-

31

R

Срочность оформления УНК

CtrctRegnOpng.Prty

HIGH - в течение дня, NORM - в течение 3 дней

32

O

Номер ранее оформленного номера УНК

CtrctRegnOpng.PrvsRegnId.Id

Заполняется только по п.10.2 Инструкции № 181-И (при уступке/переводе долга по контракту с нерезидентом резидентом на другого резидента). Пример: 11111111/3333/4444/1/1

33

O

Код типа контракта/договора

CtrctRegnOpng.SplmtryData.Envlp.AdditionalData.ContractType

1 - Экспорт товаров
2 - Импорт товаров
3 - Экспорт услуг
4 - Импорт услуг
9 - Смешанная сделка
Если тег не заполняется, то блок
SplmtryData.Envlp.AdditionalData.ContractType не используется. См. пример ниже.

34

O

Вложения к контракту

CtrctRegnOpng.Attchmnt

Описание файлов-вложений к контракту. Подробнее в разделе (Работа с вложенными файлами)

Общий путь Document.CtrctRegnReq.CtrctRegn.CtrctRegnOpng.Ctrct.Trad

35

R

Номер контракта

CtrctDocId.Id

-

36

O

Сумма контракта

Amt Ccy

-

37

O

ИНН покупателя

[Buyr Sellr<>InitgPty].PtyId.Id.OrgId.Othr.Id, где SchmeNm/Cd=TXID

Обязательно к заполнению, если ИНН равен CtrctRegnReq.GrpHdr.InitgPty.Id.OrgId.Othr.Id, где SchmeNm.Cd = 'TXID'

Один из тегов с этим замечанием должен быть обязательно и содержать ИНН клиента

38

O

ИНН продавца

[Buyr Sellr<>InitgPty].PtyId.Id.OrgId.Othr.Id, где SchmeNm/Cd=TXID

Обязательно к заполнению, если ИНН равен CtrctRegnReq.GrpHdr.InitgPty.Id.OrgId.Othr.Id, где SchmeNm.Cd = 'TXID'

Один из тегов с этим замечанием должен быть обязательно и содержать ИНН клиента

39

O

Код страны контрагента

[Buyr Sellr<>InitgPty].PtyId.CtryOfRes

Обязательно к заполнению один из тегов

40

O

Наименование контрагента

[Buyr Sellr<>InitgPty].PtyId.Nm

-

41

O

Признак "Аффилированное лицо"

[Buyr Sellr<>InitgPty].PtyId.CtctDtls.Othr

Возможные значение true/false

42

R

Дата завершения контракта/договора

MtrtyDt

YYYY-MM-DD

43

R

Признак пролонгации

PrlngtnFlg

Обязательно к заполнению по схеме, на создание УНК не влияет.

44

R

Дата начала обязательств по торговому контракту

StartDt

YYYY-MM-DD.

45

R

Валюта контракта

SttlmCcy

Валюта расчетов должна совпадать с валютой в сумме контракта.

Блок с подписью Document.CtrctRegnReq

46

R

Подпись

SplmtryData.Envlp.SgntrSt[1..n]

-
Пример: Создание контракта 
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:auth.018.001.01" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <CtrctRegnReq>
        <GrpHdr>
            <MsgId>TEST_MSG_2024-03-15-20240315</MsgId>
            <CreDtTm>2024-03-15T17:18:19.516</CreDtTm>
            <NbOfItms>1</NbOfItms>
            <InitgPty>
                <Id>
                    <OrgId>
                        <Othr>
                            <Id>7013602245</Id>
                            <SchmeNm>
                                <Cd>TXID</Cd>
                            </SchmeNm>
                        </Othr>
                        <Othr>
                            <Id>40702840200000000529</Id>
                            <SchmeNm>
                                <Cd>ACC</Cd>
                            </SchmeNm>
                        </Othr>
                    </OrgId>
                </Id>
            </InitgPty>
        </GrpHdr>
        <CtrctRegn>
            <CtrctRegnId>TEST_PCT_2024-03-15-20240315</CtrctRegnId>
            <RptgPty>
                <PtyId>
                    <Nm>ООО "Тест Альфа-Линк"</Nm>
                    <PstlAdr>
                        <Dept>1</Dept>
                        <SubDept>11</SubDept>
                        <StrtNm>Уличная</StrtNm>
                        <TwnNm>Городской</TwnNm>
                        <CtrySubDvsn>Московская область</CtrySubDvsn>
                    </PstlAdr>
                    <Id>
                        <OrgId>
                            <Othr>
                                <Id>7013602245</Id>
                                <SchmeNm>
                                    <Cd>TXID</Cd>
                                </SchmeNm>
                            </Othr>
                            <Othr>
                                <Id>40702840200000000529</Id>
                                <SchmeNm>
                                    <Cd>ACC</Cd>
                                </SchmeNm>
                            </Othr>
                        </OrgId>
                    </Id>
                </PtyId>
            </RptgPty>
            <RegnAgt>
                <FinInstnId>
                    <ClrSysMmbId>
                        <ClrSysId>
                            <Cd>RUCBC</Cd>
                        </ClrSysId>
                        <MmbId>044525593</MmbId>
                    </ClrSysMmbId>
                    <Nm>АО Альфа-Банк</Nm>
                </FinInstnId>
            </RegnAgt>
            <CtrctRegnOpng>
                <CtrctRegnOpngId>TEST_ID_2024-03-15-20240315</CtrctRegnOpngId>
                <Prty>NORM</Prty>
                <Ctrct>
                    <Trad>
                        <CtrctDocId>
                            <Id>112233</Id>
                            <DtOfIsse>2024-03-07</DtOfIsse>
                        </CtrctDocId>
                        <Amt Ccy="USD">100.00</Amt>
                        <Buyr>
                            <PtyId>
                                <Nm>ООО "Тест Альфа-Линк"</Nm>
                                <Id>
                                    <OrgId>
                                        <Othr>
                                            <Id>7013602245</Id>
                                            <SchmeNm>
                                                <Cd>TXID</Cd>
                                            </SchmeNm>
                                        </Othr>
                                    </OrgId>
                                </Id>
                                <CtryOfRes>RU</CtryOfRes>
                                <CtctDtls>
                                    <Othr>true</Othr>
                                </CtctDtls>
                            </PtyId>
                        </Buyr>
                        <Sellr>
                            <PtyId>
                                <Nm>"Партнер по контракту 1"</Nm>
                                <Id>
                                    <OrgId>
                                        <Othr>
                                            <Id>9909349194</Id>
                                            <SchmeNm>
                                                <Cd>TXID</Cd>
                                            </SchmeNm>
                                        </Othr>
                                    </OrgId>
                                </Id>
                                <CtryOfRes>PL</CtryOfRes>
                            </PtyId>
                        </Sellr>
                        <MtrtyDt>2024-03-15</MtrtyDt>
                        <PrlngtnFlg>false</PrlngtnFlg>
                        <StartDt>2024-03-07</StartDt>
                        <SttlmCcy>USD</SttlmCcy>
                    </Trad>
                </Ctrct>
                <SplmtryData>
                    <Envlp>
                        <AdditionalData>
                            <ContractType>9</ContractType>
                        </AdditionalData>
                    </Envlp>
                </SplmtryData>
            </CtrctRegnOpng>
        </CtrctRegn>
        <SplmtryData>
            <Envlp>
                <SgntrSt>
                </SgntrSt>
            </Envlp>
        </SplmtryData>
    </CtrctRegnReq>
</Document>
Пример: Если не заполнен тег ContractType 
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:auth.018.001.01" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <CtrctRegnReq>
        <GrpHdr>
            <MsgId>TEST_MSG_2024-03-15-20240315</MsgId>
            <CreDtTm>2024-03-15T17:18:19.516</CreDtTm>
            <NbOfItms>1</NbOfItms>
            <InitgPty>
                <Id>
                    <OrgId>
                        <Othr>
                            <Id>7013602245</Id>
                            <SchmeNm>
                                <Cd>TXID</Cd>
                            </SchmeNm>
                        </Othr>
                        <Othr>
                            <Id>40702840200000000529</Id>
                            <SchmeNm>
                                <Cd>ACC</Cd>
                            </SchmeNm>
                        </Othr>
                    </OrgId>
                </Id>
            </InitgPty>
        </GrpHdr>
        <CtrctRegn>
            <CtrctRegnId>TEST_PCT_2024-03-15-20240315</CtrctRegnId>
            <RptgPty>
                <PtyId>
                    <Nm>ООО "Тест Альфа-Линк"</Nm>
                    <PstlAdr>
                        <Dept>1</Dept>
                        <SubDept>11</SubDept>
                        <StrtNm>Уличная</StrtNm>
                        <TwnNm>Городской</TwnNm>
                        <CtrySubDvsn>Московская область</CtrySubDvsn>
                    </PstlAdr>
                    <Id>
                        <OrgId>
                            <Othr>
                                <Id>7013602245</Id>
                                <SchmeNm>
                                    <Cd>TXID</Cd>
                                </SchmeNm>
                            </Othr>
                            <Othr>
                                <Id>40702840200000000529</Id>
                                <SchmeNm>
                                    <Cd>ACC</Cd>
                                </SchmeNm>
                            </Othr>
                        </OrgId>
                    </Id>
                </PtyId>
            </RptgPty>
            <RegnAgt>
                <FinInstnId>
                    <ClrSysMmbId>
                        <ClrSysId>
                            <Cd>RUCBC</Cd>
                        </ClrSysId>
                        <MmbId>044525593</MmbId>
                    </ClrSysMmbId>
                    <Nm>АО Альфа-Банк</Nm>
                </FinInstnId>
            </RegnAgt>
            <CtrctRegnOpng>
                <CtrctRegnOpngId>TEST_ID_2024-03-15-20240315</CtrctRegnOpngId>
                <Prty>NORM</Prty>
                <Ctrct>
                    <Trad>
                        <CtrctDocId>
                            <Id>112233</Id>
                            <DtOfIsse>2024-03-07</DtOfIsse>
                        </CtrctDocId>
                        <Amt Ccy="USD">100.00</Amt>
                        <Buyr>
                            <PtyId>
                                <Nm>ООО "Тест Альфа-Линк"</Nm>
                                <Id>
                                    <OrgId>
                                        <Othr>
                                            <Id>7013602245</Id>
                                            <SchmeNm>
                                                <Cd>TXID</Cd>
                                            </SchmeNm>
                                        </Othr>
                                    </OrgId>
                                </Id>
                                <CtryOfRes>RU</CtryOfRes>
                            </PtyId>
                        </Buyr>
                        <Sellr>
                            <PtyId>
                                <Nm>"Партнер по контракту 1"</Nm>
                                <Id>
                                    <OrgId>
                                        <Othr>
                                            <Id>9909349194</Id>
                                            <SchmeNm>
                                                <Cd>TXID</Cd>
                                            </SchmeNm>
                                        </Othr>
                                    </OrgId>
                                </Id>
                                <CtryOfRes>PL</CtryOfRes>
                            </PtyId>
                        </Sellr>
                        <MtrtyDt>2024-03-15</MtrtyDt>
                        <PrlngtnFlg>false</PrlngtnFlg>
                        <StartDt>2024-03-07</StartDt>
                        <SttlmCcy>USD</SttlmCcy>
                    </Trad>
                </Ctrct>
            </CtrctRegnOpng>
        </CtrctRegn>
        <SplmtryData>
            <Envlp>
                <SgntrSt>
                </SgntrSt>
            </Envlp>
        </SplmtryData>
    </CtrctRegnReq>
</Document>

Ответ

Ответ приходит по схеме:

auth.027.001.01

Структура ответа описана в разделе [STS_AUTH]

Таблица кодов ответа

HTTP код Тип Body Описание

200

OK

-

Запрос принят без ошибок.

400

Err

XML does not match schema

Документ не соответствует схеме

401

Err

Wrong username or password

Неверный логин или пароль

401

Err

User was not found

Пользователь не найден

401

Err

Could not find signer by certificate

По сертификату пользователь не найден

403

Err

User is disabled

Пользователь заблокирован

403

Err

Internal error while verifying permissions

Ошибка при проверке полномочий

403

Err

Signer is not allowed to sign this operation type

У подписанта нет полномочий на такой тип операции

403

Err

User does not have permission

Нет прав на выполнение запроса

403

Err

Certificate is not valid

Сертификат подписи невалидный

403

Err

Signer’s warrant is expired

Доверенность подписанта истекла

403

Err

Signer’s warrant is disabled

Доверенность подписанта заблокирована

403

Err

Number of signatures is not enough for this operation type

Недостаточно подписей для типа операции

403

Err

Certificate is disabled

Сертификат заблокирован

406

Err

The signer certificate is not valid (revoked or not active)

Сертификат подписанта отозван или невалидный

406

Err

Signature is missing

Нет подписи

406

Err

Signature value is not valid

Подпись невалидна

406

Err

Internal sign check state error

Внутренняя ошибка сервиса

409

Err

MsgId is not unique

Id запроса неуникальный

500

Err

Internal Error

Внутренняя ошибка приложения

500

Err

Warrant service error

Сервис проверки доверенности не отвечает

502

Err

Bad Gateway

Ошибочный шлюз

503

Err

Service Unavailable

Сервис недоступен

504

Err

Gateway Timeout

Шлюз не отвечает