Работа со списками объектов — Прием платежей по API ЮKassa

Работа со списками объектов

В ЮKassa вы можете получить информацию не только по конкретному объекту (например, по платежу), но и по нескольким сразу — в формате списка объектов. Это пригодится, если вы хотите свериться по API, выгрузить значительный объем данных в другую систему, провести аналитику или выполнить любые другие задачи, связанные с одновременной обработкой большого количества объектов.

Для основных ресурсов (платежи, возвраты, чеки) в списках будет информация только об объектах, созданных за последние 3 года.

Форматы запроса и ответа

Большинство коллекций API ЮKassa поддерживает массовую выгрузку с помощью списков объектов. Например, вы можете получить список платежей , список возвратов , список чеков или список сделок (если пользуетесь Безопасной сделкой).

У основных ресурсов API ЮKassa методы получения списков имеют одинаковую структуру. К GET-запросу можно добавить параметры для фильтрации объектов по определенным критериям (зависят от коллекции ) и параметры для настройки выдачи результатов.

Параметры для настройки выдачи результатов

Параметр	Тип	Обязательность	Описание
limit	number	Необязательный	Размер выдачи результатов запроса — количество объектов, передаваемых в ответе. Возможные значения: от 1 до 100. Пример: `limit=50` Значение по умолчанию: `10`
cursor	string	Необязательный	Указатель на следующий фрагмент списка. Пример: `cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15` В качестве указателя необходимо использовать значение параметра `next_cursor`, полученное в ответе на предыдущий запрос (см. Пагинация). Используется, если конец списка не достигнут.

Пример запроса списка платежей с ограничением количества объектов в выдаче

cURL
PHP
Python
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`

Пример тела ответа

JSON
  {
  "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
PHP
Python
curl https://api.yookassa.ru/v3/payments?limit=2&cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15 \
  -u <Идентификатор магазина>:<Секретный ключ> \

Пример тела ответа, когда достигнут конец списка

JSON
{
  "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
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."
}

Что почитать еще

Ежесуточные реестры Реестры для Безопасной сделки