В ЮKassa вы можете получить информацию не только по конкретному объекту (например, по платежу), но и по нескольким сразу — в формате списка объектов. Это пригодится, если вы хотите свериться по API, выгрузить значительный объем данных в другую систему, провести аналитику или выполнить любые другие задачи, связанные с одновременной обработкой большого количества объектов.
Большинство коллекций API ЮKassa поддерживает массовую выгрузку с помощью списков объектов. Например, вы можете получить список платежей , список возвратов , список чеков или список сделок (если пользуетесь Безопасной сделкой).
У основных ресурсов API ЮKassa методы получения списков имеют одинаковую структуру. К GET-запросу можно добавить параметры для фильтрации объектов по определенным критериям (зависят от коллекции ) и параметры для настройки выдачи результатов.
Параметры для настройки выдачи результатов
Параметр | Тип | Обязательность | Описание |
---|---|---|---|
limit | number | Необязательный | Размер выдачи результатов запроса — количество объектов, передаваемых в ответе. Возможные значения: от 1 до 100. Пример: limit=50 Значение по умолчанию: 10 |
cursor | string | Необязательный | Указатель на следующий фрагмент списка. Пример: cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15 В качестве указателя необходимо использовать значение параметра next_cursor , полученное в ответе на предыдущий запрос (см. Пагинация).Используется, если конец списка не достигнут. |
Пример запроса списка платежей с ограничением количества объектов в выдаче
curl https://api.yookassa.ru/v3/payments?limit=2 \ -u <Идентификатор магазина>:<Секретный ключ> \
В ответ ЮKassa вернет список объектов, удовлетворяющих параметрам запроса. Список будет отсортирован по дате создания объектов в порядке убывания (от новых к старым).
Параметры ответа
Параметр | Тип | Обязательность | Описание |
---|---|---|---|
type | string | Обязательный | Формат выдачи результатов запроса. Возможное значение — list (список) |
items | array | Обязательный | Массив объектов, удовлетворяющих параметрам запроса |
next_cursor | string | Необязательный | Указатель на следующий фрагмент списка (см. Пагинация). Пример: cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15 |
Пример тела ответа
{ "type": "list", "items": [ { "id": "2419a771-000f-5000-9000-1edaf29243f2", "status": "pending", "paid": false, "amount": { "value": "100.00", "currency": "RUB" }, "confirmation": { "type": "redirect", "confirmation_url": "https://yoomoney.ru/api-pages/v2/payment-confirm/epl?orderId=2419a771-000f-5000-9000-1edaf29243f2" }, "created_at": "2019-03-12T11:10:41.802Z", "description": "Заказ №1", "metadata": { "order_id": "37" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false }, { "id": "22e12f66-000f-5000-8000-18db351245c7", "status": "waiting_for_capture", "paid": true, "amount": { "value": "2.00", "currency": "RUB" }, "created_at": "2018-07-18T10:51:18.139Z", "description": "Заказ №72", "expires_at": "2018-07-25T10:52:00.233Z", "metadata": { }, "payment_method": { "type": "bank_card", "id": "22e12f66-000f-5000-8000-18db351245c7", "saved": false, "card": { "first6": "555555", "last4": "4444", "expiry_month": "07", "expiry_year": "2022", "card_type": "MasterCard", "issuer_country": "RU", "issuer_name": "Sberbank" }, "title": "Bank card *4444" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false } ], "next_cursor": "37a5c87d-3984-51e8-a7f3-8de646d39ec15" }
Если в списке результатов больше, чем ограничено параметром
limit
, ЮKassa будет использовать пагинацию — разделит список на фрагменты («страницы»). В этом случае в ответе на исходный запрос вернется первый фрагмент списка и указатель на следующий — в параметре next_cursor
. Для получения следующего фрагмента повторите исходный запрос, добавив к нему параметр cursor
с полученным указателем.Пример запроса списка платежей с указанием следующего фрагмента списка
curl https://api.yookassa.ru/v3/payments?limit=2&cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15 \ -u <Идентификатор магазина>:<Секретный ключ> \
Пример тела ответа, когда достигнут конец списка
{ "type": "list", "items": [ { "id": "22979b7b-000f-5000-9000-1a603a795739", "status": "canceled", "paid": false, "amount": { "value": "2.00", "currency": "RUB" }, "created_at": "2018-05-23T15:24:43.812Z", "metadata": {}, "payment_method": { "type": "bank_card", "id": "22979b7b-000f-5000-9000-1a603a795739", "saved": false }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false, "cancellation_details": { "party": "payment_network", "reason": "payment_method_restricted" } } ] }
ЮKassa ограничивает количество входящих запросов, чтобы повысить стабильность сервиса. Если от вас будет слишком много запросов в течение короткого промежутка времени, ЮKassa вернет HTTP 429 с кодом ошибки
too_many_requests
. В этом случае рекомендуется увеличить интервалы между запросами, чтобы снизить общее количество обращений за единицу времени.Пример тела ответа, когда запросов слишком много
HTTP/2 429 Server: nginx Date: Wed, 20 Apr 2022 14:04:13 GMT Content-Type: application/json Content-Length: 199 Signature: v1 29f2269d 1 MGUCMQCJiMvqupFLDI4PY0dLlmVK6WnqagBVCk7OFP0qScRAALdPcFXaZZsmgzf6MSgasjICMAQZGgYdZolt98rlGJfdA/m2J7DqSuzddc1NLrzZv71eLiTYBAI+PHZ6EfyNKISGKA== { "type" : "error", "id" : "2a9ab90e-f69f-4844-980b-4e3ec4ff1c86", "code" : "too_many_requests", "description" : "Wow, so many requests! Try to use an exponential backoff of your requests." }
Ежесуточные реестрыРеестры для Безопасной сделки