Отправка флипбуков в Google Sheets

Что можно сделать

Два эндпоинта позволяют переносить данные флипбука в Google-таблицу через ваш коннектор Sheets:

• Отправить строки в именованную вкладку таблицы — вкладка создаётся автоматически, если её ещё нет.
• Проверить, действительно ли сервисный аккаунт может писать в таблицу, прежде чем полагаться на это.

Вместе они позволяют добавлять строки лидов (или любые табличные данные) и сначала подтверждать, что таблице корректно открыт общий доступ, — так вы поймаете проблему с доступом до отправки, а не получите отказ на отправку с 403.

Перед началом

• API-ключ — в примере спецификации он передаётся в заголовке X-Api-Key. Тело запроса также содержит поле apiKey (статический ключ, совпадающий с конфигурацией сервера), которое обязательно для обоих эндпоинтов.
• Базовый URL — это ваш коннектор Sheets, {sheetsBaseUrl} — внешний базовый URL вашего коннектора Google Sheets (например, URL веб-приложения Apps Script). Это полный URL, он НЕ относителен к go.fliplink.me.
• Тело запроса — это JSON (raw), а не form-urlencoded.
• Ни один из эндпоинтов не использует параметр пути {flipbookId} — целевая таблица определяется полем тела sheetId.

Отправка строк в таблицу

POST {sheetsBaseUrl}/api/push-to-sheets добавляет строки в Google-таблицу и автоматически создаёт именованную вкладку, если она отсутствует. data может быть массивом объектов (ключи первого объекта задают порядок столбцов, и строка заголовков записывается, если явный range не указан) или массивом массивов (передаётся как есть). Необязательное поле range принимает нотацию A1, например "Leads!A1"; если оно опущено, строки добавляются после последней заполненной строки в именованной таблице.

curl -X POST '{sheetsBaseUrl}/api/push-to-sheets' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "sheetId": "YOUR_SHEET_ID",
    "sheetName": "Leads",
    "data": [
      { "Name": "Alice", "Email": "alice@corp.com" },
      { "Name": "Bob", "Email": "bob@corp.com" }
    ],
    "range": "Leads!A1"
  }'

Ответ:

{ "Result": "OK", "Message": "Data pushed to Google Sheet.", "RowsAppended": 2 }

sheetId — это id таблицы, 44-символьное значение между /spreadsheets/d/ и /edit в URL таблицы. sheetName — целевая вкладка, создаётся, если отсутствует.

Проверка, доступна ли таблица для записи

POST {sheetsBaseUrl}/api/check-sheet-writable проверяет, может ли сервисный аккаунт писать в таблицу. Он создаёт временную вкладку, записывает в неё одну ячейку, затем удаляет вкладку — возвращая IsWritable: true только если все три шага прошли успешно, поэтому он ловит и «нам не открыли доступ», и «доступ открыт, но ячейки защищены».

curl -X POST '{sheetsBaseUrl}/api/check-sheet-writable' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "sheetId": "YOUR_SHEET_ID"
  }'

Ответ, когда таблице корректно открыт общий доступ:

{ "Result": "OK", "IsWritable": true }

Ответ, когда таблице не открыт доступ, запись заблокирована или возникает ошибка передачи:

{ "Result": "OK", "IsWritable": false }

Ответ при ошибке валидации запроса:

{ "Result": "ERROR", "Message": "...", "IsWritable": false }

Возможные ошибки

Для Push to Sheets:

• Сервисному аккаунту не открыт доступ к таблице → { "Result": "ERROR", "Message": "Sheet is not editable. Confirm the sheet is shared with the service account as Editor.", "GoogleErrorCode": 403 }
• Неверный ключ → { "Result": "ERROR", "Message": "Invalid API key." }
• Пустое тело / нечего отправлять → { "Result": "ERROR", "Message": "There is no data to send to google sheet." }

Для Check Sheet Writable:

• Ошибка валидации запроса → { "Result": "ERROR", "Message": "...", "IsWritable": false }. Заблокированная или неудавшаяся запись сообщается как { "Result": "OK", "IsWritable": false }, а не как ошибка.

Примечания

• Используйте Check Sheet Writable как предварительную проверку перед Push to Sheets — она строже простого теста доступа, потому что выполняет реальный цикл «запись-затем-удаление», отлавливая таблицы, которым открыт доступ, но которые имеют защищённые ячейки.
• В Push to Sheets, когда data — массив объектов и range не указан, строка заголовков записывается из ключей первого объекта; когда data — массив массивов, он передаётся как есть.