openapi: 3.0.0 info: version: 2.0.0 title: Vality Platform Analytics API description: | ## Описание Vality Analytics API является точкой взаимодействия с аналитической и поисковой частью платформы. Все аналитические запросы осуществляются с помощью вызовов соответствующих методов API. Любые сторонние приложения, включая наши веб-сайты, личные кабинеты и другие UI-интерфейсы являются внешними приложениями-клиентами. Vality Analytics API работает поверх HTTP-протокола. Мы используем REST архитектуру, схема описывается в соответствии со стандартом [OpenAPI v3.0](https://spec.openapis.org/oas/v3.0.0/). Коды возврата описываются соответствующими HTTP-статусами. Платформа принимает и возвращает JSON-структуры в HTTP body. ## Запросы Любой вызов методов API обязан предваряться предоставлением уникального для участника в пределах платформы ID запроса. Данный ID передается в соответствующем заголовке HTTP-запроса: ``` X-Request-ID: oX5MWM2AQy ``` Платформа гарантирует идемпотентность запросов, отправленных с одинаковым ID. ## Тип содержимого и кодировка Любой запрос к API должен выполняться в кодировке UTF-8 и с указанием содержимого в формате JSON ``` Content-Type: application/json; charset=utf-8 ``` ## Формат дат Платформа принимает значения date-time в стандарте ISO 8601 с обязательным указанием UTC-оффсета, например: ``` 2017-01-01T00:00:00Z 2017-01-01T00:00:01+00:00 ``` ## Максимальное время обработки запроса К любому вызову методов API можно добавить параметр отсечки по времени, определяющий максимальное время ожидания завершения операции по запросу. Данная отсечка передается в соответствующем заголовке HTTP-запроса: ``` X-Request-Deadline: 10s ``` Значение отсечки может быть задано в формате ISO 8601 (см. [Формат дат](#section/Format-dat)), либо в относительных величинах, например: `150000ms`, `540s`, `3.5m` При этом возможные единицы измерения `ms`, `s`, `m`. В обоих случаях не рекомендуется, чтобы задаваемое значение было меньше **3 секунд** и превышало **1 минуту**. ## Поиск по магазинам API предоставляет несколько различных критериев для выбора магазинов, в рамках которых будет выполняться поиск или аналитика: `shopID`, `shopIDs`, `paymentInstitutionRealm`, `excludeShopIDs`. В случае использования нескольких критериев одновременно в выборку будут включены магазины, подпадающие под хотя бы один из перечисленных критериев. ## Коды ошибок ### Ошибки бизнес-логики Все ошибки бизнес-логики имеют следующий вид: ```json { "code": "string", "message": "string" } ``` В поле `code` содержится тип ошибки, а в `message` - дополнительная информация по произошедшей ошибке. На данный момент существуют следующие коды ошибок: | Код | Описание | | --- | -------- | | **invalidDeadline** | Неверный формат максимального времени обработки запроса. | | **ambiguousPartyID** | Невозможно однозначно определить идентификатор участника, укажите идентификатор в запросе явно. | | **invalidPartyID** | Участник с указанным идентификатором не существует или недоступен. | | **invalidRequest** | Прочие неверные данные запроса. | | **limitExceeded** | Запрашиваемое количество данных должно быть меньше чем указано. | | **badContinuationToken** | Невалидный ContinuationToken. | ### Общие ошибки Ошибки возникающие при попытках совершения операций с незарегистрированными в системе объектами. Имеют вид ```json { "message": "string" } ``` В поле `message` содержится информация по произошедшей ошибке. Например: ```json { "message": "Invalid token" } ``` ### Ошибки обработки запросов В процессе обработки запросов силами нашей платформы могут происходить различные непредвиденные ситуации. Об их появлении платформа сигнализирует по протоколу HTTP соответствующими [статусами][5xx], обозначающими ошибки сервера. | Код | Описание | | ------- | ---------- | | **500** | В процессе обработки платформой запроса возникла непредвиденная ситуация. При получении подобного кода ответа мы рекомендуем обратиться в техническую поддержку. | | **503** | Платформа временно недоступна и не готова обслуживать данный запрос. Запрос гарантированно не выполнен, при получении подобного кода ответа попробуйте выполнить его позднее, когда доступность платформы будет восстановлена. | | **504** | Платформа превысила допустимое время обработки запроса, результат запроса не определён. Попробуйте отправить запрос повторно или выяснить результат выполнения исходного запроса, если повторное исполнение запроса нежелательно. | [5xx]: https://tools.ietf.org/html/rfc7231#section-6.6 Если вы получили ошибку, которой нет в данном описании, обратитесь в техническую поддержку. termsOfService: https://vality.dev/ contact: name: Vality support team email: support@vality.dev url: https://vality.dev/lk/v2 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: "https://api.vality.dev/lk/v2" security: - bearer: [] tags: - name: Search description: | Для получения списка всех инвойсов/платежей указанного магазина необходимо вызвать соответствующий метод платформы. Имеется возможность отфильтровать выборку по определенным статусам. x-displayName: Поиск - name: Reports description: | Один раз в отчетный период платформа автоматически подготавливает и размещает документы в формате XLSX с разбиением по магазину активной категории. Также, каждый документ будет подписан [квалифицированной ЭЦП](https://digital.gov.ru/ru/appeals/faq/31/). Данная подпись является юридически значимой и позволяет полностью отказаться от бумажного документооборота. x-displayName: Отчеты - name: Analytics description: | Аналитические методы по статистике платежей x-displayName: Аналитика paths: "/analytics/payments/amount": $ref: "./paths/analytics@payments@amount.yaml" "/analytics/payments/average": $ref: "./paths/analytics@payments@average.yaml" "/analytics/payments/count": $ref: "./paths/analytics@payments@count.yaml" "/analytics/payments/errors": $ref: "./paths/analytics@payments@errors.yaml" "/analytics/payments/split-amount": $ref: "./paths/analytics@payments@split-amount.yaml" "/analytics/payments/split-count": $ref: "./paths/analytics@payments@split-count.yaml" "/analytics/payments/sub-errors": $ref: "./paths/analytics@payments@sub-errors.yaml" "/analytics/payments-tool": $ref: "./paths/analytics@payments-tool.yaml" "/analytics/refunds/amount": $ref: "./paths/analytics@refunds@amount.yaml" "/analytics/balances/current": $ref: "./paths/analytics@balances@current.yaml" "/analytics/balances/current-shop-balances": $ref: "./paths/analytics@balances@current-shop-balances.yaml" "/analytics/crediting/amount": $ref: "./paths/analytics@crediting@amount.yaml" "/invoices": $ref: "./paths/invoices.yaml" "/payments": $ref: "./paths/payments.yaml" "/refunds": $ref: "./paths/refunds.yaml" "/chargebacks": $ref: "./paths/chargebacks.yaml" "/invoice-templates": $ref: "./paths/invoice-templates.yaml" "/reports": $ref: "./paths/reports.yaml" "/reports/{reportID}": $ref: "./paths/reports@{reportID}.yaml" "/reports/{reportID}/cancel": $ref: "./paths/reports@{reportID}@cancel.yaml" "/reports/{reportID}/files/{fileID}/download": $ref: "./paths/reports@{reportID}@files@{fileID}@download.yaml" components: securitySchemes: bearer: $ref: "./components/security-schemes/bearer.yaml"