Enviar flipbooks para o Google Sheets

O que você pode fazer

Dois endpoints permitem mover dados de flipbooks para uma planilha do Google por meio da sua ponte do Sheets:

• Push — insira linhas em uma aba de planilha com nome — a aba é criada automaticamente se ainda não existir.
• Check — verifique se a conta de serviço realmente consegue gravar em uma planilha, antes de depender disso.

Entre os dois, você pode anexar linhas de leads (ou qualquer dado tabular) e confirmar antes que a planilha está compartilhada corretamente, para pegar um problema de compartilhamento antes de enviar, em vez de ter o envio rejeitado com um 403.

Antes de começar

• Uma chave de API — o exemplo da spec a envia como cabeçalho X-Api-Key. O corpo da requisição também carrega um campo apiKey (uma chave estática que corresponde à configuração do servidor), que é obrigatório nos dois endpoints.
• A URL base é a sua ponte do Sheets, {sheetsBaseUrl} — a URL base externa da sua ponte do Google Sheets (por exemplo, a URL do web app do Apps Script). É uma URL completa e NÃO é relativa a go.fliplink.me.
• O corpo da requisição é JSON (raw), não form-urlencoded.
• Nenhum dos endpoints usa parâmetro de caminho {flipbookId} — a planilha de destino é identificada pelo campo sheetId do corpo.

Insira linhas em uma planilha

POST {sheetsBaseUrl}/api/push-to-sheets anexa linhas a uma planilha do Google e cria automaticamente a aba com nome se ela estiver faltando. data pode ser um array de objetos (as chaves do primeiro objeto viram a ordem das colunas, e uma linha de cabeçalho é gravada quando nenhum range explícito é informado) ou um array de arrays (repassado como está). O campo opcional range recebe notação A1, por exemplo "Leads!A1"; se omitido, as linhas são anexadas após a última linha preenchida na planilha com nome.

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"
  }'

Resposta:

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

O sheetId é o id da planilha — o valor de 44 caracteres entre /spreadsheets/d/ e /edit na URL da planilha. sheetName é a aba de destino, criada se estiver ausente.

Verifique se uma planilha é gravável

POST {sheetsBaseUrl}/api/check-sheet-writable verifica se a conta de serviço consegue gravar em uma planilha. Ele cria uma aba temporária, grava uma célula nela e depois exclui a aba — retornando IsWritable: true só se as três etapas forem bem-sucedidas, então ele pega tanto "não compartilhada conosco" quanto "compartilhada, mas com células protegidas".

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"
  }'

Resposta quando a planilha está compartilhada corretamente:

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

Resposta quando a planilha não está compartilhada, a gravação é bloqueada ou ocorre um erro de transporte:

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

Resposta em uma falha de validação da requisição:

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

Erros possíveis

Para o Push to Sheets:

• Planilha não compartilhada com a conta de serviço → { "Result": "ERROR", "Message": "Sheet is not editable. Confirm the sheet is shared with the service account as Editor.", "GoogleErrorCode": 403 }
• Chave incorreta → { "Result": "ERROR", "Message": "Invalid API key." }
• Corpo vazio / nada a enviar → { "Result": "ERROR", "Message": "There is no data to send to google sheet." }

Para o Check Sheet Writable:

• Falha de validação da requisição → { "Result": "ERROR", "Message": "...", "IsWritable": false }. Uma gravação bloqueada ou que falhou é reportada como { "Result": "OK", "IsWritable": false } em vez de um erro.

Notas

• Use o Check Sheet Writable como uma verificação prévia antes do Push to Sheets — ele é mais rigoroso que um teste de compartilhamento simples, porque exercita um ciclo real de gravar-depois-excluir, pegando planilhas que estão compartilhadas mas têm células protegidas.
• No Push to Sheets, quando data é um array de objetos e nenhum range é informado, uma linha de cabeçalho é gravada a partir das chaves do primeiro objeto; quando data é um array de arrays, ele é repassado como está.