CASHOFF API REFERENCE (1)

Download OpenAPI specification:Download

Данный документ описывает CASHOFF API и является дополнением к документации по API.

Взаимодействие по API

Формат взаимодействия

API является REST-like, данные передаются в формате json. В качестве кодировки используется исключительно utf8.

Для работы с API приложению необходимо получить от CASHOFF данные для подключения (идентификатор и ключ).

Ключи доступа к API

Для работы с API необходимо получить от CASHOFF два значения: идентификатор сервиса (ServiceID) и секретный ключ (PrivateKey). Они необходимы для аутентификации запросов к API.

ServiceID может быть публичным, но PrivateKey секретный и не должен никуда передаваться. Для случаев, когда необходимо выполнять запросы с клиентской стороны, предусмотрен временный токен доступа к данным одного пользователя - токен сессии пользователя.

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

Выбор пользователя

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

указать заголовок co-user-id (применяется только вместе с co-auth)
указать заголовок co-session (применяется самостоятельно)

Обратные вызовы

Данное API содержит не только описание запросов к серверу CASHOFF, но и описание обратных вызовов - запросы, в которых CASHOFF вызывает сервер приложения.

У таких методов название имеет префикс "[ОВ]", а путь начинается с /callback/. Но это не тот url, который будет использоваться при вызове. Как определяется фактический url будет написано в описании запроса. В большинстве случаев предусмотрена возможность приложению самостоятельно указать желаемый полный url обратного вызова.

Каждый исходящий от CASHOFF запрос подписывается аналогично входящим, используя секретный ключ приложения. По умолчанию используется алгоритм подписи HMAC-SHA1, но его можно поменять запросом POST /settings/callback-auth.

Ссылки на изображения

Ряд сущностей сервиса включают в себя различные изображения: картинки, логотипы, иконки. Большая часть логотипов и иконок представляет собой svg файл, картинки же обычно в формате jpg.

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

Форматы дат и времени

Для указания дат и/или времени в API используются определенные стандартом OpenAPI 3 форматы. Ниже перечислены ссылки на их полное описание, а сам формат в данном документе указывается в угловых скобках рядом с типом поля, например, string <date-time>.

Дата + время. Формат date-time в том виде, как он задан в RFC 3339, section 5.6, например, 2017-07-21T17:32:28Z
Дата. Формат full-date в том виде, как он задан в RFC 3339, section 5.6, например, 2017-07-21
Время. Формат partial-time в том виде, как он задан в RFC 3339, section 5.6, например, 00:59:11

Формат ответа при ошибке

В случае какой-либо ошибки обработки запроса CASHOFF вернет ответ с http-кодом != 200, который будет иметь следующую структуру:

{
  "error": {
    "code": "invalid_auth",
    "message": "Более подробное описание ошибки"
  }
}

Поле error.code заполняется всегда и является кодом причины ошибки.

Используемые http-коды

Список используемых http-кодов и их значение:

Код	Значение
200	Запрос успешно выполнен
400	Запрос сформирован неверно
401	Запрос не авторизован. Причина может быть в отсутвии заголовков, неверном их формате или неверных данных для авторизации
403	Запрос не доступен (запрещен) для данной учетной записи API
404	Запрос ссылается на сущность, которой нет в CASHOFF
500	Внутренняя ошибка обработки запроса

Общие коды ошибок

При ошибке CASHOFF вернет структуру с кодом ошибки в поле error.code. Ниже приведет список универсальных кодов ошибок, которые могут придти в различных запросах. При этом каждый запрос может иметь свои собственные, дополнительные, коды.

Код	Значение
no_auth	Не найдены заголовки авторизации api (co-auth/co-session)
invalid_auth	Значение заголовка co-auth имеет неверный формат или значение
sign_expired	Подпись в заголовке co-auth имеет слишком старую дату и не считается верной
invalid_token	Токен сессии (co-session) неверный
invalid_co_user_id	Заголовок co-user-id указан в неверном формате
invalid_content_type	Заголовок Content-type имеет не поддерживаемое значение
invalid_body	Неправильный формат тела запроса
invalid_params	http-параметры в url запроса имеют неверный формат (в частности неверный формат значения или недопустимая комбинация
request_not_available_for_session_auth	Данный метод не поддерживает вызов через co-session
method_not_found	По данному адресу api-метода не существует
user_not_specified	Запрос требует указания пользователя (заголовки co-session/co-user-id), но он не указан
invalid_method	Запрос не поддерживает данный http-метод (к примеру GET, POST и т.п.)
internal_error	Внутренняя ошибка сервиса
not_found	Объект, который участвует в запросе, не найден
no_self_provider_profile	Запрос требует наличия профиля self-провайдера, но он не создан

Списки записей

Листание записей

Запросы, возвращающие список записей, имеют типовую структуру и состоят из следующих частей:

входные параметры limit и offset - задают соответственно количестов записей, которое нужно вернуть, и сколько записей с начала списка нужно пропустить. Через эти параметры реализуется страничный доступ к данным, к примеру: limit=10&offset=20 - получить страницу 3, где каждая страница по 10 записей.
выходные атрибуты items и total - первый содержит список элементов, второй общее их количество (с учетом фильтров, но без учета limit). Атрибут total указывается только для первой страницы (offset=0), для остальных он не рассчитывается и не возвращается.

Сортировка записей

Для ряда запросов, возвращающих список записей, доступна сортировка. Поле, по которому требуется сортировать, указывается в GET параметре order_by. Список сортируемых полей перечисляется в описании order_by запросов, если такие поля есть.

По умолчанию сортировка будет по возрастанию. Для того, что бы отсортировать по убыванию, нужно к названию поля добавить префикс -, к примеру order_by=-created.

Фильтрация записей

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

Для фильтрации нужно указать желаемое значение поля в GET параметре с именем этого поля. При этом значение должно быть того же типа, что и поле. Например, фильтрация по id: id=10.

К названию поля можно через __ добавить операторы. Доступны следующие операторы:

gte: >=
gt: >
lte: <=
lt: <
in: вхождение в список. Значением параметра должно быть перечисление через запятую возможных значений поля.

Примеры фильтрации с операторами: date__gte=2019-02-21, id__in=1,2,3

В одном запросе может быть указано несколько фильтров. В таком случае они будут объединены через логическое И. К примеру фильтр date__gte=2019-01-01&date__lt=2019-02-01 означает "вернуть записи с полем date в пределах января 2019".

Пользователи

Список пользователей

Authorizations:

ApiAuth(ApiAuthUserID)

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.

Responses

Response Schema: application/json

required	Array of objects (User) Список пользователей
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"id": 1,
"created": "2019-08-24T14:15:22Z",
"name": "string",
"email": "test@mail.ru",
"ext_id": "user1",
"is_cashback_enabled": true
}
],
"total": 10
}

Добавить нового пользователя

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

Код	Значение
users_limit_exceeded	Достигнуто максимальное количество доступных к созданию пользователей.

Authorizations:

ApiAuth

Request Body schema: application/json

ext_id	string <= 64 characters Внешний идентификатор пользователя. Если заполняется, то должен быть уникален.
email	string Email пользователя
enable_cashback	boolean Default: false Включить кешбек
	object Добавить пользователю при создании профиль self-провайдера

Responses

Response Schema: application/json

id	number Идентификатор пользователя
created required	string <date-time> Дата создания
name required	string Внутреннее имя (username) пользователя
email	string Email пользователя
ext_id	string <= 64 characters Идентификатор пользователя во внешней системе
is_cashback_enabled	boolean Функционал кешбека включен для данного пользователя
	object (Profile) Профиль провайдера данных

Request samples

Payload

Content type

application/json

{"ext_id": "f5ff0b59-2f9f-47bb-9e3d-d6cd4f9ff537",
"email": "test@mail.ru",
"enable_cashback": false,
"provider_profile": {"add": true,
"ext_id": "f5ff0b59-2f9f-47bb-9e3d-d6cd4f9ff537"
}
}

Response samples

200

Content type

application/json

{"id": 1,
"created": "2019-08-24T14:15:22Z",
"name": "string",
"email": "test@mail.ru",
"ext_id": "user1",
"is_cashback_enabled": true,
"provider_profile": {"created": "2019-01-20T14:07:44Z",
"changed": "2019-08-24T14:15:22Z",
"id": 10,
"user_id": 3,
"provider": {"id": 5,
"key": "tcs",
"name": "Тинькофф",
"logo": "https://cashoff.ru/static/image/logo/tcs.svg",
"type": "bank"
},
"session": {"key": "b51b417f218b48c3968cbb7b2e0d753b",
"status": "ok"
},
"status": "ok"
}
}

Информация по пользователю

Authorizations:

ApiAuthUserSession

path Parameters

user_id

required

string

Идентификатор пользователя

Responses

Response Schema: application/json

id	number Идентификатор пользователя
created required	string <date-time> Дата создания
name required	string Внутреннее имя (username) пользователя
email	string Email пользователя
ext_id	string <= 64 characters Идентификатор пользователя во внешней системе
is_cashback_enabled	boolean Функционал кешбека включен для данного пользователя

Response samples

200

Content type

application/json

{"id": 1,
"created": "2019-08-24T14:15:22Z",
"name": "string",
"email": "test@mail.ru",
"ext_id": "user1",
"is_cashback_enabled": true
}

Обновить данные пользователя

Authorizations:

ApiAuthUserSession

path Parameters

user_id

required

string

Идентификатор пользователя

Request Body schema: application/json

ext_id	string <= 64 characters Внешний идентификатор пользователя. Если заполняется, то должен быть уникален.
email	string Email пользователя
provider_profile_update_ext_id	boolean Default: true Обновить `ext_id` профиля self-провайдера тем же значением, что указано для пользователя.

Responses

Response Schema: application/json

id	number Идентификатор пользователя
created required	string <date-time> Дата создания
name required	string Внутреннее имя (username) пользователя
email	string Email пользователя
ext_id	string <= 64 characters Идентификатор пользователя во внешней системе
is_cashback_enabled	boolean Функционал кешбека включен для данного пользователя

Request samples

Payload

Content type

application/json

{"ext_id": "f5ff0b59-2f9f-47bb-9e3d-d6cd4f9ff537",
"email": "test@mail.ru",
"provider_profile_update_ext_id": true
}

Response samples

200

Content type

application/json

{"id": 1,
"created": "2019-08-24T14:15:22Z",
"name": "string",
"email": "test@mail.ru",
"ext_id": "user1",
"is_cashback_enabled": true
}

Удалить пользователя

Удаление приводит к полной потере всех данных пользователя.

Если пользователь с включенным функционалом кешбека, то удалить его нелья - можно только деактивировать.

Authorizations:

ApiAuthUserSession

path Parameters

user_id

required

string

Идентификатор пользователя

Responses

Деактивировать пользователя

Данные деактивированного пользователя становятся не доступными, но могут оставаться в сервисе.

Данная операция не обратима, т.е. "активировать" обратно нельзя.

Authorizations:

ApiAuth

path Parameters

user_id

required

string

Идентификатор пользователя

Responses

Сессии пользователей

Список сессий

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.

Responses

Response Schema: application/json

required	Array of objects (Session) Список сессий
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"session_key": "412b8963e825403ebef642e2b4871a6f",
"user_id": 15
}
],
"total": 10
}

Выпустить новую сессию

Authorizations:

(ApiAuthUserID)

Request Body schema: application/json

ttl	number > 0 Default: 1440 Время жизни сессии, в минутах

Responses

Response Schema: application/json

session_key	string Ключ сессии
user_id	number Идентификатор пользователя
valid_until	string <date-time> Срок жизни сессии

Request samples

Payload

Content type

application/json

{"ttl": 1440
}

Response samples

200

Content type

application/json

{"session_key": "412b8963e825403ebef642e2b4871a6f",
"user_id": 15
}

Информация по сессии

Authorizations:

ApiAuthUserSession

path Parameters

session_key

required

string

Ключ сессии

Responses

Response Schema: application/json

session_key	string Ключ сессии
user_id	number Идентификатор пользователя
valid_until	string <date-time> Срок жизни сессии

Response samples

200

Content type

application/json

{"session_key": "412b8963e825403ebef642e2b4871a6f",
"user_id": 15
}

Удалить сессию

Authorizations:

ApiAuthUserSession

path Parameters

session_key

required

string

Ключ сессии

Responses

Продукты

Список продуктов

Управление списком:

profile_id: фильтрация

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.
ops_payment_rub	bool Для продукта доступен рублевый платеж. Если признак доступности у продукта не заполнен ("не известно"), то он не подпадает ни под `true`, ни под `false`.

Responses

Response Schema: application/json

required	Array of objects (AccountProcessed) Список продуктов
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"id": 6347,
"profile_id": 7347,
"group_id": 0,
"ext_id": "f5ff0b59-2f9f-47bb-9e3d-d6cd4f9ff537",
"type": "account",
"amount": 7400,
"currency": "usd",
"name": "Карта Visa",
"number": "**** 5789",
"bank_bic": "*****5411",
"date_open": "2019-08-24",
"date_close": "2019-08-24",
"status": "blocked",
"owner": {"type": "sme",
"name": "ООО \"Рога и копыта\"",
"inn": "7710140679",
"kpp": "773401001",
"ogrn": "1053600591197",
"email": "user@example.com",
"phone": "8916*****20"
},
"swift": {"beneficiary": {"name": "IP Chepaev Evgeniy Vladimirovich",
"institution": "MODULBANK",
"swift": "MODBRU22",
"iban": "IS140159260076545510730339"
},
"correspondent": {"bank": "RAIFFEISEN BANK INTERNATIONAL AG",
"swift": "RZBAATWWXXX",
"account": "70-55.090.237"
}
},
"card_extra": {"account_id": "acc1",
"base_card_id": "card1",
"type": "credit",
"client_funds": 0,
"overdraft": 10000,
"payment_system": "visa",
"premium_class": "classic"
},
"available_ops": {"payment_rub": true
}
}
],
"total": 10
}

Информация по продукту

Authorizations:

(ApiAuthUserID) UserSession

path Parameters

account_id

required

string

Идентификатор продукта

Responses

Response Schema: application/json

id required	number Идентификатор продукта
profile_id	number Идентификатор профиля (если продукт импортирован из провайдера)
group_id	number Идентификатор группы (если продукт включен в группу). Является идентификатором продукта с type = `group`.
ext_id	string Внешний идентификатор продукта. Всегда заполняется для импортируемых из провайдеров продуктов и не заполняется для тех, что ведутся внутри CASHOFF (в частности type = `cash`, сгенерированные `group`).
type required	string Enum: "account" "card" "credit" "deposit" "cash" "cell" "group" "loyalty_card" "wallet" Тип продукта: `account` - счет `card` - банковская карта `credit` - кредит `deposit` - депозит (вклад) `cash` - наличный кошелёк (внутренняя сущность CASHOFF) `cell` - номер мобильного оператора `group` - группа карт (внутренняя сущность CASHOFF) `loyalty_card` - карта лояльности (магазины) `wallet` - электронный кошелёк
amount required	number Баланс продукта для карт не включает овердрафт, только собственные средства для кредитов указывается остаток к погашению может быть отрицательным (задолженность)
currency required	string Валюта продукта в виде буквенного ISO кода в нижнем регистре.
name required	string Наименование продукта
number	string Номер продукта (счёта, карты, телефона и т.д.). Для ряда типов (в частности банковских карт) - маскированный. Не заполняется для type = `group`, `cash`.
bank_bic	string БИК банка
date_open	string <date> Дата открытия
date_close	string <date> Дата закрытия. Может быть как фактическая (для закрытых продуктов), так и плановая (к примеру для карт).
status	string Default: "open" Enum: "blocked" "closed" "open" "overdue" "absent" Статус продукта `blocked` - заблокирован (для карт) `closed` - закрыт `open` - открыт `overdue` - просрочен (для кредитов) `absent` - отсутсвует во внешней системе (для сохраненных в cashoff продуктов)
	object (ProductOwner) Информация о владельце продукта.
	object (SwiftAccountExtra) SWIFT реквизиты
	object (AccountCardExtraProcessed) Дополнительная информация по картам
	object Доступные операции по продукту.

Response samples

200

Content type

application/json

{"id": 6347,
"profile_id": 7347,
"group_id": 0,
"ext_id": "f5ff0b59-2f9f-47bb-9e3d-d6cd4f9ff537",
"type": "account",
"amount": 7400,
"currency": "usd",
"name": "Карта Visa",
"number": "**** 5789",
"bank_bic": "*****5411",
"date_open": "2019-08-24",
"date_close": "2019-08-24",
"status": "blocked",
"owner": {"type": "sme",
"name": "ООО \"Рога и копыта\"",
"inn": "7710140679",
"kpp": "773401001",
"ogrn": "1053600591197",
"email": "user@example.com",
"phone": "8916*****20"
},
"swift": {"beneficiary": {"name": "IP Chepaev Evgeniy Vladimirovich",
"institution": "MODULBANK",
"swift": "MODBRU22",
"iban": "IS140159260076545510730339"
},
"correspondent": {"bank": "RAIFFEISEN BANK INTERNATIONAL AG",
"swift": "RZBAATWWXXX",
"account": "70-55.090.237"
}
},
"card_extra": {"account_id": "acc1",
"base_card_id": "card1",
"type": "credit",
"client_funds": 0,
"overdraft": 10000,
"payment_system": "visa",
"premium_class": "classic"
},
"available_ops": {"payment_rub": true
}
}

Удалить продукт

Authorizations:

ApiAuthUserSession

path Parameters

account_id

required

string

Идентификатор продукта

Responses

Операции

Список операций

Управление списком:

created: сортировка и фильтрация
changed: сортировка и фильтрация
id: фильтрация
account_id: фильтрация
date: фильтрация

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.

Responses

Response Schema: application/json

required	Array of objects (TransactionProcessed) Список операций
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"created": "2019-08-24T14:15:22Z",
"changed": "2019-08-24T14:15:22Z",
"id": 3569,
"account_id": 672,
"doc_id": "10",
"merchant": {"id": 523,
"name": "Перекресток",
"generic": false,
"logo": "https://cashoff.ru/static/media/merchants_logo/PE8W7FDF_36.svg"
},
"category": {"id": 1,
"name": "Продукты питания",
"for_consumer": true,
"for_sme": true
},
"ext_id": "d275ab5a-43ef-4175-ac37-a0e708f51db5",
"amount": 50,
"currency": "usd",
"trans_amount": {"value": 10,
"currency": "usd"
},
"date": "2019-08-24",
"date_execution": "2019-08-24",
"time": "15:44:30",
"details": "STARBUCKS MOSKVA RU S5306",
"card_extra": {"is_hold": false,
"mcc": "9222",
"mcc_description": "Штрафы",
"pos_id": "pos1234",
"merchant_id": "merchant1234"
},
"geo": {"lat": 56.857995,
"lng": 35.898965,
"city": "string",
"country": "string"
},
"payer": {"name": "АО \"ТИНЬКОФФ БАНК\"",
"inn": "7710140679",
"kpp": "773401001",
"account_number": "47426810000000022664",
"bank_name": "АО \"ТИНЬКОФФ БАНК\"",
"bank_bic": "044525974",
"bank_corr_number": "30101810145250000974"
},
"receiver": {"name": "АО \"ТИНЬКОФФ БАНК\"",
"inn": "7710140679",
"kpp": "773401001",
"account_number": "47426810000000022664",
"bank_name": "АО \"ТИНЬКОФФ БАНК\"",
"bank_bic": "044525974",
"bank_corr_number": "30101810145250000974"
},
"tax": {"tax101": "01",
"tax104": "18210101040011000110",
"tax105": "45908000",
"tax106": "ТП",
"tax107": "МС.10.2018",
"tax108": "0",
"tax109": "0",
"tax110": "0"
}
}
],
"total": 10
}

Получить данные операции

Authorizations:

ApiAuthUserSession

path Parameters

trans_id

required

string

Responses

Response Schema: application/json

created required	string <date-time> Дата создания
changed required	string <date-time> Дата последнего изменения
id required	number Идентификатор операции
account_id required	number Идентификатор аккаунта
doc_id	string Номер/идентификатор документа платежа, под которым операция зарегистрирована в системе провайдера. Может быть не уникальным или уникальным ограничено (например в пределах календарного года). На данный момент только для операций юридических лиц.
	object (Merchant) Мерчант (торговая точка или постовщик услуг).
	object (TransactionSubCategory) Подкатегория
ext_id	string Идентификатор операции во внешней системе. Уникальность должна быть не ниже "уникален в пределах продукта", иначе не заполняется.
amount required	number Сумма
currency required	string (currency) Буквенный ISO код валюты, в нижнем регистре
	object Сумма в валюте операции. Указывается в случае, если отличается от валюты продукта.
date required	string <date> Дата совершения (заведения) операции
date_execution	string <date> Дата фактического исполнения операции. Для карт это дата исполнения по счету.
time	string Время совершения операции
details required	string Описание операции
	object Дополнительные поля, специфичные для операций по картам
	object Географическое место совершения операции
	object (PaymentDetails) Реквизиты платежа
	object (PaymentDetails) Реквизиты платежа
	object (TaxFields) Значение полей рублевого платежа в бюджет. Номер в название поля соответсвуют номеру поля рублевого платежа. Значение - в том же формате, что указывается в платежном документе, без пробелов.

Response samples

200

Content type

application/json

{"created": "2019-08-24T14:15:22Z",
"changed": "2019-08-24T14:15:22Z",
"id": 3569,
"account_id": 672,
"doc_id": "10",
"merchant": {"id": 523,
"name": "Перекресток",
"generic": false,
"logo": "https://cashoff.ru/static/media/merchants_logo/PE8W7FDF_36.svg"
},
"category": {"id": 1,
"name": "Продукты питания",
"for_consumer": true,
"for_sme": true
},
"ext_id": "d275ab5a-43ef-4175-ac37-a0e708f51db5",
"amount": 50,
"currency": "usd",
"trans_amount": {"value": 10,
"currency": "usd"
},
"date": "2019-08-24",
"date_execution": "2019-08-24",
"time": "15:44:30",
"details": "STARBUCKS MOSKVA RU S5306",
"card_extra": {"is_hold": false,
"mcc": "9222",
"mcc_description": "Штрафы",
"pos_id": "pos1234",
"merchant_id": "merchant1234"
},
"geo": {"lat": 56.857995,
"lng": 35.898965,
"city": "string",
"country": "string"
},
"payer": {"name": "АО \"ТИНЬКОФФ БАНК\"",
"inn": "7710140679",
"kpp": "773401001",
"account_number": "47426810000000022664",
"bank_name": "АО \"ТИНЬКОФФ БАНК\"",
"bank_bic": "044525974",
"bank_corr_number": "30101810145250000974"
},
"receiver": {"name": "АО \"ТИНЬКОФФ БАНК\"",
"inn": "7710140679",
"kpp": "773401001",
"account_number": "47426810000000022664",
"bank_name": "АО \"ТИНЬКОФФ БАНК\"",
"bank_bic": "044525974",
"bank_corr_number": "30101810145250000974"
},
"tax": {"tax101": "01",
"tax104": "18210101040011000110",
"tax105": "45908000",
"tax106": "ТП",
"tax107": "МС.10.2018",
"tax108": "0",
"tax109": "0",
"tax110": "0"
}
}

Удалить операцию

Authorizations:

ApiAuthUserSession

path Parameters

trans_id

required

string

Responses

Чеки

Список чеков

Управление списком:

id: фильтрация
ext_id: фильтрация
created: фильтрация
user_added_at: фильтрация
date: фильтрация
cashback_level: фильтрация

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.

Responses

Response Schema: application/json

required	Array of objects (ReceiptProcessed) Список чеков
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"id": 45,
"ext_id": "c3815ffcc52c49118ebcb4e4e09444b6",
"created": "2019-08-24T14:15:22Z",
"user_id": 6500,
"user_added_at": "2019-08-24T14:15:22Z",
"account_id": 350,
"profile_id": 470,
"date": "2019-08-24",
"time": "15:44:30",
"amount": 238.16,
"currency": "usd",
"fn": "8710000101444681",
"fd": "136928",
"fpd": "1133038423",
"payment_type": "cash",
"discount": 10,
"shop_description": "ЗАКРЫТОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО \"ТОРГОВЫЙ ДОМ \"ПЕРЕКРЕСТОК\"",
"goods": [{"name": "ДОКТОР МОМ РАСТ ПАСТИЛКИ ОТ КАШЛЯ АНАНАС №20",
"amount": 248.16,
"quantity": 2,
"rate": 124.08,
"id": 678,
"ext_id": "1314600f2b6f460f91cb11da294993b5",
"category_id": 0
}
],
"merchant_id": 0,
"transaction_id": 0,
"cashback_level": "base",
"unavailable_reason": "already_processed",
"cashback": [{"id": 1,
"offer_id": 405,
"user_id": 6500,
"amount": 5,
"status": "received",
"received_at": "2019-08-24T14:15:22Z",
"withdrawal_id": 0,
"items": [{"receipt_id": 0,
"receipt_item_id": 678,
"receipt_item_ext_id": "1314600f2b6f460f91cb11da294993b5"
}
]
}
],
"missing_cashback": [{"offer_id": 2357,
"items": [{"receipt_id": 0,
"receipt_item_id": 678,
"receipt_item_ext_id": "1314600f2b6f460f91cb11da294993b5"
}
],
"reason_code": "budget_exhausted"
}
]
}
],
"total": 10
}

Загрузить чек по qr-коду

Импортировать в систему чек с помощью qr кода.

Коды печатаются на чеках и данный метод принимает на вход результат сканирования в виде строки.

Чеки загружаются не синхронно, по этому после первичной проверки метод вернет запись о загрузке (pending_receipt), по которой можно отследить статус загрузки чека.

Authorizations:

(ApiAuthUserID) UserSession

Request Body schema: application/json

qr_data

required

string

Данные qr кода с чека в виде текста.
Пример: t=20190215T1239&s=1405.00&fn=9286000100050946&i=6541&fp=807042090&n=1

Responses

Response Schema: application/json

One of

status

required

string (receipt_import_status)

Enum: "loaded" "invalid_format" "invalid" "exist" "accepted"

Статус импорта чека.

loaded: успешно загружен (вернет receipt)
invalid_format: формат чека не соответсвует формату ФНС
invalid: данные чека не верны
exist: чек уже загружен данным пользователем (вернет существующий receipt)
accepted: чек добавлен в загружаемые и будет загружен в фоне (вернет pending_receipt)

object (ReceiptProcessed)

Чек

Request samples

Payload

Content type

application/json

{"qr_data": "t=20190215T1239&s=1405.00&fn=9286000100050946&i=6541&fp=807042090&n=1"
}

Response samples

200

Content type

application/json

{"status": "loaded",
"pending_receipt": {"id": 45,
"add_date": "2019-02-15T11:14:28Z",
"amount": "123.50",
"date": "2019-02-05",
"status": "loaded",
"receipt_id": 6347
}
}

Загрузить чек по фотографии

Импортировать в систему чек с помощью его фотографии.

Фотография отправляется в теле запроса в виде бинарных данных.

Чек импортируется по реквизитам, по этому на фото должны быть чётко видны либо реквизиты чека, либо qr код.

Фото должно быть в формате jpeg.

Authorizations:

(ApiAuthUserID) UserSession

Request Body schema: image/jpeg

string <binary>

Responses

Response Schema: application/json

One of

status

required

string (receipt_import_status)

Enum: "loaded" "invalid_format" "invalid" "exist" "accepted"

Статус импорта чека.

loaded: успешно загружен (вернет receipt)
invalid_format: формат чека не соответсвует формату ФНС
invalid: данные чека не верны
exist: чек уже загружен данным пользователем (вернет существующий receipt)
accepted: чек добавлен в загружаемые и будет загружен в фоне (вернет pending_receipt)

object (ReceiptProcessed)

Чек

Response samples

200

Content type

application/json

{"status": "loaded",
"pending_receipt": {"id": 45,
"add_date": "2019-02-15T11:14:28Z",
"amount": "123.50",
"date": "2019-02-05",
"status": "loaded",
"receipt_id": 6347
}
}

Получить данные чека

Authorizations:

ApiAuthUserSession

path Parameters

receipt_id

required

string

Идентификатор чека

Responses

Response Schema: application/json

id required	number Идентификатор чека
ext_id	string <= 255 characters Внешний идентификатор чека
created required	string <date-time> Дата добавления чека
user_id required	number Идентификатор пользователя
user_added_at	string <date-time> Дата добавления данных о чеке пользователем. при добавлении через QR - дата добавления QR при добавлении через фотографию - дата добавления фотографии при добавлении через провайдера - дата импорта
account_id	number Идентификатор продукта, к которому привязан чек
profile_id	number Идентификатор профиля, по которому загружен чек
date required	string <date> Дата совершения покупки
time	string Время совершения покупки
amount required	number Общая сумма чека
currency required	string (currency) Буквенный ISO код валюты, в нижнем регистре
fn	string Заводской номер (ФН)
fd	string Номер фискального документа (ФД)
fpd	string Фискальный признак документа (ФПД)
payment_type required	string Enum: "cash" "ecash" Тип платежа (если известен) cash: покупка оплачена наличностью ecash: покупка оплачена безналично
discount	number Сумма скидки по чеку (amount указан с учетом скидки)
shop_description	string <= 255 characters Описание/название магазина
required	Array of objects (ReceiptItemProcessed) Список товарных позиций чека
merchant_id	number Идентификатор мерчанта
transaction_id	number Идентификатор привязанной к чеку операции
cashback_level	string Enum: "unavailable" "base" "with_bonus" Уровень кешбека: `unavailable` - кешбек по данному чеку не доступен `base` - по данному чеку возможен базовый кешбек `with_bonus` - по данному чеку кешбек получает бонус за операцию
unavailable_reason	string Enum: "cashback_disabled" "shop_is_banned" "already_processed" "user_agreement_not_accepted" "admin" "added_too_late" "receipts_daily_limit_exhausted" Причина, по которой кешбэк в чеке полностью недоступен: `cashback_disabled` - Кешбэк не доступен пользователю либо персонально, либо на площадке в целом `shop_is_banned` - Покупка совершена в магазине, чеки из которого не участвуют в программе кешбэка `already_processed` - Кешбэк по чеку с такими реквизитами уже обработан на другом пользователе `user_agreement_not_accepted` - Пользователь не принял оферту по использованию сервиса кешбэка `admin` - По решению администратора `added_too_late` - Пользователь добавил чек позднее, чем это задано настройками антифрода на площадке `receipts_daily_limit_exhausted` - Исчерпан лимит чеков за одну дату, задаваемый настройками антифрода на площадке Присутствует только в том случае, если `cashback_level=unavailable`. Набор причин может дополняться со временем. Также некоторые причины могут быть из него удалены в будущем.
	Array of objects (CashbackAccrual) Начисленный кешбек по чеку
	Array of objects (MissingCashback) Список причин, из-за которых кешбэк не был начислен по акционным товарным позициям.

Response samples

200

Content type

application/json

{"id": 45,
"ext_id": "c3815ffcc52c49118ebcb4e4e09444b6",
"created": "2019-08-24T14:15:22Z",
"user_id": 6500,
"user_added_at": "2019-08-24T14:15:22Z",
"account_id": 350,
"profile_id": 470,
"date": "2019-08-24",
"time": "15:44:30",
"amount": 238.16,
"currency": "usd",
"fn": "8710000101444681",
"fd": "136928",
"fpd": "1133038423",
"payment_type": "cash",
"discount": 10,
"shop_description": "ЗАКРЫТОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО \"ТОРГОВЫЙ ДОМ \"ПЕРЕКРЕСТОК\"",
"goods": [{"name": "ДОКТОР МОМ РАСТ ПАСТИЛКИ ОТ КАШЛЯ АНАНАС №20",
"amount": 248.16,
"quantity": 2,
"rate": 124.08,
"id": 678,
"ext_id": "1314600f2b6f460f91cb11da294993b5",
"category_id": 0
}
],
"merchant_id": 0,
"transaction_id": 0,
"cashback_level": "base",
"unavailable_reason": "already_processed",
"cashback": [{"id": 1,
"offer_id": 405,
"user_id": 6500,
"amount": 5,
"status": "received",
"received_at": "2019-08-24T14:15:22Z",
"withdrawal_id": 0,
"items": [{"receipt_id": 0,
"receipt_item_id": 678,
"receipt_item_ext_id": "1314600f2b6f460f91cb11da294993b5"
}
]
}
],
"missing_cashback": [{"offer_id": 2357,
"items": [{"receipt_id": 0,
"receipt_item_id": 678,
"receipt_item_ext_id": "1314600f2b6f460f91cb11da294993b5"
}
],
"reason_code": "budget_exhausted"
}
]
}

Удалить чек

Authorizations:

ApiAuthUserSession

path Parameters

receipt_id

required

string

Идентификатор чека

Responses

Импорт чеков в систему

Позволяет добавить чеки в систему. Требует наличия у пользователя профиля self-профайдера.

Authorizations:

(ApiAuthUserID)

Request Body schema: application/json

required

Array of objects (ReceiptImport)

Список чеков для добавления

Responses

Response Schema: application/json

required	Array of objects Список чеков, которые уже есть в сервисе CASHOFF
required	Array of objects Список чеков, которые не были импортированы из-за ошибок в данных

Request samples

Payload

Content type

application/json

{"receipts": [{"date": "2019-08-24",
"time": "15:44:30",
"amount": 238.16,
"currency": "usd",
"fn": "8710000101444681",
"fd": "136928",
"fpd": "1133038423",
"payment_type": "cash",
"discount": 10,
"shop_description": "ЗАКРЫТОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО \"ТОРГОВЫЙ ДОМ \"ПЕРЕКРЕСТОК\"",
"shop_inn": "7728029110",
"shop_address": "398026, 48, г. Липецк, ул. Героя России Эдуарда Белана, б/н",
"user_added_at": "2019-08-24T14:15:22Z",
"user_added_city": "string",
"ext_id": "c3815ffcc52c49118ebcb4e4e09444b6",
"goods": [{"name": "ДОКТОР МОМ РАСТ ПАСТИЛКИ ОТ КАШЛЯ АНАНАС №20",
"amount": 248.16,
"quantity": 2,
"rate": 124.08,
"ext_id": "1314600f2b6f460f91cb11da294993b5"
}
]
}
]
}

Response samples

200

Content type

application/json

{"duplicates": [{"ext_id": "c3815ffcc52c49118ebcb4e4e09444b6",
"duplicated_ext_id": "f2dc39891e0c46f5a4c5392e1bf2fab4"
}
],
"fails": [{"ext_id": "c3815ffcc52c49118ebcb4e4e09444b6",
"error_message": "В чеке должно быть не менее одной товарной позиции."
}
]
}

Список загружаемых чеков

Загружаемый чек - это отметка о загрузке пераданного qr кода.

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

После успешной загрузки данных чека в запись добавляется идентификатор загруженного чека.

Управление списком:

id: фильтрация
add_date: фильтрация
date: фильтрация
receipt_id: фильтрация

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.

Responses

Response Schema: application/json

	Array of objects (PendingReceipt) Список загружаемых чеков
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"id": 45,
"add_date": "2019-02-15T11:14:28Z",
"amount": "123.50",
"date": "2019-02-05",
"status": "loaded",
"receipt_id": 6347
}
],
"total": 10
}

Информация по загружаемому чеку

Authorizations:

ApiAuthUserSession

path Parameters

pending_id

required

string

Идентификатор записи

Responses

Response Schema: application/json

id required	string Идентификатор
qr_data required	string Данные qr кода
add_date required	string <date-time> Дата добавления чека в систему
amount required	string Сумма покупки
date required	string <date-time> Дата покупки
status required	string Enum: "loading" "loaded" "timed_out" "invalid" Статус загрузки `loading`: чек загружается `loaded`: чек загружен, его идентификатор указан в поле `receipt_id` `timed_out`: данные чека не удалось получать за предельное время загрузки чека, попытки загрузить прекращены `invalid`: чек не валиден, по нему не могут быть загружены данные
receipt_id	number Идентификатор чека, если он уже загружен.

Response samples

200

Content type

application/json

{"id": 45,
"add_date": "2019-02-15T11:14:28Z",
"amount": "123.50",
"date": "2019-02-05",
"status": "loaded",
"receipt_id": 6347
}

Удалить загружаемый чек

Если чек уже загружен, то удаление записи не приводит к удалению самого чека.

Authorizations:

ApiAuthUserSession

path Parameters

pending_id

required

string

Идентификатор записи

Responses

ККТ

Список ККТ

Список загруженных из ОФД ККТ (Контрольно-кассовая техника). Управление списком:

created: сортировка и фильтрация
changed: сортировка и фильтрация

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.

Responses

Response Schema: application/json

required	Array of objects (OfdKkt) Список ККТ
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"created": "2019-10-25T15:22:25Z",
"changed": "2019-10-28T12:48:43Z",
"id": 1,
"ext_id": 1,
"name": "Мебельная студия \"Лесовичок\"",
"reg_no": 2883225008884,
"status": "registered",
"user_id": 6604,
"address": "Московская обл, г. Пушкино, ул. Ленина, д. 29, цокольный этаж",
"factory_no": 307405235630,
"fn_no": 9287440300203788,
"model_name": "ЭВОТОР СТ2Ф"
}
],
"total": 10
}

Чеки ККТ

Список чеков ККТ

Чеки по ККТ из ОФД

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.

Responses

Response Schema: application/json

required	Array of objects (OfdKktReceipt) Список чеков ККТ
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"created": "2019-08-24T14:15:22Z",
"changed": "2019-08-24T14:15:22Z",
"date": "2019-08-24",
"time": "15:44:30",
"amount": 238.16,
"currency": "usd",
"fn": "8710000101444681",
"fd": "136928",
"fpd": "1133038423",
"payment_type": "cash",
"user_id": 140,
"kkt_id": 30,
"operation_type": "income",
"goods": [{"name": "ДОКТОР МОМ РАСТ ПАСТИЛКИ ОТ КАШЛЯ АНАНАС №20",
"amount": 248.16,
"quantity": 2,
"rate": 124.08,
"id": 678
}
]
}
],
"total": 10
}

Профили

Список профилей

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.

Responses

Response Schema: application/json

required	Array of objects (Profile) Список профилей
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"created": "2019-01-20T14:07:44Z",
"changed": "2019-08-24T14:15:22Z",
"id": 10,
"user_id": 3,
"provider": {"id": 5,
"key": "tcs",
"name": "Тинькофф",
"logo": "https://cashoff.ru/static/image/logo/tcs.svg",
"type": "bank"
},
"session": {"key": "b51b417f218b48c3968cbb7b2e0d753b",
"status": "ok"
},
"status": "ok"
}
],
"total": 10
}

Добавить новый профиль

Authorizations:

(ApiAuthUserID) UserSession

Request Body schema: application/json

provider_key required	string Ключ провайдера данных
	object (ProfileAuthData) Данные авторизации
start_update	boolean Default: false После создания сразу запустить синхронизацию
	Array of strings or object (ProfileUpdateStages) Шаги обновления. Есть два варианта указания: сокращённый в виде списка идентификаторов полный в виде объекта Оба варианта позволяют выбрать нужные шаги, но второй ещё позволяет установить отдельные опции для каждого из шагов. По умолчанию всегда выполняется шаг `auth`, шаги `accounts` и `transactions` выполняются если провайдер поддерживает их. Шаг `payments` по умолчанию не выполняется и требует явного добавления.

Responses

Response Schema: application/json

required

object (Profile)

Профиль провайдера данных

update_status

string (update_status)

Enum: "ok" "already_started" "form_invalid" "provider_unavailable"

Результат запуска обновления

ok: запущено
already_started: обновление уже идет
form_invalid: предоставленные данные не валидны по форме текущего шага
provider_unavailable: провайдер не доступен (отключен)

Request samples

Payload

Content type

application/json

{"provider_key": "tcs",
"auth_data": {"login": "test",
"password": "qwerty"
}
}

Response samples

200

Content type

application/json

{"profile": {"created": "2019-01-20T14:07:44Z",
"changed": "2019-08-24T14:15:22Z",
"id": 10,
"user_id": 3,
"provider": {"id": 5,
"key": "tcs",
"name": "Тинькофф",
"logo": "https://cashoff.ru/static/image/logo/tcs.svg",
"type": "bank"
},
"session": {"key": "b51b417f218b48c3968cbb7b2e0d753b",
"status": "ok"
},
"status": "ok"
},
"update_status": "ok"
}

Добавить профиль self-провайдера

Authorizations:

(ApiAuthUserID) UserSession

Request Body schema: application/json

ext_id

string

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

Responses

Response Schema: application/json

required

object (Profile)

Профиль провайдера данных

Request samples

Payload

Content type

application/json

{"ext_id": "f5ff0b59-2f9f-47bb-9e3d-d6cd4f9ff537"
}

Response samples

200

Content type

application/json

{"profile": {"created": "2019-01-20T14:07:44Z",
"changed": "2019-08-24T14:15:22Z",
"id": 10,
"user_id": 3,
"provider": {"id": 5,
"key": "tcs",
"name": "Тинькофф",
"logo": "https://cashoff.ru/static/image/logo/tcs.svg",
"type": "bank"
},
"session": {"key": "b51b417f218b48c3968cbb7b2e0d753b",
"status": "ok"
},
"status": "ok"
}
}

Информация по профилю

Authorizations:

ApiAuthUserSession

query Parameters

profile_id

required

number

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

Responses

Response Schema: application/json

created required	string <date-time> Дата создания
changed required	string <date-time> Дата последнего изменения
id required	number Идентификатор профиля
user_id	number Идентификатор пользователя
required	object (Provider) Провайдер финансовых данных
required	object (ProfileSession) Сессия профиля
status required	string (profile_status) Enum: "auth" "updating" "error" "ok" Статус обновления профиля auth: выполняется авторизация updating: идет обновление error: последнее обновление завершилось ошибкой ok: профиль в нормальном состоянии (обновление завершено/отменено/не выполнялось)
	object Информация о последней ошибке по профилю. Заполняется при `status`=`error`
	object Список блоков выписки, загрузка по которым завершились ошибкой
update_progress	nubmer Прогресс обновления, от 0 до 100
accounts_updated_at	string <date-time> Дата последнего обновления списка продуктов
update_done_at	string <date-time> Дата последнего успешного обновления
update_started_at	string <date-time> Дата последнего запуска обновления
update_current_stage	string Текущий этап обновления профиля. Список возможных шагов перечислен в описании атрибуте `update_stages` запроса на запуск обновления. Список шагов может расширяться и изменяться.

Response samples

200

Content type

application/json

{"created": "2019-01-20T14:07:44Z",
"changed": "2019-08-24T14:15:22Z",
"id": 10,
"user_id": 3,
"provider": {"id": 5,
"key": "tcs",
"name": "Тинькофф",
"logo": "https://cashoff.ru/static/image/logo/tcs.svg",
"type": "bank"
},
"session": {"key": "b51b417f218b48c3968cbb7b2e0d753b",
"status": "ok"
},
"status": "ok"
}

Удалить профиль

Удалить профиль можно только если по нему на момент удаления не проводится никаких операций (в частности обновление).

Если профиль используется, то вернется статус 423 c кодом ошибки in_use.

Authorizations:

ApiAuthUserSession

query Parameters

profile_id

required

number

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

Responses

Запустить обновление профиля

Запуск возможен из статуса профиля ok или error (в таком случае будет автоматически выполнен сброс профиля).
В случае статуса auth нужно либо выполнить шаг авторизации через соответствующий метод, либо отменить обновление - тогда его можно будет запустить заного.

Authorizations:

ApiAuthUserSession

query Parameters

profile_id

required

number

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

Request Body schema: application/json

Array of strings or object (ProfileUpdateStages)

Шаги обновления.

Есть два варианта указания:

сокращённый в виде списка идентификаторов
полный в виде объекта

Оба варианта позволяют выбрать нужные шаги, но второй ещё позволяет установить отдельные опции для каждого из шагов.

По умолчанию всегда выполняется шаг auth, шаги accounts и transactions выполняются если провайдер поддерживает их. Шаг payments по умолчанию не выполняется и требует явного добавления.

Responses

Response Schema: application/json

status

required

string (update_status)

Enum: "ok" "already_started" "form_invalid" "provider_unavailable"

Результат запуска обновления

ok: запущено
already_started: обновление уже идет
form_invalid: предоставленные данные не валидны по форме текущего шага
provider_unavailable: провайдер не доступен (отключен)

Request samples

Payload

Content type

application/json

{"update_stages": ["auth"
]
}

Response samples

200

Content type

application/json

{"status": "ok"
}

Сброс профиля

Сброс возможен из статусов auth и error.
В случае ok все остается без изменений, а в процессе обновления (updating) сброс не доступен.
Сброс приводит к переходу в статус ok, очистке сохраненных ошибок и сбросу прогресса авторизации на первый шаг.

Authorizations:

ApiAuthUserSession

query Parameters

profile_id

required

number

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

Responses

Response Schema: application/json

status

string

Enum: "ok" "reset_unavailable"

Результат сброса обновления

Response samples

200

Content type

application/json

{"status": "ok"
}

Выполнить шаг авторизации профиля

Authorizations:

ApiAuthUserSession

query Parameters

profile_id

required

number

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

Request Body schema: application/json

required

object (ProfileAuthData)

Данные авторизации

Responses

Response Schema: application/json

status

required

string (update_status)

Enum: "ok" "already_started" "form_invalid" "provider_unavailable"

Результат запуска обновления

ok: запущено
already_started: обновление уже идет
form_invalid: предоставленные данные не валидны по форме текущего шага
provider_unavailable: провайдер не доступен (отключен)

Request samples

Payload

Content type

application/json

{"auth_data": {"login": "demo",
"password": "qwerty",
"can_save_private": true
}
}

Response samples

200

Content type

application/json

{"status": "ok"
}

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

Данный запрос позволяет получить "запросы" на выгрузку файлов выписки из банка. "Запросы" потому, что для получения выписки передается не только url, но и http-метод (get/post) и заголовки http-запроса.

Для работы требует уже авторизованную сессию. В качестве параметров передаются идентификатор продукта, по которому нужна выписка, а так же её период.

Выписка может быть разбита на блоки, по этому возвращается список запросов.

Запросы работают только в пределах времени активности сессии, по этому должны быть использованы как можно скорее.

Authorizations:

ApiAuthUserSession

query Parameters

profile_id

required

number

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

Request Body schema: application/json

account_id required	string Идентификатор аккаунта
date_from required	string <date> Дата, начиная с которой получить выписку
date_to required	string <date> Дата, по которую (включительно) получить выписку

Responses

Response Schema: application/json

Array

url required	string Адрес запроса
method required	string Enum: "GET" "POST" Метод запроса
headers	string Заголовки запроса
body	string Тело запроса (для POST)

Request samples

Payload

Content type

application/json

{"account_id": 153,
"date_from": "2019-08-24",
"date_to": "2019-08-24"
}

Response samples

200

Content type

application/json

[{"url": "https://bank.ru/stm/download?id=12345",
"method": "GET",
"headers": "Cache-Control: max-age=0\nUser-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36\nCookie: JSESSIONID=64CD4AE222C53FA4676D987EAEBE801C;",
"body": "account_id=3245&date_from=2019-03-18"
}
]

Провайдеры

Список провайдеров данных

Управление списком:

id: фильтрация
key: фильтрация
type: фильтрация

Authorizations:

ApiAuthUserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.
include_all_steps	boolean Default: false Добавить в описание список всех возможных шагов авторизации (поле all_steps).

Responses

Response Schema: application/json

required	Array of objects (ProviderFullAuth) Список провайдеров
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"id": 10,
"key": "tcs",
"name": "Тинькофф",
"logo": "https://cashoff.ru/static/media/institutions_logo/tcs_36.svg",
"type": "bank",
"first_step": {"key": "sms",
"name": "string",
"help": "Введите СМС-код, отправленный на ваш номер телефона.",
"fields": [{"key": "login",
"type": "text",
"label": "Логин"
}
]
},
"all_steps": [{"key": "sms",
"name": "string",
"help": "Введите СМС-код, отправленный на ваш номер телефона.",
"fields": [{"key": "login",
"type": "text",
"label": "Логин"
}
]
}
]
}
],
"total": 10
}

Получить параметры self-провайдера

Authorizations:

ApiAuth

Responses

Response Schema: application/json

any (ProviderSelfGet)

Response samples

200

Content type

application/json

null

Установить параметры self-провайдера

Этот метод используется не только установки отдельных параметров, но и для включения провайдера в целом: для этого нужно установить enabled=true.

По умолчанию провайдер отключен.

Authorizations:

ApiAuth

Request Body schema: application/json

enabled required	boolean Провайдер включен.
name	string Название провайдера в UI встраиваемых модулей
	object Набор url сервисов для получения данных по провайдеру

Responses

Response Schema: application/json

any (ProviderSelfGet)

Request samples

Payload

Content type

application/json

{"enabled": true,
"name": "Банк \"Лучший\"",
"endpoints": {"accounts": "https://test.endpoint/cashoff/accounts/",
"transactions": "https://test.endpoint/cashoff/transactions/",
"receipts": "https://test.endpoint/cashoff/receipts/"
}
}

Response samples

200

Content type

application/json

null

Удалить self-провайдера

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

Authorizations:

ApiAuth

Responses

Синхронизация с CASHOFF

[ОВ] Получить список продуктов

Это запрос, который выполняется от CASHOFF к серверу приложения.

Адрес запроса указывается в /providers/self, параметр endpoints.accounts.

Authorizations:

ApiAuth

Request Body schema: application/json

user_id required	number Идентификатор пользователя в CASHOFF
ext_id	string Идентификатор пользователя в приложении (указывается при добавлении профиля self-провайдера)

Responses

Response Schema: application/json

required	Array of objects (AccountImport) Список продуктов
	Array of objects Список групп продуктов

Request samples

Payload

Content type

application/json

{"user_id": 140,
"ext_id": "f5ff0b59-2f9f-47bb-9e3d-d6cd4f9ff537"
}

Response samples

200

Content type

application/json

{"accounts": [{"ext_id": "f5ff0b59-2f9f-47bb-9e3d-d6cd4f9ff537",
"type": "account",
"amount": 7400,
"currency": "usd",
"name": "Карта Visa",
"number": "**** 5789",
"bank_bic": "*****5411",
"date_open": "2019-08-24",
"date_close": "2019-08-24",
"status": "blocked",
"owner": {"type": "sme",
"name": "ООО \"Рога и копыта\"",
"inn": "7710140679",
"kpp": "773401001",
"ogrn": "1053600591197",
"email": "user@example.com",
"phone": "8916*****20"
},
"swift": {"beneficiary": {"name": "IP Chepaev Evgeniy Vladimirovich",
"institution": "MODULBANK",
"swift": "MODBRU22",
"iban": "IS140159260076545510730339"
},
"correspondent": {"bank": "RAIFFEISEN BANK INTERNATIONAL AG",
"swift": "RZBAATWWXXX",
"account": "70-55.090.237"
}
},
"card_extra": {"account_ext_id": "acc1",
"base_card_ext_id": "card1",
"type": "credit",
"client_funds": 0,
"overdraft": 10000,
"payment_system": "visa",
"premium_class": "classic"
},
"group_ext_id": "group1"
}
],
"groups": [{"ext_id": "group1",
"amount": 7400,
"currency": "usd",
"is_combined": true
}
]
}

[ОВ] Получить список операций

Это запрос, который выполняется от CASHOFF к серверу приложения.

Адрес запроса указывается в /providers/self, параметр endpoints.transactions.

Authorizations:

ApiAuth

Request Body schema: application/json

user_id required	number Идентификатор пользователя в CASHOFF
ext_id	string Идентификатор пользователя в приложении (указывается при добавлении профиля self-провайдера)
required	object Блок, за который запрашивается выписка.

Responses

Response Schema: application/json

required

Array of objects (TransactionImport)

Список операций

Request samples

Payload

Content type

application/json

{"user_id": 140,
"ext_id": "f5ff0b59-2f9f-47bb-9e3d-d6cd4f9ff537",
"block": {"account_ext_id": "string",
"date_from": "2019-08-24",
"date_to": "2019-08-24"
}
}

Response samples

200

Content type

application/json

{"transactions": [{"ext_id": "d275ab5a-43ef-4175-ac37-a0e708f51db5",
"amount": 50,
"currency": "usd",
"trans_amount": {"value": 10,
"currency": "usd"
},
"date": "2019-08-24",
"date_execution": "2019-08-24",
"time": "15:44:30",
"details": "STARBUCKS MOSKVA RU S5306",
"card_extra": {"is_hold": false,
"mcc": "9222",
"mcc_description": "Штрафы",
"pos_id": "pos1234",
"merchant_id": "merchant1234"
},
"geo": {"lat": 56.857995,
"lng": 35.898965,
"city": "string",
"country": "string"
},
"payer": {"name": "АО \"ТИНЬКОФФ БАНК\"",
"inn": "7710140679",
"kpp": "773401001",
"account_number": "47426810000000022664",
"bank_name": "АО \"ТИНЬКОФФ БАНК\"",
"bank_bic": "044525974",
"bank_corr_number": "30101810145250000974"
},
"receiver": {"name": "АО \"ТИНЬКОФФ БАНК\"",
"inn": "7710140679",
"kpp": "773401001",
"account_number": "47426810000000022664",
"bank_name": "АО \"ТИНЬКОФФ БАНК\"",
"bank_bic": "044525974",
"bank_corr_number": "30101810145250000974"
},
"tax": {"tax101": "01",
"tax104": "18210101040011000110",
"tax105": "45908000",
"tax106": "ТП",
"tax107": "МС.10.2018",
"tax108": "0",
"tax109": "0",
"tax110": "0"
},
"receipt": {"date": "2019-08-24",
"time": "15:44:30",
"amount": 238.16,
"currency": "usd",
"fn": "8710000101444681",
"fd": "136928",
"fpd": "1133038423",
"payment_type": "cash",
"discount": 10,
"shop_description": "ЗАКРЫТОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО \"ТОРГОВЫЙ ДОМ \"ПЕРЕКРЕСТОК\"",
"shop_inn": "7728029110",
"shop_address": "398026, 48, г. Липецк, ул. Героя России Эдуарда Белана, б/н",
"user_added_at": "2019-08-24T14:15:22Z",
"user_added_city": "string",
"ext_id": "c3815ffcc52c49118ebcb4e4e09444b6",
"goods": [{"name": "ДОКТОР МОМ РАСТ ПАСТИЛКИ ОТ КАШЛЯ АНАНАС №20",
"amount": 248.16,
"quantity": 2,
"rate": 124.08,
"ext_id": "1314600f2b6f460f91cb11da294993b5"
}
]
}
}
]
}

Платежи

Создать платеж в рублях

В ходе запроса выполняется только заведение платежа в CASHOFF, заведение платежа в системе провайдера происходит в фоновом режиме.

Результат выполнения данной операции у провайдера сообщается нотификацией profile.rub_payment.add.

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

profile_id

required

number

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

Request Body schema: application/json

account_id required	number Идентификатор продукта
required	object (RubPaymentFields) Реквизиты рублевого платежа

Responses

Response Schema: application/json

required

object (RubPayment)

Рублевый платеж

Request samples

Payload

Content type

application/json

{"account_id": 1276,
"doc": {"amount": 100,
"payer_name": "ООО «Беркут»",
"payer_address": "Россия, г. Самара, ул. Калинина 15.",
"bank_bic": 41012718,
"bank_corr_number": "30101810145250000974",
"bank_name": "АО \"ТИНЬКОФФ БАНК\"",
"account_number": "30101810700000000718",
"receiver_name": "Иванов Иван Иванович ИП",
"inn": "7731347089",
"kpp": "773101001",
"nds": 0,
"payment_order": 5,
"details": "По сч. 50 от 01.02.04 г. приобретение кондиционеров",
"tax": {"tax22": "0",
"tax101": "01",
"tax104": "18210101040011000110",
"tax105": "45908000",
"tax106": "ТП",
"tax107": "МС.10.2018",
"tax108": "0",
"tax109": "0",
"tax110": "0"
}
}
}

Response samples

200

Content type

application/json

{"payment": {"created": "2019-08-24T14:15:22Z",
"changed": "2019-08-24T14:15:22Z",
"id": 367,
"ext_id": "payment-123",
"account_id": 785,
"status": "in_progress"
}
}

Подтвердить платеж в рублях

Подтверждаются только документы в статусе at_confirmation, которые при создании вернули confirm_required.

Подтверждение платежа в системе провайдера происходит в фоновом режиме.

Результат выполнения данной операции у провайдера сообщается нотификацией profile.rub_payment.confirm.

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

profile_id required	number Идентификатор профиля.
payment_id required	number Идентификатор платежа.

Request Body schema: application/json

confirm_code

required

string

Код подтверждения

Responses

Request samples

Payload

Content type

application/json

{"confirm_code": "1234"
}

Список рублевых платежей

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.

Responses

Response Schema: application/json

required	Array of objects (RubPayment) Список рублевых платежей
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"created": "2019-08-24T14:15:22Z",
"changed": "2019-08-24T14:15:22Z",
"id": 367,
"ext_id": "payment-123",
"account_id": 785,
"status": "in_progress"
}
],
"total": 10
}

Информация по рублевому платежу

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

profile_id required	number Идентификатор профиля.
payment_id required	number Идентификатор платежа.

Responses

Response Schema: application/json

created required	string <date-time> Дата создания
changed required	string <date-time> Дата последнего изменения
id required	number Идентификатор платежа
ext_id	string Идентификатор платежа у провайдера.
account_id required	number Идентификатор продукта плательщика
status required	string Enum: "absent" "accepted" "executed" "denied" "at_creation" "not_created" "at_confirmation" Статус заведенного платежа: `absent`: не найден у провайдера `not_created`: создать не удалось `accepted`: принят `executed`: исполнен `denied`: отказан Статус платежа в процессе заведения: `at_creation`: в процессе создания `at_confirmation`: платеж ожидает фазы подтверждения

Response samples

200

Content type

application/json

{"created": "2019-08-24T14:15:22Z",
"changed": "2019-08-24T14:15:22Z",
"id": 367,
"ext_id": "payment-123",
"account_id": 785,
"status": "in_progress"
}

Категории

Список категорий

Authorizations:

ApiAuthUserSession

Responses

Response Schema: application/json

Array

id required	number Идентификатор категории
name required	string Название категории
required	Array of objects (TransactionSubCategory) Подкатегории

Response samples

200

Content type

application/json

[{"id": 0,
"name": "Еда и напитки",
"children": [{"id": 1,
"name": "Продукты питания",
"for_consumer": true,
"for_sme": true
}
]
}
]

Мерчанты

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

Управление списком:

name: фильтрация (от 3-х символов)
generic: фильтрация

Authorizations:

ApiAuthUserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.

Responses

Response Schema: application/json

required	Array of objects (Merchant) Список мерчантов
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"id": 523,
"name": "Перекресток",
"generic": false,
"logo": "https://cashoff.ru/static/media/merchants_logo/PE8W7FDF_36.svg"
}
],
"total": 10
}

Акции

Список акций

Управление списком:

created: сортировка и фильтрация
changed: сортировка и фильтрация
id: фильтрация
date_from: фильтрация
date_to: фильтрация

Authorizations:

ApiAuthUserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.
only_active	boolean Default: true Выдавать только активные на текущую дату акции.
active_at	string <date> Выдавать только активные на указанную дату акции.

Responses

Response Schema: application/json

required	Array of objects (Offer) Список акций
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"created": "2019-08-24T14:15:22Z",
"changed": "2019-08-24T14:15:22Z",
"id": 0,
"title": "Икра Дядя Ваня из кабачков 460г",
"text": "Вернем 10 % за покупку в любом магазине товара Икра Дядя Ваня из кабачков 460г.\n",
"conditions": "Организатор акции ООО...",
"category": {"id": 0,
"name": "Рыба и морепродукты",
"for_adults_only": true,
"order_num": 0
},
"cashback_type": "percent",
"cashback": {"qr": 0,
"card": 0,
"trans_bonus": 0
},
"currency": "rub",
"date_from": "string",
"date_to": "string",
"status": "active",
"restrictions": {"participations": {"limit_type": "product_units",
"max_count": 5
},
"rate": {"min": 0,
"max": 0
},
"amount": {"min": 0,
"max": 0
},
"count": {"min": 0,
"max": 0
}
},
"images": ["string"
]
}
],
"total": 10
}

Включить пользователю кешбек

Данный метод включает пользователю кешбек.

Authorizations:

(ApiAuthUserID) UserSession

Responses

Response Schema: application/json

status

string

Enum: "done" "forbidden"

Результат включения

Response samples

200

Content type

application/json

{"status": "done"
}

Отключить пользователю кешбек

Authorizations:

(ApiAuthUserID) UserSession

Responses

Response Schema: application/json

status

string

Enum: "done" "forbidden"

Результат отключения

Response samples

200

Content type

application/json

{"status": "done"
}

Включить кешбек за акции для совершеннолетних

Пользователь сможет получать кешбэк по акциям из категорий, доступных только совершеннолетним.

Изменения будут заблокированы, если у пользователя выключен кешбэк, либо согласие пользователя не требуется.

Authorizations:

(ApiAuthUserID) UserSession

Responses

Response Schema: application/json

status

string

Enum: "done" "not_modified" "forbidden"

Результат включения:

done: Успешно;
not_modified: Изменения не выполнены, т.к. не требуются;
forbidden: Изменения блокированы;

Response samples

200

Content type

application/json

{"status": "done"
}

Отключить кешбек за акции для совершеннолетних

Пользователь не сможет получать кешбэк по акциям из категорий, доступных только совершеннолетним.

Изменения будут заблокированы, если у пользователя выключен кешбэк, либо согласие пользователя не требуется.

Authorizations:

(ApiAuthUserID) UserSession

Responses

Response Schema: application/json

status

string

Enum: "done" "not_modified" "forbidden"

Результат выключения:

done: Успешно;
not_modified: Изменения не выполнены, т.к. не требуются;
forbidden: Изменения блокированы;

Response samples

200

Content type

application/json

{"status": "done"
}

Справочник категорий акций

Authorizations:

ApiAuthUserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.

Responses

Response Schema: application/json

required	Array of objects (OfferCategory) Список категорий акций
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"id": 0,
"name": "Рыба и морепродукты",
"for_adults_only": true,
"order_num": 0
}
],
"total": 10
}

Кешбек

Получить информацию о имеющемся кешбеке

Управление списком:

changed: сортировка и фильтрация

Authorizations:

(ApiAuthUserID) UserSession

Responses

Response Schema: application/json

amount required	number Сумма кешбека
currency required	string Валюта кешбека
changed	string <date-time> Дата последнего изменения

Response samples

200

Content type

application/json

{"amount": 100,
"currency": "rub",
"changed": "2019-08-24T14:15:22Z"
}

Список снятий кешбека

Управление списком:

id: фильтрация
date: сортировка и фильтрация
status: фильтрация

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.
order_by	string Value: "date"

Responses

Response Schema: application/json

required	Array of objects (CashbackWithdraw) Список снятий кешбеков
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"id": 10,
"user_id": 20,
"amount": 100,
"date": "2019-08-24T14:15:22Z",
"status": "created"
}
],
"total": 10
}

Снять кешбек через moneta.ru

Через данный метод осуществляется перечисление кешбека на банковскую карту посредством сервиса moneta.ru. Операция проходит следующим образом:

выполняется данный метод, он создает объект снятия средств (withdraw) и возвращает url формы moneta, через которую происходит платеж
данный url открывается клиенту, там он заполняет поля формы и отправляет её
результат приходит в сервис cashoff, в случае успеха платеж подтверждается
клиент перенаправляется на указанную при выполнении данного метода страницу возврата

При возврате к redirect_url в качестве параметров добавляются значения полей id, amount, status из объекта снятия. Итоговая ссылка будет вида: redirect_url?id=1&status=done&amount=100

Authorizations:

(ApiAuthUserID) UserSession

Request Body schema: application/json

redirect_url

required

string

url, на который необходимо вернуть клиента

Responses

Response Schema: application/json

form_url required	string url, по которому клиенту необходимо заполнить форму
	object (CashbackWithdraw) Снятие кешбека

Request samples

Payload

Content type

application/json

{"redirect_url": "https://example.com/withdraw-done/"
}

Response samples

200

Content type

application/json

{"form_url": "https://www.moneta.ru/secureCardData.htm",
"withdrawal": {"id": 10,
"user_id": 20,
"amount": 100,
"date": "2019-08-24T14:15:22Z",
"status": "created"
}
}

Список начислений кешбека

Управление списком:

id: фильтрация
offer_id: фильтрация
status: фильтрация
received_at: сортировка и фильтрация
withdrawal_id: фильтрация

Authorizations:

ApiAuth(ApiAuthUserID) UserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.
order_by	string Value: "received_at"

Responses

Response Schema: application/json

required	Array of objects (CashbackAccrual) Список начислений кешбеков
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"id": 1,
"offer_id": 405,
"user_id": 6500,
"amount": 5,
"status": "received",
"received_at": "2019-08-24T14:15:22Z",
"withdrawal_id": 0,
"items": [{"receipt_id": 0,
"receipt_item_id": 678,
"receipt_item_ext_id": "1314600f2b6f460f91cb11da294993b5"
}
]
}
],
"total": 10
}

Информация по начислению

Authorizations:

ApiAuthUserSession

path Parameters

accrual_id

required

string

Идентификатор начисления

Responses

Response Schema: application/json

id required	number Идентификатор начисления
offer_id required	number Идентификатор акции
user_id required	number Идентификатор пользователя
amount required	number Сумма кешбека
status required	string Enum: "pending" "approved" "received" "redeemed" Статус кешбека. `pending`: кешбэк создан, но его правильность не подтверждена `approved`: кешбэк создан, его правильность подтверждена, но он еще не зачислен на внутренний счет `received`: кешбэк зачислен на внутренний счёт `redeemed`: кешбэк выплачен (деньги выведены из сервиса, например, на банковскую карту пользователя)
received_at	string <date-time> Дата зачисления кешбека
withdrawal_id	integer Идентификатор операции выплаты кешбека
required	Array of objects (CashbackAccrualHeading) Список товаров, за которые получен кешбек

Response samples

200

Content type

application/json

{"id": 1,
"offer_id": 405,
"user_id": 6500,
"amount": 5,
"status": "received",
"received_at": "2019-08-24T14:15:22Z",
"withdrawal_id": 0,
"items": [{"receipt_id": 0,
"receipt_item_id": 678,
"receipt_item_ext_id": "1314600f2b6f460f91cb11da294993b5"
}
]
}

Лимит участий пользователя в акциях

Управление списком:

offer_id: фильтрация

Authorizations:

(ApiAuthUserID) UserSession

query Parameters

limit	integer <= 100 Default: 50 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.
only_active	boolean Default: true Выдавать лимиты только по активным на текущую дату акциям.
active_at	string <date> Выдавать лимиты только по активным на указанную дату акциям.

Responses

Response Schema: application/json

required	Array of objects (OfferParticipationInfo) Список лимитов по каждой акции. Если количество участий в акции не ограничено, то она не попадает в этот список.
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"offer_id": 1041,
"limit_type": "product_units",
"max_count": 5,
"actual_count": 3
}
],
"total": 10
}

Суточный лимит чеков с доступным кешбэком

Метод актуален только для площадок, на которых установлен суточный лимит чеков, по которым можно получить кешбэк.

Управление списком:

date: сортировка и фильтрация

Authorizations:

(ApiAuthUserID) UserSession

query Parameters

limit	integer <= 92 Default: 30 Максимальное количество записей, которое можно вернуть.
offset	integer Сколько записей от начала нужно пропустить.
with_receipts_list	boolean Default: false По каждой дате выдавать список ID чеков в лимите.

Responses

Response Schema: application/json

required	Array of objects (DailyReceiptsLimit) Список лимитов по каждой дате покупки
total	number (total) Общее количество записей

Response samples

200

Content type

application/json

{"items": [{"date": "2019-08-24",
"receipts_count": 4,
"receipts_list": [451242,
451251,
451279
]
}
],
"total": 10
}

Истории

Список текущих историй

Возвращает текущий список историй, которые доступны пользователю.

Authorizations:

(ApiAuthUserID) UserSession

Responses

Response Schema: application/json

required	Array of objects (Story) Список историй
favorite_stories_count required	number Количество историй, добавленных в избранное.

Response samples

200

Content type

application/json

{"stories": [{"id": 150,
"header": "Как избавиться от хлама?",
"hide_header": "no",
"background": {"type": "color",
"isDark": true,
"direction": "none",
"colors": ["#ffffff"
]
},
"user_stats": {"like_status": "liked",
"in_favorites": true,
"first_view": "2019-08-24T14:15:22Z"
}
}
],
"favorite_stories_count": 0
}

Список избранных историй

Возвращает список историй, которые пользователь добавил в избранное.

Authorizations:

(ApiAuthUserID) UserSession

Responses

Response Schema: application/json

required

Array of objects (Story)

Список историй

Response samples

200

Content type

application/json

{"stories": [{"id": 150,
"header": "Как избавиться от хлама?",
"hide_header": "no",
"background": {"type": "color",
"isDark": true,
"direction": "none",
"colors": ["#ffffff"
]
},
"user_stats": {"like_status": "liked",
"in_favorites": true,
"first_view": "2019-08-24T14:15:22Z"
}
}
]
}

Нотификации

Получить настройки нотификаций

Authorizations:

ApiAuth

Responses

Response Schema: application/json

target	string Полный url адрес для получения нотификаций
events	Array of strings (notification_event_id) Items Enum: "profile.updated" "profile.rub_payment.add" "profile.rub_payment.confirm" "receipt.pending_resolved" "receipt.cashback" Список идентификаторов событий.

Response samples

200

Content type

application/json

{"target": "https://test.endpoint/cashoff/notifications/",
"events": ["profile.updated"
]
}

Установить настройки нотификаций

Authorizations:

ApiAuth

Request Body schema: application/json

target	string Полный url адрес для получения нотификаций
events	Array of strings (notification_event_id) Items Enum: "profile.updated" "profile.rub_payment.add" "profile.rub_payment.confirm" "receipt.pending_resolved" "receipt.cashback" Список идентификаторов событий.

Responses

Request samples

Payload

Content type

application/json

{"target": "https://test.endpoint/cashoff/notifications/",
"events": ["profile.updated"
]
}

Удалить настройки нотификаций

Authorizations:

ApiAuth

Responses

[ОВ] Нотификация об событиях в сервисе

Это запрос, который выполняется от CASHOFF к серверу приложения.

Адрес /callback/notify указан для примера, реальный адрес запроса берётся из настроек нотификаций (поле target). В теле запроса CASHOFF укажет код события и его данные. Сервер приложения после обработки запроса может ответить произвольно - CASHOFF смотрит только на http-код ответа. По этому в случае успеха рекомендуется вернуть код 200 с пустым телом.

В случае неуспешной попытки доставки нотификации в дальнейшем будут выполнены 4 дополнительные попытки с увеличивающейся паузой в 1, 6, 12 и 24 часа. Доставка нотификации считается неуспешной если:

сервер не ответил (сетевая ошибка)
в ответ пришел один из следующих кодов: 429, 502, 503, 504.

Остальные случаи считаются за успешную доставку.

Возможные события:

Код события	Формат поля data	Когда отправляется
profile.updated	ProfileNotification	При изменении профиля (статуса и текущего этапа обновления) или состояния сессии.
profile.rub_payment.add	ProfileRubPaymentAddNotification	Как результат выполнения запроса `/profiles/{profile_id}/payments/rub/add`
profile.rub_payment.confirm	ProfileRubPaymentConfirmNotification	Как результат выполнения запроса `/profiles/{profile_id}/payments/rub/{payment_id}/confirm`
receipt.pending_resolved	PendingReceiptNotification	Загружаемый чек получил конечный статус (как успешный, так и нет)
receipt.cashback	ReceiptNotification	Чек получил/обновил кешбек

Authorizations:

ApiAuth

Request Body schema: application/json

event required	string (notification_event_id) Enum: "profile.updated" "profile.rub_payment.add" "profile.rub_payment.confirm" "receipt.pending_resolved" "receipt.cashback" Код события
required	ProfileNotification (object) or PendingReceiptNotification (object) or ReceiptNotification (object) or ProfileRubPaymentAddNotification (object) or ProfileRubPaymentConfirmNotification (object)

Request samples

Payload

Content type

application/json

{"event": "profile.updated",
"data": {"profile": {"created": "2019-01-20T14:07:44Z",
"changed": "2019-08-24T14:15:22Z",
"id": 10,
"user_id": 3,
"provider": {"id": 5,
"key": "tcs",
"name": "Тинькофф",
"logo": "https://cashoff.ru/static/image/logo/tcs.svg",
"type": "bank"
},
"session": {"key": "b51b417f218b48c3968cbb7b2e0d753b",
"status": "ok"
},
"status": "ok"
}
}
}

Обратные вызовы

Получить схему авторизации ОВ

Authorizations:

ApiAuth

Responses

Response Schema: application/json

auth_schema required	string Enum: "sign_sha1" "sign_sha256" "http_basic" Схема авторизации для обратных вызовов
force_for_incoming	boolean Default: false Если установлено, то эта же схема авторизации требуется для входящих в CASHOFF запросов.

Response samples

200

Content type

application/json

{"auth_schema": "sign_sha1",
"force_for_incoming": false
}

Установить схему авторизации ОВ

Authorizations:

ApiAuth

Request Body schema: application/json

auth_schema required	string Enum: "sign_sha1" "sign_sha256" "http_basic" Схема авторизации для обратных вызовов
force_for_incoming	boolean Default: false Если установлено, то эта же схема авторизации требуется для входящих в CASHOFF запросов.

Responses

Request samples

Payload

Content type

application/json

{"auth_schema": "sign_sha1",
"force_for_incoming": false
}