Списки объектов
В Яндекс.Кассе вы можете получить информацию не только по конкретному объекту (например, по платежу), но и по нескольким сразу — в формате списка объектов. Это пригодится, если вы хотите свериться по API, выгрузить значительный объем данных в другую систему, провести аналитику или выполнить любые другие задачи, связанные с одновременной обработкой большого количества объектов.
Для основных ресурсов (платежи, возвраты, чеки) в списках будет информация только об объектах, созданных за последние 3 года.
 Форматы запроса и ответа
Большинство коллекций API Яндекс.Кассы поддерживает массовую выгрузку с помощью списков объектов. Например, вы можете получить список платежей , список возвратов  или список чеков .
У основных ресурсов API Яндекс.Кассы методы получения списков имеют одинаковую структуру. К GET-запросу можно добавить параметры для фильтрации объектов по определенным критериям (зависят от коллекции ) и параметры для настройки выдачи результатов.
Параметры для настройки выдачи результатов
ПараметрТипОбязательностьОписание
limitnumberНеобязательныйРазмер выдачи результатов запроса — количество объектов, передаваемых в ответе. Возможные значения: от 1 до 100. Пример:
limit=50

Значение по умолчанию:
10
cursorstringНеобязательныйУказатель на следующий фрагмент списка. Пример:
cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15

В качестве указателя необходимо использовать значение параметра
next_cursor
, полученное в ответе на предыдущий запрос (см. Пагинация).
Используется, если конец списка не достигнут.
Пример запроса списка платежей с ограничением количества объектов в выдаче
cURL
PHP
Python
curl https://payment.yandex.net/api/v3/payments?limit=2 \
  -u <Идентификатор магазина>:<Секретный ключ> \
В ответ Яндекс.Касса вернет список объектов, удовлетворяющих параметрам запроса. Список будет отсортирован по дате создания объектов в порядке убывания (от новых к старым).
Параметры ответа
ПараметрТипОбязательностьОписание
typestringОбязательныйФормат выдачи результатов запроса. Возможное значение —
list
(список)
itemsarrayОбязательныйМассив объектов, удовлетворяющих параметрам запроса
next_cursorstringНеобязательныйУказатель на следующий фрагмент списка (см. Пагинация). Пример:
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://money.yandex.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": "100001",
        "gateway_id": "1000001"
      },
      "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": "100001",
        "gateway_id": "1000001"
      },
      "refundable": false,
      "test": false
    }
  ],
  "next_cursor": "37a5c87d-3984-51e8-a7f3-8de646d39ec15"
}
 Пагинация
Если в списке результатов больше, чем ограничено параметром
limit
, Яндекс.Касса будет использовать пагинацию — разделит список на фрагменты («страницы»). В этом случае в ответе на исходный запрос вернется первый фрагмент списка и указатель на следующий — в параметре
next_cursor
. Для получения следующего фрагмента повторите исходный запрос, добавив к нему параметр
cursor
с полученным указателем.
Пример запроса списка платежей с указанием следующего фрагмента списка
cURL
PHP
Python
curl https://payment.yandex.net/api/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": "100001",
        "gateway_id": "1000001"
      },
      "refundable": false,
      "test": false,
      "cancellation_details": {
        "party": "payment_network",
        "reason": "payment_method_restricted"
      }
    }
  ]
}
 Ограничение количества запросов
Яндекс.Касса ограничивает количество входящих запросов, чтобы повысить стабильность сервиса. Если от вас будет слишком много запросов в течение короткого промежутка времени, Яндекс.Касса вернет HTTP-код 429 с кодом ошибки
too_many_requests
. В этом случае рекомендуется увеличить интервалы между запросами, чтобы снизить общее количество обращений за единицу времени.
Пример тела ответ, когда запросов слишком много
JSON
{
  "type": "error",
  "code": "too_many_requests",
  "description": "Wow, so many requests! Try to use an exponential backoff of your requests.",
  "id": "a8c33ab1-ddbf-43cd-990b-f3a943cafe3c"
}
 Что почитать еще
Списки платежейСписки возвратовСписки чековЕжесуточные реестры