Пагинация

API Пачки использует cursor-based пагинацию для всех методов, возвращающих списки. Это обеспечивает стабильную работу при добавлении и удалении записей.

Две группы методов с пагинацией

В API существует две группы методов, возвращающих разную структуру meta — алгоритмы обхода и условия конца данных у них отличаются. Перед интеграцией убедитесь, что вы знаете, к какой группе относится используемый метод.

• Списочные методы — возвращают meta.paginate с четырьмя полями: next_page, prev_page, has_next, has_prev.
• Методы поиска — возвращают meta с полем total и paginate.next_page (только курсор «вперёд», без prev_page/has_next/has_prev). Отдельно стоит GETСписок сотрудников с заданным параметром query: в его meta.paginate есть только next_page и has_next.

Параметры запроса

Списочные методы

Списочные методы возвращают объект meta.paginate с четырьмя полями:

{  "data": [{ "id": 1, "...": "..." }, { "id": 2, "...": "..." }],  "meta": {    "paginate": {      "next_page": "eyJpZCI6MTAsIl9rZCI6Im4ifQ",      "prev_page": "eyJpZCI6MSwgIl9rZCI6InAifQ",      "has_next": true,      "has_prev": false    }  }}

К этой группе относятся: GETСписок сотрудников (без query), GETСписок чатов, GETСписок участников чата, GETСписок сообщений чата, GETСписок реакций, GETСписок прочитавших сообщение, GETСписок тегов, GETСписок сотрудников тега, GETСписок напоминаний, GETЖурнал аудита событий, GETИстория событий.

Сценарии и состояния meta.paginate

Поведение полей meta.paginate для типичных сценариев пагинации (на примере метода GETСписок чатов с DESC-сортировкой):

Курсоры next_page и prev_page остаются валидными даже на пустом ответе — можно безопасно повторять запрос с тем же курсором, не теряя точку отсчёта.

Методы поиска

Методы поиска используют отдельный формат meta — без prev_page и без флагов has_next/has_prev. Вместо них возвращается total — общее количество найденных результатов:

{  "data": [{ "id": 1, "...": "..." }, { "id": 2, "...": "..." }],  "meta": {    "total": 42,    "paginate": {      "next_page": "eyJpZCI6MTAsIl9rZCI6Im4ifQ"    }  }}

К этой группе относятся:

• GETПоиск сотрудников
• GETПоиск чатов
• GETПоиск сообщений

Список сотрудников с параметром query

GETСписок сотрудников с заданным параметром query ищет по сотрудникам и возвращает meta.paginate только с двумя полями: next_page и has_next. Полей prev_page, has_prev и total в ответе нет. Курсор next_page приходит и на последней странице, поэтому конец списка — has_next: false, как у списочных методов. Без query ответ соответствует группе «Списочные методы» с полным meta.paginate.

Обход всех записей

Передайте next_page в параметр cursor следующего запроса. Условие остановки зависит от группы метода: для списочных — has_next: false, для методов поиска — равенство числа полученных записей значению total.

Для списочных методов

const TOKEN = 'ваш_токен';const BASE = 'https://api.pachca.com/api/shared/v1';const headers = { Authorization: `Bearer ${TOKEN}` }; const allChats = [];let cursor;let hasNext = true; while (hasNext) {  const url = new URL(`${BASE}/chats`);  url.searchParams.set('limit', '50');  if (cursor) url.searchParams.set('cursor', cursor);   const res = await fetch(url, { headers });  const json = await res.json();  allChats.push(...json.data);   cursor = json.meta.paginate.next_page;  hasNext = json.meta.paginate.has_next;} console.log(`Всего чатов: ${allChats.length}`);

Для методов поиска

const TOKEN = 'ваш_токен';const BASE = 'https://api.pachca.com/api/shared/v1';const headers = { Authorization: `Bearer ${TOKEN}` }; const allMessages = [];let cursor;let total = Infinity; while (allMessages.length < total) {  const url = new URL(`${BASE}/search/messages`);  url.searchParams.set('query', 'отчёт');  url.searchParams.set('limit', '200');  if (cursor) url.searchParams.set('cursor', cursor);   const res = await fetch(url, { headers });  const json = await res.json();  allMessages.push(...json.data);   if (json.data.length === 0) break;  total = json.meta.total;  cursor = json.meta.paginate.next_page;} console.log(`Всего найдено: ${allMessages.length} из ${total}`);

Polling новых данных

Курсор prev_page доступен только в списочных методах и позволяет получать записи, появившиеся «перед» первой страницей, без полного рефетча. Это полезно для отслеживания новых сообщений в чате, новых чатов и других обновлений. В методах поиска prev_page отсутствует — там polling новых результатов через курсор не предусмотрен.

Алгоритм

1. Выполните первый запрос без курсора и сохраните prev_page из ответа.
2. Периодически делайте запрос с cursor=prev_page.
3. Если data не пуст — появились новые записи. Обновите prev_page из ответа.
4. Если has_prev равен true — новых записей больше, чем limit. Продолжайте запрашивать по prev_page, пока has_prev не станет false.

Пока новых записей нет, ответ возвращает пустой data и тот же prev_page — можно безопасно повторять запрос с тем же курсором, не теряя точку отсчёта.

const TOKEN = 'ваш_токен';const BASE = 'https://api.pachca.com/api/shared/v1';const headers = { Authorization: `Bearer ${TOKEN}` }; // Первый запрос — загрузка начального спискаconst initial = await fetch(`${BASE}/chats?limit=50`, { headers });const initialJson = await initial.json();let prevCursor = initialJson.meta.paginate.prev_page;const chats = new Map(initialJson.data.map(c => [c.id, c])); // Polling — проверка новых данных каждые 5 секундsetInterval(async () => {  let hasPrev = true;   while (hasPrev) {    const url = new URL(`${BASE}/chats`);    url.searchParams.set('limit', '50');    url.searchParams.set('cursor', prevCursor);     const res = await fetch(url, { headers });    const json = await res.json();     // Дедупликация по id и обновление позиции в сортировке    for (const chat of json.data) {      chats.set(chat.id, chat);    }     prevCursor = json.meta.paginate.prev_page;    hasPrev = json.meta.paginate.has_prev;  }}, 5000);