Cadastro de Chaves de API
Este artigo é para a equipe de TI que sustenta o KFlow. A tela Chaves de API é onde você cria, edita e revoga as chaves usadas por sistemas externos (ERP, middleware) para autenticar na API do KFlow, no cabeçalho X-Api-Key.
Serve para controlar quem pode chamar a API, quais operações cada chave executa e até quando ela vale — sem compartilhar usuário e senha de operador. Se a chave vazar ou o integrador deixar de usar, você revoga na tela e gera outra, sem mudar o código da integração.
1. Pré-requisitos
- Licença do KFlow válida.
- Perfil com acesso a Configurações e à ação de Chaves de API.
- Estar logado na empresa do integrador: a chave só autentica workflows dessa empresa.
2. Onde fica e o que dá para fazer
Caminho: Configurações → Sistema → Chaves de API.
| Ação | Efeito |
| Nova chave | Abre o cadastro. Depois de salvar, o token secreto aparece uma única vez. |
| Editar (lápis) | Altera Nome e Permissões de uma chave Ativa. Não muda o token nem a data de expiração. |
| Excluir (lixeira) | Revoga a chave (exclusão lógica). A confirmação pergunta: Deseja realmente excluir a chave "{nome}"? |
| Pesquisar… | Filtra a grade por nome, texto das permissões ou situação (Ativa, expirada, excluída). |
| Voltar | Retorna a Configurações. |
3. Lista de chaves
| Coluna | O que exibe |
| Nome | Identificação da chave na grade. Não autentica. |
| Secret Key | Token mascarado. O valor completo só aparece no momento da criação. |
| Status | Ativa (verde), Chave expirada (laranja, desativada automaticamente) ou Excluída (vermelho). |
| Permissões | Rótulos dos métodos liberados. |
| Criada em / Criada por | Quando e quem cadastrou. |
| Último uso | Última vez em que a API aceitou a chave (vazio se nunca usada). |
| Ações | Editar só aparece quando o status é Ativa. |
A grade pagina 10 registros por padrão (opções 10, 20, 30, 40, 50 e 75). Sem registros: Não há registros a serem exibidos.
4. Nova chave
O diálogo Cadastro de chave de API pede:
| Campo | O que faz |
| Nome (para você identificar) | Nome interno (ex.: integração ERP). Obrigatório; a tela avisa O campo é obrigatório se ficar vazio. Não é o segredo do header. |
| Permissões | Multiseleção dos métodos que a chave poderá chamar. Sem seleção, a chave não autoriza nenhum método. |
| Prazo de expiração | Obrigatório. Padrão: 30 dias. A chave deixa de ser aceita após o fim do dia correspondente a hoje + o prazo (horário local). |
Prazos disponíveis: 30 dias, 60 dias, 90 dias, 120 dias, 180 dias, 1 ano e 2 anos.
Ajuda na tela: A chave deixa de ser aceita após o fim do dia correspondente ao prazo a partir de hoje (horário local).
5. Token secreto (única exibição)
Ao salvar, a mensagem é Chave criada com sucesso. O modal passa para Salve sua chave:
- O segredo não poderá ser visualizado de novo. Quem tiver o token pode chamar a API. Se perder, é preciso gerar uma chave nova.
- Campo somente leitura com o token e botão Copiar (
Copiado para a área de transferência.). - Concluído fecha o diálogo.
Guarde o token no cofre do integrador. Nunca em repositório, ticket ou documentação.
6. Permissões (rótulo na tela)
Marque só o que o integrador realmente usa.
Faturamento — consultas
| Rótulo | Valor |
| Faturamento – Consultar contas (lista, paginado) | Faturamento/GetContas |
| Faturamento – Movimentações (lista, paginado) | Faturamento/GetMovimentacoes |
| Faturamento – Histórico de follow-up (várias contas) | Faturamento/GetHistoricoFollowUpByCdContas |
| Faturamento – Histórico de follow-up (várias contas; etapa opcional) | Faturamento/GetHistoricoFollowUpByCdContasIdEtapa |
| Faturamento – Movimentações por período (etapa opcional) | Faturamento/GetMovimentacoesByDtMovimentacaoIdEtapa |
| Faturamento – Pendentes por período de movimentação | Faturamento/GetPendentesByDtMovimentacao |
Faturamento — escrita
| Rótulo | Valor |
| Faturamento – Exclusão lógica de contas (lote) | Faturamento/DeleteContas |
| Faturamento – Movimentar conta (setor/origem/unidade + etapa) | Faturamento/MovimentarConta |
Planejamento Cirúrgico
| Rótulo | Valor |
| Planejamento Cirúrgico – Consultar avisos (paginado) | PlanejamentoCirurgico/GetAvisos |
| Planejamento Cirúrgico – Movimentações de avisos (paginado) | PlanejamentoCirurgico/GetMovimentacoes |
| Planejamento Cirúrgico – Exclusão lógica de avisos (lote) | PlanejamentoCirurgico/DeleteAvisos |
| Planejamento Cirúrgico – Movimentar aviso (de-para + etapa) | PlanejamentoCirurgico/MovimentarAviso |
Recebimento
| Rótulo | Valor |
| Recebimento – Consultar contas a receber (paginado) | Recebimento/GetContas |
| Recebimento – Movimentações de recebimento (paginado) | Recebimento/GetMovimentacoes |
| Recebimento – Exclusão lógica de contas a receber (lote) | Recebimento/DeleteContas |
| Recebimento – Movimentar conta a receber (de-para + etapa) | Recebimento/MovimentarConta |
Tarefas
| Rótulo | Valor |
| Tarefas – Listar tarefas pendentes (paginado) | Tarefa/GetPendentes |
| Tarefas – Iniciar tarefa | Tarefa/IniciarTarefa |
| Tarefas – Finalizar tarefa | Tarefa/FinalizarTarefa |
| Tarefas – Exclusão lógica de tarefas (lote) | Tarefa/DeleteTarefas |
Indicadores
| Rótulo | Valor |
| Indicadores – Indicadores (meta/resultado) por período | Indicador/GetIndicadores |
| Indicadores – Conceito/formulação de indicadores | Indicador/GetConceitoFormulacao |
7. Editar chave
Só chaves Ativas têm lápis. Você altera o nome e as permissões. Cancelar fecha sem gravar. Salvar persiste as mudanças sem renovar o token nem a data de expiração. Mensagem: Chave editada com sucesso.
8. Como validar
- Depois de criar, a linha deve aparecer como Ativa.
- Copie o token e teste um método que você marcou (por exemplo consultar contas, se
Faturamento/GetContasestiver na chave). - Uma chamada a método não marcado na chave deve ser recusada.
- Após Excluir, o status fica Excluída e a API rejeita aquele token.
- Depois do prazo, a grade mostra Chave expirada e a API deixa de aceitar a chave.
9. Problemas comuns
| Sintoma | O que verificar |
| Menu Chaves de API não aparece | Perfil com Configurações / Chaves de API. |
| A chave autentica o cliente errado | Empresa da sessão no momento do cadastro. |
| API recusa a chamada (sem permissão) | O método está marcado nas permissões da chave? |
| Token perdido | Não há como reexibir. Gere uma chave nova e revogue a antiga. |
| Editei e o integrador continua com o mesmo prazo | Esperado: editar não altera expiração nem o token. |