Como definir uma planilha do Google com colunas tipadas, valores preenchidos pelo sistema, linha única e edição à mão do arquivo.
Uma planilha é uma aba de um arquivo do Google, criada no Drive da conta conectada ao Google Planilhas e registrada no workspace. Ela tem colunas com tipo e origem; agentes, fluxos e pessoas registram linhas, e a plataforma grava essas linhas no Google em fila. Várias planilhas podem ser abas do mesmo arquivo.
GET /google-sheets/catalogdevolve os tipos de coluna, as origens do sistema com o tipo que cada uma exige, os estilos, as cores, os limites, os modos de linha única e os códigos de erro das linhas. As rotas estão no grupo Google Planilhas da Referência da API.
Rotas principais
| Método e caminho | Para que serve |
|---|---|
GET /google-sheets/catalog | Catálogo das colunas. |
POST /google-sheets | Cria a planilha (num arquivo novo ou, com spreadsheetId, como aba nova de um arquivo do workspace). |
POST /google-sheets/workbook | Cria várias planilhas como abas de um só arquivo, na ordem pedida. |
GET /google-sheets/{id} | A planilha com as colunas e a configuração. id é o id no painel, não o do arquivo no Google. |
PATCH /google-sheets/{id} | Muda título, descrição e linha única. |
PATCH /google-sheets/{id}/columns | Adiciona colunas ao fim, renomeia cabeçalhos, muda instruções e obrigatoriedade, arquiva colunas e acrescenta opções. Tipo e chave não mudam. |
POST /google-sheets/{id}/rows | Adiciona uma linha. Exige o cabeçalho Idempotency-Key. |
POST /google-sheets/files/{spreadsheetId}/edit-session | Começa a edição à mão do arquivo. |
PATCH /google-sheets/{id}, PATCH /google-sheets/{id}/columns e PATCH /google-sheets/{id}/layout recebem version, a versão lida; uma planilha que mudou depois responde 409 google_sheet_changed.
Criar uma planilha
| Campo | Tipo | Regra |
|---|---|---|
title | string | Obrigatório, até 200 caracteres. |
fileTitle | string | Nome do arquivo novo. Obrigatório sem spreadsheetId, até 200 caracteres, sem quebras de linha. |
spreadsheetId | string | Opcional. Cria a planilha como aba de um arquivo que já tem planilhas deste workspace. |
tabName | string | Nome da aba (padrão: title), até 100 caracteres, sem ', [, ], *, ?, /, \ e :. |
tabPeriod | string | none (padrão) ou month, que abre uma aba por mês. |
tabPattern | string | Só com month. Usa {mes} (nome do mês), {mm} (número do mês) e {ano}; precisa ter {ano} e {mes} ou {mm}. Padrão: o título seguido de · {mes} {ano}. |
style | string | plain, graphite (padrão), blue, green ou purple. |
description | string | Opcional. |
timeZone | string | Fuso IANA (padrão America/Sao_Paulo). |
columns | lista | Ao menos uma coluna. |
unique | objeto | Opcional. A regra de linha única. |
No Google, a coluna A da aba é a referência de cada linha (cabeçalho ref), e as colunas da planilha vêm depois, na ordem enviada.
Colunas
| Campo | Regra |
|---|---|
header | Obrigatório, até 200 caracteres. Não pode repetir outro cabeçalho da planilha, sem diferenciar maiúsculas e acentos. |
type | Um dos tipos abaixo. |
source | De onde vem o valor: input (padrão) ou uma origem do sistema. |
required | Se a linha precisa trazer o valor. |
instruction | Até 500 caracteres. Orienta quem preenche a coluna. |
options | Só no tipo choice, e obrigatório nele: opções de até 200 caracteres, sem vazias nem repetidas. |
colors | Só no tipo choice: a cor de cada opção (green, red, amber, blue ou purple). |
linkSheetId, linkLabel | Só na origem export_link. |
A resposta traz a key de cada coluna, derivada do cabeçalho: minúsculas sem acento, com _ no lugar do resto, até 40 caracteres, com c_ na frente quando começa por dígito e _2, _3 quando repete. As linhas usam essas chaves.
Tipos (type): text, long_text, number, money, date, datetime, boolean, choice, email, phone, url e link (este só com a origem export_link).
Origens preenchidas pelo sistema (source), com o tipo que cada uma exige:
| Origem | Tipo | Valor |
|---|---|---|
written_at | datetime | Momento da gravação. |
lead_name | text | Nome do lead. |
lead_phone | phone | Telefone do lead. |
lead_email | email | E-mail do lead. |
conversation_link | url | Link da conversa. |
origin | text | Nome de quem registrou a linha. |
message_sent_at | datetime | Por mensagem: quando foi enviada. |
message_sender | text | Por mensagem: quem enviou. |
message_direction | text | Por mensagem: a direção. |
message_text | long_text | Por mensagem: o texto. |
message_media_url | url | Por mensagem: o link da mídia. |
export_link | link | Link para as mensagens exportadas em outra planilha do mesmo arquivo. |
Colunas por mensagem e de export_link não podem ser obrigatórias. export_link exige linkSheetId (ou linkSheetRef em POST /google-sheets/workbook, apontando para uma planilha anterior do pedido); linkLabel tem até 60 caracteres e o padrão é "Ver mensagens". Ao adicionar uma linha, values traz os valores pelas chaves das colunas input; enviar valor para uma coluna do sistema é recusado com google_sheet_system_column.
Linha única
| Campo | Regra |
|---|---|
mode | none (padrão, cada registro vira uma linha), conversation (uma linha por conversa) ou columns (os valores das colunas escolhidas não se repetem). Numa aba mensal, a regra vale dentro de cada mês. |
columnIndexes | Na criação, com columns: as posições, neste pedido, das colunas comparadas. |
columns | Em PATCH /google-sheets/{id}, com columns: as chaves das colunas comparadas. |
onRepeat | skip (padrão): um registro repetido não é gravado de novo. |
Só valem colunas não arquivadas das origens input, lead_name, lead_phone, lead_email, conversation_link e origin; colunas de link, de data de gravação e por mensagem são recusadas. Uma linha repetida responde 409 com google_sheet_already_recorded_conversation, google_sheet_already_recorded_columns ou as variantes _month das abas mensais, com details.rowId da linha existente. Em conversation, a adição manual é recusada com google_sheet_unique_needs_conversation. Trocar a regra vale para as próximas gravações, e as linhas que o painel ainda guarda (gravadas nos últimos 30 dias ou ainda na fila) passam a contar.
Exemplo
POST /google-sheets
{
"fileTitle": "Matrículas 2026",
"title": "Matrículas",
"tabPeriod": "month",
"tabPattern": "Matrículas · {mes} {ano}",
"style": "blue",
"columns": [
{ "header": "Gravado em", "type": "datetime", "source": "written_at", "required": false },
{ "header": "Aluno", "type": "text", "source": "lead_name", "required": false },
{ "header": "Matrícula", "type": "text", "required": true, "instruction": "Número da matrícula informado pelo aluno" },
{ "header": "Curso", "type": "choice", "required": true, "options": ["Administração", "Direito", "Enfermagem"], "colors": { "Direito": "purple" } },
{ "header": "Valor da mensalidade", "type": "money", "required": false },
{ "header": "Conversa", "type": "url", "source": "conversation_link", "required": false }
],
"unique": { "mode": "columns", "columnIndexes": [2], "onRepeat": "skip" }
}As chaves geradas são gravado_em, aluno, matricula, curso, valor_da_mensalidade e conversa, e a linha única compara matricula dentro de cada mês.
Edição à mão do arquivo
Uma sessão de edição trava o arquivo inteiro para alguém editar no Google. Enquanto ela durar, nada é gravado no arquivo automaticamente: as linhas novas ficam na fila, e mudanças de colunas, abas novas, reparos e remoções de linha são recusados com 409 google_sheet_file_being_edited.
| Método e caminho | Para que serve |
|---|---|
GET /google-sheets/files/{spreadsheetId}/edit-session | Estado: a sessão em andamento (editing) ou null, heartbeatSeconds e leaseSeconds. |
POST /google-sheets/files/{spreadsheetId}/edit-session | Começa a sessão. Só uma pessoa edita o arquivo por vez. |
POST /google-sheets/edit-sessions/{sessionId}/heartbeat | Sinal de presença, só de quem começou. |
POST /google-sheets/edit-sessions/{sessionId}/end | Termina a sessão, com reason finished ou left, e confere as abas. |
POST /google-sheets/edit-sessions/{sessionId}/force-end | Encerra a sessão de outra pessoa; exige a permissão de remover planilhas. |
GET /google-sheets/files/{spreadsheetId}/edit-sessions | Histórico de sessões do arquivo. |
O sinal de presença vai a cada 30 segundos; sem ele, a sessão termina sozinha 2 minutos depois do último, e nenhuma passa de 4 horas (deadline). endReason é finished, left, expired ou ended_by_admin. Ao terminar, check.status é ok, broken (abas com reason, detail e repairable) ou unchecked (o Google não pôde ser lido agora).
Erros
Uma definição recusada responde 400 com um código próprio e o local do problema em details (field, column, key, header, option, limit):
{
"error": true,
"code": "google_sheet_unique_column_not_allowed",
"message": "googlesheet: invalid sheet definition: google_sheet_unique_column_not_allowed: coluna \"Gravado em\"",
"details": { "field": "unique", "column": 0, "key": "gravado_em", "header": "Gravado em" }
}| Código | Status | Quando |
|---|---|---|
google_sheet_source_type_mismatch | 400 | A origem do sistema exige outro tipo. |
google_sheet_header_repeated | 400 | Dois cabeçalhos iguais. |
google_sheet_per_message_required | 400 | Coluna por mensagem marcada como obrigatória. |
google_sheet_unique_column_not_allowed | 400 | Coluna que não vale para a linha única. |
google_sheet_invalid_value, google_sheet_value_not_in_options, google_sheet_required_column_missing | 422 | Valor da linha fora do tipo, fora das opções ou ausente. |
google_sheet_idempotency_key_required | 400 | Falta o Idempotency-Key ao adicionar uma linha. |
google_sheet_changed | 409 | A planilha mudou depois da versão enviada. |
google_sheet_file_being_edited | 409 | Alguém está editando o arquivo à mão. |
google_sheet_not_found | 404 | A planilha não existe no workspace. |
google_sheet_google_busy | 429 | O limite do Google para este minuto foi atingido. |