Skip to main content

​
O que são escopos?

Ao criar uma API Key, você define quais escopos ela possui. Um escopo é uma permissão específica para ler ou escrever um recurso. Isso permite criar chaves com acesso mínimo necessário para cada integração.

​
Tabela completa de escopos

EscopoAcessoPlano mínimoDescrição
read:contactsLeituraTodosListar e buscar contatos
write:contactsEscritaTodosCriar, editar e excluir contatos
read:companiesLeituraTodosListar e buscar empresas
write:companiesEscritaTodosCriar, editar e excluir empresas
read:dealsLeituraGrowth+Listar e buscar negócios
write:dealsEscritaGrowth+Criar, editar e excluir negócios
read:pipelinesLeituraTodosListar pipelines e etapas
write:pipelinesEscritaTodosCriar e editar pipelines
read:conversationsLeituraTodosListar e buscar conversas
write:conversationsEscritaTodosAtualizar status e responsável
write:messagesEscritaTodosEnviar mensagens via WhatsApp/Messenger
read:tasksLeituraGrowth+Listar e buscar tarefas
write:tasksEscritaGrowth+Criar, editar e excluir tarefas
read:webhooksLeituraGrowth+Listar assinaturas de webhooks
write:webhooksEscritaGrowth+Criar e editar assinaturas de webhooks
read:broadcastsLeituraGrowth+Listar disparos em massa
write:broadcastsEscritaGrowth+Criar e gerenciar disparos
read:ai_agentsLeituraGrowth+Listar agentes de IA
write:ai_agentsEscritaGrowth+Gerenciar agentes de IA
read:tagsLeituraTodosListar tags da organização
write:tagsEscritaTodosAdicionar e remover tags de recursos
read:membersLeituraTodosListar membros da organização
read:whatsapp_instancesLeituraTodosListar instâncias WhatsApp conectadas
read:messenger_pagesLeituraTodosListar páginas Messenger conectadas
read:instagram_accountsLeituraTodosListar contas Instagram conectadas
read:custom_fieldsLeituraTodosListar campos personalizados
write:custom_fieldsEscritaTodosCriar e editar campos personalizados
read:message_creditsLeituraTodosConsultar saldo e extrato de créditos de mensagem
write:message_creditsEscritaTodosConfigurar recarga e comprar créditos

​
Restrições por plano

Os seguintes escopos não estão disponíveis no plano Starter:
  • read:deals / write:deals
  • read:tasks / write:tasks
  • read:webhooks / write:webhooks
  • read:broadcasts / write:broadcasts
  • read:ai_agents / write:ai_agents
Ao tentar usar um endpoint que requer um escopo restrito, a API retorna: 
{
  "error": {
    "type": "forbidden",
    "message": "Recurso não disponível no seu plano. Faça upgrade para Growth ou superior.",
    "code": "PLAN_RESTRICTION"
  }
}

​
Erro de escopo insuficiente

Se a chave não tiver o escopo necessário para um endpoint: 
{
  "error": {
    "type": "forbidden",
    "message": "Escopo 'write:contacts' necessário.",
    "code": "INSUFFICIENT_SCOPE"
  }
}

​
Boas práticas

  • Princípio do mínimo privilégio: conceda apenas os escopos que a integração realmente precisa
  • Crie chaves separadas por integração: facilita auditar e revogar acessos específicos
  • Prefira read:* quando possível: evite write:* em integrações que só precisam ler dados