Пагинация

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 возвращается в упрощённом формате.

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

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

Списочные методы возвращают объект 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Поиск сообщений
• GETСписок сотрудников с заданным параметром query — возвращает упрощённый meta без prev_page/has_next/has_prev. Если вызывать /users без 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);