Escolher os escopos
Escopo é a permissão do token: o que ele pode ler e o que pode escrever. A regra é dar o mínimo que a integração usa. Se um token vazar, o estrago é do tamanho do escopo.
Como escolher
Na criação da integração (Criar seu token), a aba Escopos lista cada área com duas opções: leitura (readonly) e escrita (write). Escrita inclui leitura.
Pergunte pra cada área: a integração só consulta ou também cria/altera?
Escopos por tipo de projeto
| Projeto | Escopos |
|---|---|
| Site envia lead | contacts.write, opportunities.write |
| ERP sincroniza clientes | contacts.write, locations/customFields.readonly, locations/tags.readonly |
| Enviar mensagem a partir do seu sistema | contacts.readonly, conversations/message.write |
| Agendar pelo seu sistema | contacts.readonly, calendars.readonly, calendars/events.write |
| BI só lendo | contacts.readonly, opportunities.readonly, conversations.readonly, users.readonly |
| Descobrir ids de pipeline e fase | opportunities.readonly |
Os escopos mais usados
| Escopo | Libera |
|---|---|
contacts.readonly / contacts.write | Ler e escrever contatos, etiquetas e campos do contato |
opportunities.readonly / opportunities.write | Oportunidades e a lista de pipelines e fases |
conversations.readonly | Ler conversas e mensagens |
conversations/message.write | Enviar mensagem |
calendars.readonly / calendars.write | Calendários e configuração |
calendars/events.readonly / calendars/events.write | Compromissos |
locations/customFields.readonly | Lista de campos personalizados e seus ids |
locations/tags.readonly | Lista de etiquetas |
users.readonly | Lista de usuários (pra atribuir dono) |
workflows.readonly | Lista de automações |
Errou o escopo
A chamada volta 401 com uma mensagem mencionando escopo. Abra a integração em Configurações > Integrações Privado, edite os escopos e salve. O token continua o mesmo; não precisa trocar no seu sistema.
Um token por integração
Site e ERP com tokens separados, cada um com o seu escopo. Se o site vazar o token, você revoga só ele, e o ERP continua rodando.