Autenticação

API Keys

Toda requisição à API do Vistum requer uma API Key no header Authorization:

Authorization: Bearer vg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Formato da chave

As chaves seguem o padrão vg_live_ seguido de 40 caracteres hexadecimais:

vg_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

A chave é exibida uma única vez no momento da criação. Se perdida, revogue e gere uma nova — não é possível recuperar a chave original.

Onde gerar e configurar sua API Key

Acesse Configurações → Desenvolvedor → API Keys no CRM
Clique em Nova API Key
Defina um nome descritivo, o limite de requisições por minuto e uma data de expiração (opcional)
Selecione os escopos que a chave poderá usar (veja a tabela abaixo)
Copie e guarde a chave gerada

O acesso à API está incluído em todos os planos comerciais, a partir do Essencial (1 API Key; 3 no Crescimento; ilimitadas no Sob consulta). O erro 402 API_ACCESS_REQUIRED ocorre apenas em workspaces sem plano comercial ativo — plano gratuito, trial expirado ou assinatura suspensa. Veja Planos e Limites.

Escopos

Cada API Key carrega um ou mais escopos que definem exatamente quais operações ela pode realizar. A checagem é estrita: um escopo de escrita não concede leitura, e vice-versa — cada verbo é um escopo independente.

Escopo	Permite
`leads:read`	Listar/buscar contatos, campos personalizados e canais
`leads:write`	Criar e atualizar contatos (inclui `POST /api/v1/leads`)
`leads:delete`	Excluir contatos (soft-delete)
`deals:read`	Listar/buscar negócios
`deals:write`	Criar, atualizar, mover, ganhar/perder e restaurar negócios
`deals:delete`	Excluir negócios (soft-delete)
`tags:read`	Listar/buscar tags
`tags:write`	Criar/editar/excluir tags e atribuir/remover em contatos
`lists:read`	Listar/buscar listas de contatos
`lists:write`	Criar/editar/excluir listas e gerenciar seus contatos
`notes:read`	Listar anotações de um contato
`notes:write`	Criar/editar/excluir anotações
`activities:read`	Ler atividades de um negócio
`history:read`	Ler histórico de etapas de um negócio
`attachments:read`	Ler anexos de mídia de um contato
`pipelines:read`	Ler pipelines, etapas e campos personalizados
`members:read`	Ler membros do workspace
`products:read`	Listar/buscar produtos
`products:write`	Criar/editar/excluir produtos
`tasks:read`	Listar/buscar tarefas
`tasks:write`	Criar/editar/concluir/excluir tarefas
`insights:read`	Ler o insight de IA de um contato
`conversations:read`	Listar conversas e ler mensagens
`conversations:send`	Enviar mensagem de texto e finalizar atendimento
`instances:read`	Listar instâncias (conexões)

Editar os escopos de uma chave

Você pode ajustar nome, limite por minuto e escopos de uma chave ativa em Configurações → Desenvolvedor → API Keys → (editar). Ampliar escopos é tratado como escalonamento de poder: a mudança é validada contra a lista canônica e auditada. Uma chave precisa de ao menos um escopo válido.

Compatibilidade Vistum Forms: chaves antigas emitidas apenas com leads:write continuam autorizadas a ler pipelines e membros (pipelines:read, members:read) — e somente esses dois. Nenhum outro escopo é herdado. Chaves novas devem selecionar explicitamente os escopos desejados.

Segurança

Não exponha sua chave em código frontend, repositórios públicos ou logs
Use variáveis de ambiente para armazenar a chave na sua aplicação
Conceda o mínimo de escopos necessários a cada integração
Configure uma data de expiração para chaves de uso temporário
Revogue imediatamente se suspeitar de comprometimento

Erros de autenticação e autorização

Código	`code`	Causa
`401`	`UNAUTHORIZED`	Chave inválida ou ausente
`401`	`KEY_EXPIRED`	Chave expirada
`403`	`FORBIDDEN_SCOPE`	Chave válida, mas sem o escopo exigido pelo endpoint
`402`	`API_ACCESS_REQUIRED`	Plano atual não inclui acesso à API
`402`	`SUBSCRIPTION_INACTIVE`	Assinatura cancelada, suspensa, vencida ou em atraso

Exemplo de resposta 401

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "hint": "Pass a valid API key: Authorization: Bearer <key>"
}

Exemplo de resposta 403

{
  "error": "Forbidden",
  "code": "FORBIDDEN_SCOPE",
  "hint": "This API key does not have the 'deals:write' scope"
}

Introdução

Fundamentos da API

API Keys

Formato da chave

Onde gerar e configurar sua API Key

Escopos

Editar os escopos de uma chave

Segurança

Erros de autenticação e autorização

​API Keys

​Formato da chave

​Onde gerar e configurar sua API Key

​Escopos

​Editar os escopos de uma chave

​Segurança

​Erros de autenticação e autorização

API Keys

Formato da chave

Onde gerar e configurar sua API Key

Escopos

Editar os escopos de uma chave

Segurança

Erros de autenticação e autorização