Описание методов API Поручительство

1. Взаимодействия с API ИС Поручитель
Данный документ описывает взаимодействие внешних информационных систем (ВИС) с информационной системой «Поручитель» (ИС).
Каждый документ (файл) участвующий в работе ИС имеет свой уникальный идентификатор. В качестве идентификаторов используются натуральные числа и/или GUID.
GUID (Globally Unique Identifier) – шестнадцати байтный двоичный массив, являющийся пространственно-временным независимым идентификатором. GUID имеет следующее 36-символьное представление:
Документы, запросы с повторяющимися идентификаторами недопустимы и считаются ошибочными.
1.1 Протокол обмена
В качестве протокола обмена используется HTTPS.
1.2 Формат данных
Система поддерживает 2 типа данных — XML и JSON. Формат выбирается ВИС по заголовку Accept для Ответов и Content-Type для Запросов.
1.3 Авторизация ВИС
Авторизация производится по логину и паролю. Если комбинация логина и пароля верны, то в результате выдается JSON Web Token (JWT) и идентификатор сессии.
Токен JWT состоит из трех частей: заголовок (header), полезная нагрузка (payload) и подпись или данные шифрования. Первые два элемента — это JSON объекты определенной структуры. Третий элемент вычисляется на основании первых и зависит от выбранного алгоритма (в случае использования не подписанного JWT может быть опущен). Токены могут быть перекодированы в компактное представление (JWS/JWE Compact Serialization): к заголовку и полезной нагрузке применяется алгоритм кодирования Base64-URL, после чего добавляется подпись и все три элемента разделяются точками («.»).
По идентификатору сессии можно обновить токен доступа.
1.4 Группы пользователей
После прохождения авторизации необходимо выбрать группу пользователя (описано в 3.2), в которой будет осуществляться работа. Сделать это нужно после первого входа в приложения, а дальше при необходимости.
Группы отвечают за видимость документов между агентами и филиалами.
2. Сценарии взаимодействия
Основной сценарий взаимодействия выглядит следующим образом:
1. Загрузка ДДП
2. Отправка ДДП на скоринг
3. Отправка в ФТС
4. Получение результатов из ФТС
2.1 Загрузка ДДП
ВИС загружает в ИС ТД\ПИ в виде xml-файла с указанием суммы страхования. Формат ДДП описан в разделе 4. Если есть номер ДДП, то запускается проверка на наличие ошибок заполнения. Результат проверка отправляется в качестве ответа. Если есть ошибки, то ВИС может повторно загрузить исправленную версию ДДП.
2.2 Отправка ДДП на скоринг
Если ДДП не содержит ошибок, то ее можно отправить на скоринг. Если скоринг не пройден, то в ответе будет указана причина, далее нужно зайти в ИС и решить что дальше (отмена или андеррайтинг).
2.3 Отправка в ФТС
Если скоринг пройден, то ДДП отправляется в ФТС. ФТС может долго обрабатывать документ, поэтому ответ нужно будет получить отдельно.
2.4 Получение результатов из ФТС
ВИС периодически посылает запрос на получение ответов от ФТС.
3. Описание запросов к API
На любой запрос всегда сразу возвращается http-код:
200 - Операция успешно выполнена
400 - Неверный формат данных
403 - Нет прав для выполнения данной операции
404 - Для ВИС нет ответов
409 - Невозможно выполнить по бизнес процессу
3.1 Авторизация
3.1.1 Получение токена доступа и сессии
URL: URL: /api/token?login=(login)&password=(password)
Метод: POST
login обязателный String Логин пользователя
password обязательный String Пароль
3.1.2 Обновление токена
URL: URL: /api/token?session=(session)
Метод: PUT
session обязательный Guid Идентификатор сессии
3.1.3 Удаление сессии
URL: URL: /api/token?session=(session)
Метод: DELETE
session обязательный Guid Идентификатор сессии
3.2 Группы пользователей
3.2.1 Получения списка доступных групп пользователя
URL: /api/groups/user
Метод: GET
Ответ:
[ { "ID": 0, "Name": "Все", "IsAgent": false, "Active": true }, { "ID": 1, "Name": "System", "IsAgent": false, "Active": false } ]
3.2.1 Выбор группы в качестве активной
URL: /api/groups/user?currentGroupId=(currentGroupId)
Метод: POST
Ответ: 200 OK
3.3 Работа с ДДП
3.3.1 Импорт ДДП
Создание ДДП через импорт ТД/ПИ.
URL: /api/insurance-application/import?dutyAmount=(dutyAmount)&softName=(softName)
Метод: POST
Тело запроса должно содержать импортируемый документ в актуальном альбоме форматов.
dutyAmount не обязательный Decimal Страховая сумма
softName не обязательный String Наименование внешней системы
Ответ:
{"ID":1213,"Warning":"Не удалось получить расстояние между таможенными постами"}
ID обязательный Integer Идентификатор документа
Warning не обязательный String Предупреждения, если есть, то документ создан, но с оговорками.
Если ошибок нет, то документ создается в ИС в ответ возвращается его идентификатор.
3.3.2 Создание новой ДДП
Создание пустой ДДП или на основе другой во внутреннем формате.
URL: /api/insurance-application
Метод: POST
Тело запроса может опционально содержать документ во внутреннем формате.
Ответ: Идентификатор созданного документа.
3.3.3 Обновление существующей ДДП
URL: /api/insurance-application/(id)
Метод: PUT
Параметры:
id обязательный Integer Идентификатор заявления на страхование
3.3.4 Получить список всех ДДП
URL: /api/insurance-application?sort=&page=1&pageSize=20&group=&filter=&searchStr= &status=Active
Метод: GET
sort не обязательный String Поле, по которому будет выполнена сортировка
page не обязательный Integer Номер страницы
pageSize не обязательный Integer Размер страницы
group не обязательный String Группировка
filter не обязательный String Поле, по которому будет выполнена фильтрация
status обязательный String Активные/архивные заявления
searchStr не обязательный String Строка поиска, по которой будет произведена выборка
Пример ответа
{ "Data": [ {
"ID": 1119, "DocID": "96477e57-2f73-48ec-8f90-be3fafc0a794",
"RefDocID": null "DocName": "Дополнение к договору поручительства", "DocNumber": "10000/060818/П00030", "DocDate": "2018-08-06T00:00:00",
"StatusID": "StNew", "StatusDescription": "Проект", "DdpStatusID": "DocSaved", "DdpStatusDescription": "Документ сохранен", "ContractKind": "Разовый", "TdIssueDate": "2019-08-19T00:00:00", "ValidityDate": "2019-09-17T00:00:00", "DutyAmount": null, "InsurancePremium": null, "Agent": "Лсв Орг", "AgentContract": null, "PaymentProviderName": "Страхователь", "PaymentProviderINN": "101111111112", "PaymentProviderForeignINN": null, "DeclarantName": "Декларант", "DeclarantINN": "101111111111", "DeclarantForeignINN": null, "CarrierName": null, "CarrierINN": null, "CarrierForeignINN": null, "GroupID": 61, "Login": "admin", "DocInfoID": 1135, "SavingDateTime": "2019-08-19T13:13:37", "InnerProcessID": "76c0dc96-d54f-4b50-8fc3-1efadce466bb", "TdStatusID": null, "IsDeleted": false, "ArchiveStatus": "Основная", "CurrentStatusID": null, "CreationDateTime": "2019-08-19T13:13:37", "RegistrationDate": "2019-08-19T00:00:00", "ElectroDppNumber": null, "GeneralContractNumber": null, "IsOneTimeContract": true, "TransportNumber": null, "TrailerNumber": null, "VesselName": null, "VesselNumber": null, "CodeFF": null, "InsurancePolicyNumber": "190J6001119", } ], "Total": 1,
"AggregateResults": null, "Errors": null }
3.3.5 Скоринг ДДП
Выполнить скоринг заявления. При этом сначала проводится валидация самого заявления по xsd ФТС, а затем уже выполняется скоринг.
URL: /api/auto-scoring/(id)
Метод: POST
id обязательный Integer Идентификатор заявления на страхование
Если валидация не пройдена, то ответ будет код 409, а тело будет содержать список ошибок. 
Пример:
[ { "HtmlItem": "PaymentProvider.OrganizationName", "Name": "Страхователь", "Message": "Значение данного поля не может быть пустым", "MessageExt": "Значение данного поля не может быть пустым", "Value": null, "Data": null }, { "HtmlItem": "PaymentProvider.RFOrganizationFeatures.INN", "Name": "ИНН Страхователя", "Message": "Значение данного поля не может быть пустым", "MessageExt": "Значение данного поля не может быть пустым", "Value": null, "Data": null } ]

Если валидация пройдена, то будет произведен автоматический скоринг. 
Пример:
{ "Id": 19, "GuaranteeContractAdditionId": 1183, "InsuredCheckStatus": true, "InsuredCheckStatusMessage": null, "DeclarantCheckStatus": true, "DeclarantCheckStatusMessage": null, "CarrierCheckStatus": true,
"CarrierCheckStatusMessage": null, "TransportCheckStatus": true, "TransportCheckStatusMessage": "", "InsurancePremiumStatus": false, "InsurancePremiumStatusMessage": "Ошибка расчета страховой премии.", "NomenclatureCheckStatus": true, "NomenclatureFailedCodes": "", "IsOneTimeContract": false, "Status": true, "Errors": [], "Comment": "" }
3.3.6 Отправка в ФТС
URL: api/insurance-application/{id}/fts-message
Метод: POST
id обязательный Integer Идентификатор заявления на страхование

Ответ:
HTTP-код, 200-OK, 400-ошибка входных данных.
3.3.7 Получение данных из ФТС
URL: /api/insurance-application/(id)/fts-message?sort=&page=1&pageSize=20&group=&filter=
Метод: GET
Ответ:
{ "Data": [ {
"ID": 2592,
"StatusID": "DocSent", "StatusDescription": "Документ отправлен",
"TdStatusID": null, "TdStatusDescription": null, "DocID": "7890ec23-c34d-4c72-b9b7-b4d600d60688", "RefDocID": null, "MessageType": "GGI.14001", "DocType": 3, "SavingDateTime": "2019-11-13T11:05:57", "EnvelopeID": "3FC6A6FA-2DC0-43C0-BED8-2C8F4BE1D4D9", "InitialEnvelopeID": null, "InnerProcessID": "4a227bbd-3967-4cf0-a647-3c0300708393", "ReceivedMsgError": null, "AdditionalID": null, "Rank": 0, "Status": null, "HasIcon": true, "CreationDateTime": "2019-11-13T11:05:57" } ], "Total": 1, "AggregateResults": null, "Errors": null }
Описание DocType
0 - ReqOpenProc
1- Unknown
2 - Result
3 - GuaranteeContractAddition
4 - AddRegistrationRefusal
5 - AdditionalRegistrationNotif
6 - AddCustomerRegRefusal
7 - EdContainer
8 - TDSolution
9 - GuaranteeUsage
10 - ExpiredAdditionalList
11 - GuaranteeUsageNotify
12 - GuaranteeStatusReq
13 - GuaranteeContractAmount
14 - GuaranteeResult
15 - NotEnoughSumNotif
3.3.8 Получение документа из обмена с ФТС
URL: /api/insurance-application/(insuranceApplicationId)/fts-message/(ftsMessageId)?ashtml=(true/false)
Метод: GET
insuranceApplicationId Обязательный Integer Идентификатор заявления на страхование
ftsMessageId Обязательный String Поле ID из ответа на запрос (3.3.7)
ashtml Не Обязательный (по умолчанию false) Boolean Получить документ в виде html (применяется стандартное xslt преобразование)
Ответ:
Пример части документа
<Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.w3.org/2001/06/soap-envelope">
<Header>
<roi:RoutingInf xmlns:roi="urn:customs.ru:Envelope:RoutingInf:1.0">
<roi:EnvelopeID>3FC6A6FA-2DC0-43C0-BED8-2C8F4BE1D4D9</roi:EnvelopeID>
<roi:SenderInformation>smtp://eps.customs.ru/nts102773904870472</roi:SenderInformation>
<roi:ReceiverInformation>smtp://eps.customs.ru/gateway</roi:ReceiverInformation>
<roi:PreparationDateTime>2019-11-13T11:06:42+05:00</roi:PreparationDateTime>
</roi:RoutingInf>
<app:ApplicationInf xmlns:app="urn:customs.ru:Envelope:ApplicationInf:1.0">
<app:SoftKind>MySoft</app:SoftKind>
<app:SoftVersion>5.14.3/3.3.22</app:SoftVersion>
</app:ApplicationInf>
<edhead:EDHeader xmlns:edhead="urn:customs.ru:Envelope:EDHeader:2.0">
<edhead:MessageType>GGI.14001</edhead:MessageType>
<edhead:ParticipantID>102773904870472</edhead:ParticipantID>
<edhead:ReceiverCustoms>
<edhead:CustomsCode>10109090</edhead:CustomsCode>
<edhead:ExchType>171000</edhead:ExchType>
</edhead:ReceiverCustoms>
</edhead:EDHeader>
</Header>
<Body>
...
<Body>
</Envelope>
3.3.9 Отмена ДДП
URL: api/insurance-application/(id)/cancel?comment=
Метод: POST
id Обязательный Integer Идентификатор заявления на страхование
comment Не Обязательный String Причина отмены

Ответ:
HTTP-код: 200 – OK, 403 – нет доступа, 409 – невозможно сменить статус.
3.4 Андеррайтинг
3.4.1 Отправка на андеррайтинг
URL: api/underwriting/(id)
Метод: POST

Ответ:
HTTP-код: 200 – OK, 403 – нет доступа, 409 – невозможно сменить статус.
3.4.2 Получение результата андеррайтинга
URL: api/underwriting/(id)
Метод: GET

Ответ:
{"Result": ”Согласовано"} или {"Result": ”Не согласовано"} или {"Result": ”Нет решения"} или {"Result": ”Андеррайтинг указанного заявления не производился"} или HTTP-код 403 – нет доступа

Result Обязательный String Результат андеррайтинга
4. Формат импортируемых документов
В качестве импортируемых документов поддерживаются ТД и ПИ текущего альбома форматов ФТС.