Читайте Отправки с ограниченным токеном Management API

Management API — сторона чтения FormFlow: пять маршрутов GET, один bearer-токен и никакой возможности что-либо записать. Это та поверхность, к которой обращаются инструменты Команды, когда им нужны Отправки, уже хранящиеся в FormFlow, а не копия в таблице.

Сделайте токен таким же узким, как задача

Токен принадлежит Команде, а не человеку. При создании ему дают имя, хотя бы одну Способность — submissions:read, refusals:read или forms:read —, при желании список Форм и при желании дату истечения. FormFlow хранит только хеш, поэтому сам токен показывается один раз, при создании, и больше никогда. Отзыв действует сразу; истёкший токен сохраняет строку и освобождает место.

Два из этих параметров делают основную работу. Токен, ограниченный названными Формами, достигает этих Форм и ничего больше. Токен только с forms:read может перечислить метаданные Форм, не прочитав ни одной Отправки. Ни то, ни другое не предпочтение: чтение за пределами досягаемости токена отвечает точно так же, как чтение несуществующей записи, поэтому отсутствующая и запрещённая запись выглядят одинаково.

Пять чтений

Все маршруты находятся под /api/v1/manage и аутентифицируются bearer-токеном в заголовке Authorization.

• GET /api/v1/manage/forms — метаданные Форм. Требует forms:read.

• GET /api/v1/manage/submissions — страница Отправок. Требует submissions:read.

• GET /api/v1/manage/submissions/{uuid} — одна Отправка, включая спам-сигналы, которые опускает список.

• GET /api/v1/manage/refused-submissions — отказы, сохранённые реестром Формы. Требует refusals:read.

• GET /api/v1/manage/attempts/{attemptId} — упорядоченная жизнь одной попытки во всех реестрах, которые её записали.

Тело Отправки индексировано по именам полей и возвращается таким, каким было отправлено. Большинство полей — строки, multiselect — список, поле файла — ссылка с сохранённым именем, а сетка — объект, индексированный по метке строки. Только маршрут одной Отправки возвращает спам-сигналы.

Листайте курсором

Маршруты списков отвечают data и meta. limit принимает от 1 до 200 и по умолчанию 50, порядок — created_at, затем id, по убыванию. meta.has_more говорит, есть ли следующая страница; meta.next_cursor — непрозрачное значение, которое отправляют обратно как cursor. Смещения здесь нет, потому что набор движется, пока вы читаете, и смещение молча пропустило бы или повторило строки.

cursor=""
while :; do
  page=$(curl -sS "https://formflow.digital/api/v1/manage/submissions?limit=100&cursor=$cursor" \
    -H "Authorization: Bearer $FORMFLOW_TOKEN")
  echo "$page" | jq -r '.data[] | [.uuid, .form_id, .created_at] | @tsv'
  cursor=$(echo "$page" | jq -r '.meta.next_cursor // empty')
  [ "$(echo "$page" | jq -r '.meta.has_more')" = "true" ] || break
done

Фильтры намеренно узкие: form_id, since, until, is_spam, unread и q. q — поиск по точному токену по слепому индексу, не поиск подстроки, и он отвечает только там, где включено индексирование поиска.

Проследите отказ до его попытки

Отклонённая Отправка и Отправка — разные записи. Отказ хранится, чтобы клиент мог на него отреагировать; он никогда не доставляется и никогда не становится учтённой Отправкой. У обеих есть идентификатор попытки, и маршрут попытки собирает цепочку этой попытки — трение Preflight, отказ, приём, спасение, восстановление, квитанцию и каждое обязательство доставки — без отправленных значений и без метаданных Отправителя.

Идентификатор попытки сам по себе не уникален, поэтому цепочка всегда привязана к одной Форме. Когда идентификатор есть на нескольких, ответ — 409 с их перечислением, и запрос повторяют с form_uuid, чтобы выбрать.

Где поверхность чтения резка

Ещё три границы стоит знать до того, как строить на этом. Тела расшифровываются внутри FormFlow и возвращаются такими, какими были сохранены, поэтому токен, читающий Отправки, читает персональные данные, и его хранение заслуживает такой же заботы, как сам токен. Строка, чьё тело не удаётся расшифровать, приходит с payload_error равным payload_unavailable, а остальная страница всё равно приходит. И коды точны: 401 для недействительного, истёкшего или отозванного токена; 403 при отсутствующей Способности или недоступном тарифе; 404 когда запись вне досягаемости токена; 422 при недопустимом фильтре или курсоре; 429 с Retry-After при превышении лимита.

Полный контракт — каждый параметр, форма ответа и ошибка — в /docs/api. И запись Списка изменений для v1.0.0 фиксирует API таким, каким он вышел: документированный management API рядом с единственной конечной точкой, принимающей Отправки.