Inviare i flipbook a Google Sheets

Cosa puoi fare

Due endpoint ti permettono di spostare i dati dei flipbook in un foglio Google tramite il tuo bridge Sheets:

• Inviare righe in una scheda del foglio con un nome — la scheda viene creata automaticamente se non esiste ancora.
• Verificare se il service account può davvero scrivere su un foglio, prima di affidartici.

Insieme ti permettono di aggiungere righe di lead (o qualsiasi dato tabellare) e di confermare prima che il foglio sia condiviso correttamente, così puoi individuare un problema di condivisione prima di inviare i dati, invece di veder rifiutare l'invio con un 403.

Prima di iniziare

• Una chiave API — l'esempio della specifica la invia come header X-Api-Key. Il body della richiesta contiene anche un campo apiKey (una chiave statica che corrisponde alla configurazione del server), che è obbligatorio su entrambi gli endpoint.
• L'URL di base è il tuo bridge Sheets, {sheetsBaseUrl} — l'URL di base esterno del tuo bridge Google Sheets (per esempio, l'URL della web app di Apps Script). È un URL completo e NON è relativo a go.fliplink.me.
• Il body della richiesta è JSON (raw), non form-urlencoded.
• Nessuno dei due endpoint usa un parametro {flipbookId} nel percorso — il foglio di destinazione è identificato dal campo sheetId nel body.

Inviare righe in un foglio

POST {sheetsBaseUrl}/api/push-to-sheets aggiunge righe a un foglio Google e crea automaticamente la scheda con il nome indicato se manca. data può essere un array di oggetti (le chiavi del primo oggetto diventano l'ordine delle colonne, e viene scritta una riga di intestazione quando non è indicato un range esplicito) oppure un array di array (passato così com'è). Il campo facoltativo range accetta la notazione A1, per esempio "Leads!A1"; se omesso, le righe vengono aggiunte dopo l'ultima riga riempita nel foglio indicato.

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

Risposta:

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

Il sheetId è l'id del foglio di calcolo — il valore di 44 caratteri tra /spreadsheets/d/ e /edit nell'URL del foglio. sheetName è la scheda di destinazione, creata se assente.

Verificare se un foglio è scrivibile

POST {sheetsBaseUrl}/api/check-sheet-writable verifica se il service account può scrivere su un foglio. Crea una scheda temporanea, vi scrive una cella e poi elimina la scheda — restituendo IsWritable: true solo se tutti e tre i passaggi riescono, così individua sia "non condiviso con noi" sia "condiviso ma con celle protette".

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

Risposta quando il foglio è condiviso correttamente:

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

Risposta quando il foglio non è condiviso, la scrittura è bloccata, o si verifica un errore di trasporto:

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

Risposta in caso di errore di convalida della richiesta:

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

Errori possibili

Per Push to Sheets:

• Foglio non condiviso con il service account → { "Result": "ERROR", "Message": "Sheet is not editable. Confirm the sheet is shared with the service account as Editor.", "GoogleErrorCode": 403 }
• Chiave errata → { "Result": "ERROR", "Message": "Invalid API key." }
• Body vuoto / niente da inviare → { "Result": "ERROR", "Message": "There is no data to send to google sheet." }

Per Check Sheet Writable:

• Errore di convalida della richiesta → { "Result": "ERROR", "Message": "...", "IsWritable": false }. Una scrittura bloccata o fallita viene riportata come { "Result": "OK", "IsWritable": false } invece che come errore.

Note

• Usa Check Sheet Writable come verifica preliminare prima di Push to Sheets — è più rigoroso di un semplice test di condivisione perché esegue un ciclo effettivo di scrittura-poi-eliminazione, individuando i fogli condivisi ma con celle protette.
• Su Push to Sheets, quando data è un array di oggetti e non è indicato alcun range, viene scritta una riga di intestazione dalle chiavi del primo oggetto; quando data è un array di array, viene passato così com'è.