Входящий API для интеграции с агентами по выдаче банковских гарантий. Полный справочник эндпоинтов, схем данных и справочников по работе с заявкой через единый конвейер мультибанка.
Документ описывает методы запуска и сопровождения заявок на банковскую гарантию через интеграционный шлюз Farzoom. Заявка автоматически распределяется между банками-партнёрами; жизненный цикл и решения по каждому банку независимы.
Введение
Используемые типы запросов для работы с заявкой:
POST — старт заявки
PUT — любые изменения и ответы по заявке
GET — запрос статуса по заявке
Метод GET /masterOrder/{masterOrderId} позволяет получить консолидированный ответ о статусах заявки в разрезе банков одновременно. Для получения статуса заявки в конкретном банке используется метод GET /order/{orderId}. Для работы с заявкой в каждом из банков используется метод PUT /order/{orderId}.
Модель данных для методов POST и PUT идентичная. Отличие — для метода POST не требуется направлять decision.resultCode. При отправке новых данных старые данные будут перезаписаны.
Изменение данных ограничено стороной владельца заявки
Система не принимает изменения данных по заявке, если заявка находится на стороне банка или клиента. Изменение данных возможно только тогда, когда заявка находится на стороне агента — в этом случае в статусе заявки будут присутствовать decision.resultCode с описанием.
Базовый URL
Базовый URL интеграционного шлюза предоставляется куратором при подключении к партнёрской программе. В этой документации эндпоинты приведены как относительные пути от базового URL — например, POST {base-url}/order.
Авторизация
Для авторизации используется HTTP Basic Authentication. Логин и пароль (необходимо получить у своего куратора) передаются в заголовке запроса Authorization для совместимости со старым API банков.
HTTP Заголовки
POST /order HTTP/1.1
Host: {base-url}
Authorization: Basic <base64(login:password)>
Content-Type: application/json
Жизненный цикл заявки
После старта заявка проходит через несколько состояний. Заявки в разных банках в рамках одного запроса имеют независимый статус: при отказе по одной заявке статус других не изменяется.
Маршрутизация по банкам-партнёрам, переходы между ролями (Агент / Банк / Клиент) и итоговые состояния.
Краткая схема перехода статусов:
POST /order→InProcess→PendingAgent↔PendingClient→Executed
Поведение при выдаче гарантии
При выдаче одной из заявок в банке вместе со статусом приходит скан БГ и соответствующий статус Executed. При этом остальные заявки в рамках этого запроса переходят в статус RejectedByBank, работа с ними становится невозможна.
Запуск заявки
Отправьте запрос методом POST на /order. Тело запроса должно содержать необходимые для старта заявки данные (схема OrderRequest).
В случае успешного старта сервис вернёт 200 с идентификаторами и номерами заявок в банках (OrderResponse). Если валидация запроса не прошла, ответит 4XX.
Пример запроса (минимальный набор данных)
POST /order — application/json
{"principal":{"inn":"9721162149","kpp":"773001001","ogrn":"1227700208471","fullName":"АКЦИОНЕРНОЕ ОБЩЕСТВО \"СТАРТ\""},"multiLotBankGuarantee":{"bankGuaranteeType":"participation","purchaseNumber":"32514958721","federalLaw":"223","marketPlace":"ЭТП РТС-тендер","tenderContractType":"state","tenderType":"Аукцион в электронной форме, участниками которого могут быть только субъекты малого и среднего предпринимательства","purchasePublishedDate":"2025-06-19","startDate":"2025-06-19","endDate":"2025-06-27","requiredExecutionDate":"2025-06-19","amount":24242.35,"maxAmount":242251.35,"finalAmount":242251.35,"isSplittedByBeneficiaries":false,"url":"https://zakupki.gov.ru/epz/order/notice/notice223/common-info.html?noticeInfoId=18450681","auctionType":"public","isBigDeal":false,"isGuaranteeInBeneficiaryForm":false,"guaranteeReceivingWay":"bankOffice","subject":"Поставка электроинструмента и ручного инструмента для нужд отряда ФПС ГПС – Амурский филиал ФГБУ «Управление ДП ФПС ГПС № 6»","isSeparateLotProtocols":false,"lots":[{"lotNumber":"1","lotSubject":"Поставка электроинструмента и ручного инструмента для нужд отряда ФПС ГПС – Амурский филиал ФГБУ «Управление ДП ФПС ГПС № 6»","startAmount":242251.35,"finalAmount":242251.35,"ikzList":[""],"okpd":[{"name":"Инструменты ручные электрические","code":"28.24.11.000"}],"beneficiaries":[{"inn":"2722085818","kpp":"272201001","ogrn":"1092722003725","fullName":"ФЕДЕРАЛЬНОЕ ГОСУДАРСТВЕННОЕ БЮДЖЕТНОЕ УЧРЕЖДЕНИЕ \"УПРАВЛЕНИЕ ДОГОВОРНЫХ ПОДРАЗДЕЛЕНИЙ ФЕДЕРАЛЬНОЙ ПРОТИВОПОЖАРНОЙ СЛУЖБЫ ГОСУДАРСТВЕННОЙ ПРОТИВОПОЖАРНОЙ СЛУЖБЫ № 6\"","customerRegNum":"82722085818272201001","deliveryPlace":"Амурская обл, Амурская область, г. Благовещенск, ул. Вокзальная, д. 61","purchaseAmount":242251.35,"amount":24242.35,"legalAddress":"680000, ХАБАРОВСКИЙ КРАЙ, Г.О. ГОРОД ХАБАРОВСК, Г ХАБАРОВСК, УЛ ШЕВЧЕНКО, Д. 28","actualAddress":"680000, ХАБАРОВСКИЙ КРАЙ, г.о. ГОРОД ХАБАРОВСК, Г. ХАБАРОВСК, УЛ ШЕВЧЕНКО, Д. 28","phone":"9242172735","email":"kanc@udp6.27.mchs.gov.ru","contract":{"isConcluded":false}}],"contractConditions":{"prepaymentExists":false,"isRequiredIndisputableDebiting":false,"isIncludedForfeit":false,"isRequiredSecurityForGuaranteePeriod":false}}],"callbackUrl":"some_url"}}
Отправьте запрос методом GET на /order/{orderId}. Ответ содержит комментарии валидации и возможные решения по заявке (StatusResponse). Заявки в разных банках в рамках одного запроса имеют независимый статус.
Справочник допустимых статусов заявки указан в разделе «Статусы заявки». Справочник допустимых taskDefinitionKey (детализированный статус) указан в разделе «TaskDefinitionKey».
Пример ответа
200 OK — application/json
{"orderId":"zhAyONl9OoNCpwWt5XRD7","orderNumber":"МБГ-1491@АкБарс","taskDefinitionKey":"AGENT_FILL_APPLICATION","processDefinitionKey":"BG_AGENT_BANK","comments":"Не удалось отправить заявку в банк: ИКЗ: Некорректный формат;","decisionOptions":[{"code":"sendToBank","text":"Отправить в банк","isCommentRequired":false},{"code":"reject","text":"Отказ","isCommentRequired":false}],"orderStatus":"PendingAgent"}
Работа с заявкой
Для изменения данных по заявке используется метод PUT/order/{orderId}. Обязательно к отправке поле decision.resultCode (схема Decision).
Подписание документов осуществляется только на странице подписания Системы. При запросе подписания документов банком в статус заявки придёт ссылка на страницу подписания. На этапе подписания управление заявкой ведётся со страницы подписания (подписано / не подписано / маршруты изменения этапа и параметров заявки).
Работа с файлами
Для загрузки файлов используется метод POST/file. В случае успешной загрузки сервис вернёт 200 и идентификатор файла (FileUploadInfo).
Для получения файлов используется метод GET/order/{orderId}/file/{fileId}. При успешном выполнении вернёт 200 и сам файл; если файл не найден — 404.
Размер файла ограничен 10 МБ. Количество файлов не ограничено.
Файлы загружаются в заявку в соответствующие доктайпы.
Если в свойствах доктайпа указано multiple: false, доктайп хранит только один файл. При отправке нового имеющийся будет перезаписан. При отправке нескольких файлов с multiple: false в доктайп будет сохранён только последний.
Коллбеки
При изменении статуса заявки Система направляет уведомление в виде HTTP-коллбека по указанному в запросе адресу — callbackUrl. Данные коллбека идентичны данным, получаемым при запросе статуса в один момент времени (StatusResponse).
Рекомендация
Принимающий обработчик коллбеков должен быть идемпотентным: при сетевых сбоях возможна повторная доставка одного и того же события. Используйте сочетание orderId + taskDefinitionKey + orderStatus как ключ дедупликации.
Эндпоинты
Полный справочник методов API. Все пути указаны относительно базового URL.
Статус заявки в банке:
* InProcess - в процессе
* RejectedByBank - отказ
* RejectedByAgent - клиент отказался от гарантии
* Executed - гарантия предоставлена банком
* PendingAgent - ожидает ответа от Агента
* PendingClient - ожидает действий клиента
* Failed - Процесс невозможно закончить
Вид банковской гарантии:
* participation - На участие в торгах
* execution - На исполнение обязательств по контракту
* returnAdvance - На возврат аванса
* period - На обеспечение гарантийных обязательств
Основания наличия статуса:
* controlOfActions - Возможность контролировать действия Клиента,
* directCapitalParticipation - Прямое участие в капитале Клиента,
* indirectCapitalParticipation - Косвенное участие в капитале Клиента,
* companyHead - Единоличный исполнительный орган юридического лица
Должность:
* director - Директор,
* ceo - Генеральный директор,
* actingCeo - ВРИО Генерального директора,
* president - Президент,
* other - значение из поля otherPosition
directorceoactingCeopresidentother
otherPosition
string
опц.
Иная должность. Обязательно, если в поле position указано other
Единственный участникОбщее собрание участников (несколько участников)Общее собрание акционеров (несколько акционеров)Единственный акционер (один акционер с долей 100%)
soleExecutiveBody
string
опц.
Единоличный исполнительный орган. companyHead - руководитель, managementCompany - управляющая компания
Контракт содержи требование об обеспечении гарантийного периода
securityForGuaranteePeriodDays
integer (int32)
опц.
Срок гарантийного периода в днях (если предусмотрен)
Decisionobject
Свойство
Тип
Обязат.
Описание
resultCode
string
опц.
Код решения агента
comment
string
опц.
Комментарий агента
DefaultHttpStatusCodeobject
Documentobject
Свойство
Тип
Обязат.
Описание
type
string
опц.
Тип документа:
* customer_charter - Устав юридического лица
* customer_eioAuthorizingDoc - Решение и/или приказ о назначении на должность ЕИО (директора, ген.директора, президента компании и пр.)
* customer_passports - Паспорт ЕИО
* customer_passportsMember - Паспорта учредителей и бенефициарных владельцев
* customer_passportsSigner - Паспорт представителя (лица, действующего по доверенности)
* customer_finReport - Бухгалтерская отчётность (годовая)
* customer_finReportQ - Бухгалтерская отчётность (последний квартал)
* customer_signerConfirmingDoc - Доверенность / Документ, подтверждающий право подписи
* customer_nonResidentDoc - Документ, подтверждающий право иностранного гражданина или лица без гражданства на пребывание (проживание) в РФ
* customer_taxForm - Налоговая декларация за отчетный период с отметкой о принятии или заверенная ЭЦП налоговым органом или копией почтовой квитанции
* customer_ledgerYear - Для Клиентов находящихся на УСН/ЕНВД - Книга доходов и расходов за последний завершенный год
* customer_shareholdersExcerpt - Выписка из реестра акционеров
* customer_premisesConfirmingDoc - Документ, подтверждающий право собственности или аренды помещения
* customer_contractRegistry - Реестр исполненных контрактов
* customer_orderCard51 - Карточка 51 счета за 6 полных календарных месяцев, предшествующих текущей дате (не отчетной)
* customer_osv58 - ОСВ по 58 счету за прошедшие 12 месяцев от последней отчетной даты в разрезе субсчетов контрагентов с указанием ИНН/доходов или расходов (если применимо) и субсчетов
* customer_osv60 - ОСВ по 60 счету за прошедшие 12 месяцев от последней отчетной даты в разрезе субсчетов контрагентов с указанием ИНН/доходов или расходов (если применимо) и субсчетов
* customer_osv62 - ОСВ по 62 счету за прошедшие 12 месяцев от последней отчетной даты в разрезе субсчетов контрагентов с указанием ИНН/доходов или расходов (если применимо) и субсчетов
* customer_osv66 - ОСВ по 66 счету за прошедшие 12 месяцев от последней отчетной даты в разрезе субсчетов контрагентов с указанием ИНН/доходов или расходов (если применимо) и субсчетов
* customer_osv67 - ОСВ по 67 счету за прошедшие 12 месяцев от последней отчетной даты в разрезе субсчетов контрагентов с указанием ИНН/доходов или расходов (если применимо) и субсчетов
* customer_osv76 - ОСВ по 76 счету за прошедшие 12 месяцев от последней отчетной даты в разрезе субсчетов контрагентов с указанием ИНН/доходов или расходов (если применимо) и субсчетов
* customer_osv91 - ОСВ по 91 счету за прошедшие 12 месяцев от последней отчетной даты в разрезе субсчетов контрагентов с указанием ИНН/доходов или расходов (если применимо) и субсчетов
* customer_osvCommon - Общая ОСВ по счетам и субсчетам с указанием наименования субсчетов за прошедшие 12 месяцев от последней отчетной даты
* customer_otherDocs - Прочие документы клиента
* bg_bill - Счет на оплату вознаграждения за выдачу банковской гарантии
* bg_contract - Гарантийный договор
* bg_guaranteeDraft - Макет БГ
* bg_guaranteeDraftPaid - Платный макет БГ
* bank_principalForm - Анкета клиента по форме банка
* bg_finReportGenerated - Бухотчетность. Сгенерированный xlsx на основании данных БО, отправленных в анкете
* bg_persDataConsent - Согласие на обработку персональных данных
* bg_application - Заявка на банковскую гарантию
* bg_edoRequest - Заявление о присоединении
* bg_woAppLot - Справка об отсутствии необходимости одобрения сделки
* bg_rulesAgreement - Заявление о присоединении к правилам предоставления продукта
* bg_agentRelationAgreement - Согласие на работу с агентом
* bg_declarationBenOwner - Декларация бенефициарного владельца
* bg_limitRequest - Заявление на установление лимита
* bg_account51analysis - Анализ 51 счета в разрезе банков
* bg_passports - Верифицированные банком паспорта ЕИО, подписанта, бенефициарных владельцев
* bg_finReport - Верифицированная банком бухгалтерская отчётность (годовая)
* bg_finReportQ - Верифицированная банком бухгалтерская отчётность (последний квартал)
* otherOrderDocs - Прочие документы по заявке
Вид банковской гарантии:
* participation - На участие в торгах
* execution - На исполнение обязательств по контракту
* returnAdvance - На возврат аванса
* period - На обеспечение гарантийных обязательств
Данные отчетности. Ассоциативный массив, где ключ - период отчетности в формате гггг-мм (гггг - год, мм - последний месяц квартала). Значение массива - объект FinReport
Должность:
* director - Директор,
* ceo - Генеральный директор,
* actingCeo - ВРИО Генерального директора,
* president - Президент,
* other - значение из поля otherPosition
directorceoactingCeopresidentother
otherPosition
string
опц.
Иная должность. Обязательно, если в поле position указано other
Штат сотрудников (общая численность сотрудников), чел.
wageFund
number
опц.
Фонд оплаты, год, руб.
staffDebts
number
опц.
Задолженность по зарплате, руб.
StatusResponseobject
Свойство
Тип
Обязат.
Описание
orderId
string
опц.
Идентификатор заявки
Пример: AWEs186CU22kNAUZhN1R
orderNumber
string
опц.
Номер заявки
Пример: 000042
taskDefinitionKey
string
опц.
Ключ задачи:
* AGENT_FILL_APPLICATION - На заполнении
* BANK_REVIEW_APPLICATION - На проверке в банке
* CLIENT_SIGN_QUESTIONNAIRE - На подписании анкеты
* AGENT_REWORK - На доработке
* BANK_MAKING_DECISION - На рассмотрении в банке
* CLIENT_SIGN_DOCS - На подписании документов
* AGENT_APPROVE - Одобрено, согласовать текст и параметры гарантии
* CLIENT_SIGN_CONTRACT - На подписании договора при выдаче
* BANK_ISSUING - Оформление документов в банке
Пример: [{'code': 'SEND_TO_BANK', 'text': 'Отправить в Банк', 'isCommentRequired': False}, {'code': 'REJECT', 'text': 'Отказ от гарантии', 'isCommentRequired': True}]
taskName
string
опц.
Наименование текущей задачи агента
Пример: Доработать заявку, приложить документы
url
string
опц.
Ссылка для дальнейших действий
Пример: http://qwe.asd
orderStatus
string
опц.
Статус заявки:
* InProcess - в процессе
* RejectedByBank - отказ
* RejectedByAgent - клиент отказался от гарантии
* Executed - гарантия предоставлена банком
* PendingAgent - ожидает ответа от Агента
* PendingClient - ожидает действий клиента
* Failed - Процесс невозможно закончить
Перечень типов документов, в которые можно загружать файлы по заявке. Колонка multiple указывает, может ли доктайп хранить несколько файлов одновременно.
Доктайп
Сущность
Название
multiple
customer_charter
customer
Устав юридического лица
✓
customer_contractRegistry
customer
Реестр исполненных контрактов
✓
customer_eioAuthorizingDoc
customer
Решение и/или приказ о назначении на должность ЕИО (директора, ген.директора, президента компании и пр.)
—
customer_finReport
customer
Бухгалтерская отчётность (годовая)
✓
customer_finReportQ
customer
Бухгалтерская отчётность (последний квартал)
✓
customer_ledgerYear
customer
Для Клиентов находящихся на УСН/ЕНВД - Книга доходов и расходов за последний завершенный год
—
customer_nonResidentDoc
customer
Документ, подтверждающий право иностранного гражданина или лица без гражданства на пребывание (проживание) в РФ
✓
customer_orderCard51
customer
Карточка 51 счета за 6 полных календарных месяцев, предшествующих текущей дате (не отчетной)
✓
customer_osv58
customer
ОСВ по 58 счету за прошедшие 12 месяцев
✓
customer_osv60
customer
ОСВ по 60 счету за прошедшие 12 месяцев
✓
customer_osv62
customer
ОСВ по 62 счету за прошедшие 12 месяцев
✓
customer_osv66
customer
ОСВ по 66 счету за прошедшие 12 месяцев
✓
customer_osv67
customer
ОСВ по 67 счету за прошедшие 12 месяцев
✓
customer_osv76
customer
ОСВ по 76 счету за прошедшие 12 месяцев
✓
customer_osv91
customer
ОСВ по 91 счету за прошедшие 12 месяцев
✓
customer_osvCommon
customer
Общая ОСВ по счетам и субсчетам
✓
customer_otherDocs
customer
Прочие документы клиента
✓
customer_passports
customer
Паспорт ЕИО
✓
customer_passportsMember
customer
Паспорта учредителей и бенефициарных владельцев
✓
customer_passportsSigner
customer
Паспорт представителя (лица, действующего по доверенности)
✓
customer_premisesConfirmingDoc
customer
Документ, подтверждающий право собственности или аренды помещения
✓
customer_shareholdersExcerpt
customer
Выписка из реестра акционеров
—
customer_signerConfirmingDoc
customer
Доверенность / Документ, подтверждающий право подписи
Справка об отсутствии необходимости одобрения сделки
—
bill
orders
Счёт
—
otherOrderDocs
orders
Прочие документы по заявке
✓
Справочник статусов заявки
Допустимые значения поля orderStatus в ответах API и коллбеках.
Код
Описание
InProcess
На стороне Банка
RejectedByBank
Отказ Банка
RejectedByAgent
Инициатор отказался от гарантии
Executed
Гарантия предоставлена банком
PendingAgent
Ожидает ответа от Агента
PendingClient
Ожидает подписания клиентом
Failed
Технический сбой
Справочник TaskDefinitionKey
Детализированный статус заявки. Колонки «Подписано Клиентом» и «Одобрено Банком» указывают, наступило ли соответствующее событие в жизненном цикле заявки.