#Список оплат

GET /v1/payments

Возвращает список оплат заказов с поддержкой фильтрации и авто-пагинации.

#Параметры

Параметр Тип По умолч. Описание
limit number 50 Количество записей (до 5000). При limit > 50 Вайбкод автоматически запрашивает несколько страниц у Битрикс24
offset number 0 Пропустить N записей. При offset ≥ 2500 рекомендуется limit ≤ 500
select string — Выборка полей: ?select=id,orderId,sum,paid
order object — Сортировка: ?order[id]=desc
filter object — Фильтрация по ключевым полям оплаты.
Синтаксис фильтрации. Пример: ?filter[orderId]=19

#Примеры

#curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/payments?limit=10&filter[paid]=true&order[id]=desc" \
  -H "X-Api-Key: YOUR_API_KEY"

#curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/payments?limit=10&filter[paid]=true&order[id]=desc" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

#JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/payments?limit=10&filter[paid]=true&order[id]=desc', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Найдено ${meta.total} оплат`)

#JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/payments?limit=10&filter[paid]=true&order[id]=desc', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

#Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив оплат (каждая содержит все поля оплаты)
meta.total number Общее количество записей, соответствующих фильтру
meta.hasMore boolean Есть ли ещё записи за пределами limit

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": 17,
      "accountNumber": "19/1",
      "orderId": 19,
      "paySystemId": 11,
      "paySystemName": "Наличные",
      "sum": 0,
      "currency": "RUB",
      "paid": false,
      "datePaid": "2020-05-14T20:00:00.000Z",
      "dateBill": "2020-05-14T20:00:00.000Z",
      "responsibleId": 1,
      "isReturn": "N",
      "comments": "",
      "xmlId": "bx_5ebe943aacfa0"
    },
    {
      "id": 19,
      "accountNumber": "21/1",
      "orderId": 21,
      "paySystemId": 11,
      "paySystemName": "Наличные",
      "sum": 0,
      "currency": "RUB",
      "paid": false,
      "datePaid": "2020-05-17T20:00:00.000Z",
      "dateBill": "2020-05-17T20:00:00.000Z",
      "responsibleId": 1,
      "isReturn": "N",
      "comments": "",
      "xmlId": "bx_5ec2368b6e74d"
    }
  ],
  "meta": {
    "total": 99,
    "hasMore": true
  }
}

Показаны основные поля. Полный ответ оплаты — см. `GET /v1/payments/:id`.

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

403 — нет скоупа:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'sale' scope"
  }
}

#Ошибки

HTTP Код Описание
400 UNKNOWN_FILTER_FIELD Фильтр по полю, которого нет в схеме оплаты
403 SCOPE_DENIED API-ключ не имеет скоупа sale
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

#Известные особенности

Авто-пагинация: при limit > 50 Вайбкод автоматически запрашивает несколько страниц у Битрикс24 и возвращает все записи в одном ответе.

Когда использовать search вместо list: для сложных фильтров с множеством условий удобнее `POST /v1/payments/search` — параметры передаются в body.

Поле isReturn — строка с тремя значениями. Принимает "N" (обычная оплата), "Y" (возврат) и "P" (частичный возврат) — фильтр по нему работает по этим строковым значениям.

#Смотрите также