Guia do Google Planilhas

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/catalog devolve 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 caminhoPara que serve
GET /google-sheets/catalogCatálogo das colunas.
POST /google-sheetsCria a planilha (num arquivo novo ou, com spreadsheetId, como aba nova de um arquivo do workspace).
POST /google-sheets/workbookCria 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}/columnsAdiciona 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}/rowsAdiciona uma linha. Exige o cabeçalho Idempotency-Key.
POST /google-sheets/files/{spreadsheetId}/edit-sessionComeç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

CampoTipoRegra
titlestringObrigatório, até 200 caracteres.
fileTitlestringNome do arquivo novo. Obrigatório sem spreadsheetId, até 200 caracteres, sem quebras de linha.
spreadsheetIdstringOpcional. Cria a planilha como aba de um arquivo que já tem planilhas deste workspace.
tabNamestringNome da aba (padrão: title), até 100 caracteres, sem ', [, ], *, ?, /, \ e :.
tabPeriodstringnone (padrão) ou month, que abre uma aba por mês.
tabPatternstringSó 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}.
stylestringplain, graphite (padrão), blue, green ou purple.
descriptionstringOpcional.
timeZonestringFuso IANA (padrão America/Sao_Paulo).
columnslistaAo menos uma coluna.
uniqueobjetoOpcional. 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

CampoRegra
headerObrigatório, até 200 caracteres. Não pode repetir outro cabeçalho da planilha, sem diferenciar maiúsculas e acentos.
typeUm dos tipos abaixo.
sourceDe onde vem o valor: input (padrão) ou uma origem do sistema.
requiredSe a linha precisa trazer o valor.
instructionAté 500 caracteres. Orienta quem preenche a coluna.
optionsSó no tipo choice, e obrigatório nele: opções de até 200 caracteres, sem vazias nem repetidas.
colorsSó no tipo choice: a cor de cada opção (green, red, amber, blue ou purple).
linkSheetId, linkLabelSó 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:

OrigemTipoValor
written_atdatetimeMomento da gravação.
lead_nametextNome do lead.
lead_phonephoneTelefone do lead.
lead_emailemailE-mail do lead.
conversation_linkurlLink da conversa.
origintextNome de quem registrou a linha.
message_sent_atdatetimePor mensagem: quando foi enviada.
message_sendertextPor mensagem: quem enviou.
message_directiontextPor mensagem: a direção.
message_textlong_textPor mensagem: o texto.
message_media_urlurlPor mensagem: o link da mídia.
export_linklinkLink 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

CampoRegra
modenone (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.
columnIndexesNa criação, com columns: as posições, neste pedido, das colunas comparadas.
columnsEm PATCH /google-sheets/{id}, com columns: as chaves das colunas comparadas.
onRepeatskip (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 caminhoPara que serve
GET /google-sheets/files/{spreadsheetId}/edit-sessionEstado: a sessão em andamento (editing) ou null, heartbeatSeconds e leaseSeconds.
POST /google-sheets/files/{spreadsheetId}/edit-sessionComeça a sessão. Só uma pessoa edita o arquivo por vez.
POST /google-sheets/edit-sessions/{sessionId}/heartbeatSinal de presença, só de quem começou.
POST /google-sheets/edit-sessions/{sessionId}/endTermina a sessão, com reason finished ou left, e confere as abas.
POST /google-sheets/edit-sessions/{sessionId}/force-endEncerra a sessão de outra pessoa; exige a permissão de remover planilhas.
GET /google-sheets/files/{spreadsheetId}/edit-sessionsHistó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ódigoStatusQuando
google_sheet_source_type_mismatch400A origem do sistema exige outro tipo.
google_sheet_header_repeated400Dois cabeçalhos iguais.
google_sheet_per_message_required400Coluna por mensagem marcada como obrigatória.
google_sheet_unique_column_not_allowed400Coluna que não vale para a linha única.
google_sheet_invalid_value, google_sheet_value_not_in_options, google_sheet_required_column_missing422Valor da linha fora do tipo, fora das opções ou ausente.
google_sheet_idempotency_key_required400Falta o Idempotency-Key ao adicionar uma linha.
google_sheet_changed409A planilha mudou depois da versão enviada.
google_sheet_file_being_edited409Alguém está editando o arquivo à mão.
google_sheet_not_found404A planilha não existe no workspace.
google_sheet_google_busy429O limite do Google para este minuto foi atingido.