Escopos

Produtos dentro de um negócio pedem dois escopos. Ler as linhas de produto de um negócio exige products:read e deals:read; adicionar, editar, remover ou subs…

Grupo Escopo O que você perde sem ele
Contatos contacts:read ler contatos
Contatos contacts:write criar e editar contatos
Empresas companies:read ler empresas
Empresas companies:write criar e editar empresas
Negócios deals:read ler negócios
Negócios deals:write criar e editar negócios
Tarefas tasks:read ler tarefas
Tarefas tasks:write criar e editar tarefas
Leads leads:write injetar leads novos no CRM
Leads leads:read conferir o que já foi enviado pela porta de leads (external_ref)
Importação import:write informar created_at/updated_at (e, em anotações, author_id/author_name/attachments; em tarefas, completed_at) originais na criação — sem ele, tudo nasce com a data de agora
Tags tags:read ver as tags de contatos, empresas e negócios
Tags tags:write criar e aplicar tags
Equipe users:read listar as pessoas da equipe
Funis funnels:read listar funis e etapas (e descobrir o id de cada coluna)
Funis funnels:write criar funil e mexer nas etapas
Conversas conversations:read ler conversas e mensagens
Conversas conversations:write responder, atribuir e resolver conversa, e acionar o agente de IA nela
Agenda agenda:read ler compromissos
Agenda agenda:write marcar e cancelar compromisso
Webhooks webhooks:read ver destinos e histórico de entrega
Webhooks webhooks:write cadastrar e editar destinos
Relatórios reports:read ler os números de vendas
Comissões commissions:read ler as regras e usar a calculadora
Produtos products:read ler o catálogo de produtos (variações, estoque, categorias)
Produtos products:write criar, editar e excluir produtos, e criar categorias

Produtos dentro de um negócio pedem dois escopos. Ler as linhas de produto de um negócio exige products:read e deals:read; adicionar, editar, remover ou substituir linhas exige products:write e deals:write. O consumo por produto (GET/api/reports/products) exige reports:read, products:read e deals:read. Custo e margem só aparecem quando o responsável pela chave é administrador da conta.

Campos personalizados usam o escopo da entidade. Não existe escopo próprio: ler as definições de campos de produto pede products:read, criar ou editar pede products:write — e o mesmo vale para contatos, empresas e negócios.

funnels:read não é necessário para mover negócio de etapa — PATCH/api/deals/{id} exige apenas deals:write. O que este escopo dá é listar funis e etapas, que é como você descobre o column_id para onde mover.

⚠️ import:write sozinho não libera nenhuma escrita. Ele é um qualificador do que a chave já pode fazer — soma-se ao escopo do recurso, nunca o substitui. Uma chave só com import:write toma 403 forbidden_scope em POST/api/contacts do mesmo jeito que uma chave sem escopo nenhum. Para criar um contato com a data original, a chave precisa dos dois: contacts:write e import:write.