В данном разделе описаны возможные варианты по импорту данных пользователя в его учетную запись в CASHOFF.
Доступно два варианта импорта данных:
- отправка данных напрямую в CASHOFF (push):
- синхронизация данных приложения с CASHOFF (pull)
В первом варианте приложение с помощью API напрямую добавляет пользователю необходимые данные (к примеру чеки запросом POST /receipts/add).
Во втором варианте приложение на каждого пользователя единоразово включает синхронизацию данных и в дальнейшем только запускает её. В рамках синхронизации CASHOFF отправляет запросы в сторону приложения на получения необходимых ему данных.
Если задача импорта заключается в поддержании в постоянной актуальности большого набора данных пользователя, то необходимо использовать синхронизацию. Если добавление данных единоразовое и не массовое, то может быть достаточной прямой отправки.
Оба варианта требуют наличия у пользователя профиля self-провайдера, т.к. все загруженные данные привязываются к нему. Добавления профиля описано в разделе Профили
Импорт данных напрямую
На данный момент для прямого добавления доступны только чеки, делается это запросом POST /receipts/add. Добавлять можно не только по одному чеку, но и разом списком. Каждый чек должен иметь внешний идентификатор (ext_id), который уникален в пределах всего приложения.
Импорт данных через синхронизацию
Данным способом можно импортировать банковские продукты (карты, счета, кредиты и т.п.) и операции по ним. Синхронизация запускается запросом POST /profiles/{profile_id}/update. В рамках синхронизации CASHOFF выполняет следующие запросы в сторону приложения:
- у приложения запрашивается список продуктов POST {self-provider.endpoints.accounts}
- по каждому продукту запрашивается список операций POST {self-provider.endpoints.accounts}
Адреса запросов берутся из настроек self-провайдера.
Импорт продуктов
Первым всегда идет запрос на список продуктов, т.к. уже исходя из полученных продуктов далее будут формироваться запросы на список операций. Если получение списка продуктов завершится ошибкой, то вся синхронизация остановится и получит статус ошибки.
Импорт операций
После успешного получения списка продуктов идут запросы на список операций. Синхронизация операций идет блоками, каждый блок по одному продукту (block.account_ext_id) и определенному периоду дат (block.date_from, block.date_to). Блок имеет период до 50 дней, в целом максимальная глубина запросов на выписку - 3 года. Все запросы на операции выполняются последовательно, при этом ошибки в каком-то отдельном запросе не останавливают всю синхронизацию - блок просто помечается как завершившийся ошибкой, а запросы продолжаются. Такие ошибочные блоки снова запрашиваются будущих синхронизациях, пока данные не будут успешно получены.
Для операций CASHOFF использует инкрементный подход к синхронизации данных: все блоки, которые были успешно загружены, далее больше не запрашиваются. По этому каждая следующая синхронизация запрашивает только те данные, которые не были получены в прошлые синхронизации. Это так же означает, что операции не могут быть штатно обновлены или изменены после импорта.
Это важно учесть в случае исключительных ситуаций при формировании списка операций в приложении: если список не может быть сформирован, то необходимо вернуть именно ошибку. Если вернуть "успех" с пустым списком, то CASHOFF пометит блок как успешный и больше не будет запрашивать операции по нему - операции так и не попадут в CASHOFF.
Единственное исключение из инкрементного подхода - это "холды". Под холдами понимаются операции по банковским картам, которые еще не были исполнены. Такие операции зачастую могут быть в дальнейшем отменены либо частично изменены (в частности поле details). Признак холда устанавливается через поле card_extra.is_hold. Встретив операцию в статусе холда CASHOFF подстраивает блоки выписки таким образом, чтобы повторно запросить операции вплоть до самого "старого" холда. Делает он это до тех пор, пока либо статус холда не будет снят (операция исполнена), либо запись с холдом исчезнет (операция отменена), либо будет превышен период ожидания холда (30 дней).
Для закрытых продуктов выписка запрашивается вплоть до даты закрытия, если она указана.