Acessos de API

Para quem quer ligar outro sistema ao CleanFin (um site, um aplicativo, o sistema de um parceiro). Aqui você cria o token: a senha que esse sistema usa para ler e gravar dados no CleanFin pela API.

Onde ficaIntegraçõesAcessos de API

Quem acessaSomente o administrador

Precisa deMódulo Integração via API e Webhook ligado em Configurações › Módulos, no plano 2 ou acima

Quem faz a integração é um programador

A API é usada por quem desenvolve o outro sistema. Esta página mostra a parte do CleanFin: criar o acesso e passar o token. Se quiser ajuda, a própria tela recomenda a integração assistida pela equipe do CleanFin.

O módulo Integração via API e Webhook vem desligado. Para ligar, veja Configurações.

Abrir a tela

No menu da esquerda, clique em Integrações e depois em Acessos de API.

1. Novo — cria um acesso.
2. Documentação da API — o manual técnico da API, para o programador.
3. Endpoint base — o endereço da API do CleanFin. Passe ao programador junto do token.

O quadro Instruções de integração também tem o link Abrir sandbox, o ambiente de homologação, para testar a integração sem mexer nos dados reais.

A lista mostra o Nome de cada acesso, o Cargo, o começo do Token, quem criou (Criador), a data de Expiração e se a IA pode usar o token (IA (MCP)).

Robôs e programas só entram com token

Robôs, agentes de inteligência artificial e outros programas acessam o sistema somente pela API, com um token desta tela. O login de usuário vale só pelo navegador ou pelo aplicativo.

Criar um acesso

1. Clique em Novo

   No alto da tela. O formulário abre numa janela.

2. Dê um nome

   Algo que diga qual sistema vai usar o acesso, como "Site da loja" ou "App de entregas".

3. Escolha o cargo e a expiração

   O Cargo de acesso define o que o outro sistema pode fazer, como se fosse uma pessoa com aquele cargo. A Data de expiração diz até quando o token vale.

4. Salve no ✓ verde

   A janela continua aberta e mostra o token.

5. Copie o token e guarde

   Clique no botão de copiar ao lado do código e guarde num lugar seguro. O código é exibido somente desta vez.

O que preencher

Nomeobrigatório

De 3 a 30 letras. Serve para você reconhecer o acesso na lista.

Cargo de acessoobrigatório

O que o sistema pode fazer pela API: as mesmas permissões de uma pessoa com esse cargo. Vem como Administrador; prefira o cargo mais baixo que dê conta do que o sistema precisa. Não muda depois de salvo.

Data de expiraçãoobrigatório

Até quando o token vale. Não muda depois de salvo: para estender, crie outro acesso.

Permitir acesso por IA (MCP)

Libera o token para a IA da sua empresa (Claude, ChatGPT, Cursor, n8n ou um agente próprio) ler os dados e os relatórios, com o mesmo cargo do token. Vem desligado. Desligue para cortar o acesso da IA sem derrubar as integrações que usam o token.

Permitir que a IA altere dados

Aparece com o acesso por IA ligado. Além de ler, a IA passa a cadastrar, alterar e excluir pelas mesmas telas e regras do sistema, sempre mostrando uma prévia antes de gravar. Vale só com o cargo Administrador ou Gerente.

Usar o token com uma IA

Com Permitir acesso por IA (MCP) ligado, a janela mostra o Endereço do MCP e um exemplo de configuração. Na IA, configure esse endereço com o cabeçalho de autorização e o token. No Claude.ai e no ChatGPT basta adicionar o endereço como conector: eles abrem o login do sistema e criam um token próprio nesta tela.

Exclusões e ações sem volta pedem um código

Com a IA autorizada a alterar dados, excluir (um registro por vez) e ações sem volta, como emitir nota ou comprar etiqueta, pedem um código de segurança, enviado a quem criou o token.

O token é uma senha

Quem tiver o token entra no CleanFin com as permissões do cargo escolhido. Não mande por e-mail aberto nem cole em lugar público. Depois de salvo, o sistema só mostra o começo dele: não é mais possível copiar o token completo. Perdeu? Crie um acesso novo.

Excluir um acesso

Clique em Ações em grupo, marque o acesso e clique em Excluir.

Clicando na linha, o acesso abre para trocar o nome. O cargo e a expiração ficam como foram criados.

Dúvidas comuns

Não acho Acessos de API no menu

A tela é só do administrador e aparece com o módulo Integração via API e Webhook ligado, nos planos 2 ou acima.

O outro sistema precisa saber quando uma fatura foi paga

Para isso existe o webhook: o CleanFin avisa o outro sistema sozinho, sem que ele precise ficar perguntando.

Apareceu "não é permitida a criação de tokens de acesso"

Você está na empresa de demonstração, onde não dá para criar tokens. Volte para a sua empresa e crie lá.