A chave de API é o que o sistema da sua empresa, ou de um parceiro, usa para ler e lançar dados na Kamino. Você cria a chave em Configurações › Integrações › Chaves de API, entrega o segredo a quem vai integrar e acompanha o uso pela mesma tela.
Antes de começar a criar uma chave de API
Quem pode criar e revogar: quem tem a funcionalidade Chaves de API — Escrita, em Papéis e permissões. Entre os papéis padrão, ela vem com Administrador da Organização e Administrador. O Gestor vê a lista, mas não cria.
Ambiente: a chave de Teste só alcança dados de exemplo; a de Produção, os dados reais da conta. Para começar uma integração, crie primeiro uma chave de teste. Veja "Como testar a integração no ambiente de teste".
Onde: na plataforma web.
Passo a passo para criar uma chave de API
Abra Configurações › Integrações › Chaves de API e clique em Nova chave. Abre o painel Nova chave de API.
Em Nome, escreva um nome que identifique a integração (ex.: "ERP Omie — contas a pagar").
Em Ambiente, escolha Teste ou Produção.
Em Vence, escolha Em 90 dias, Em 180 dias ou Em 1 ano. Quem tem a funcionalidade Chaves de API — Sem vencimento vê também Sem vencimento: a chave vale até alguém revogá-la.
Em Quem recebe o aviso de vencimento, deixe os administradores da conta ou escolha até 10 pessoas. A chave sem vencimento não tem esse campo.
Em Onde ela atua, escolha os grupos e as empresas que a chave alcança. Fora deles, ela não vê nem altera nada.
Em O que ela pode fazer, escolha Só ler, Ler, lançar e dar baixa ou Personalizar. Nenhuma permissão paga, aprova ou envia dinheiro ao banco.
Clique em Criar chave.
Guardar o segredo da chave de API
Logo depois de criar, o painel Guarde o segredo agora mostra o segredo. Ele aparece uma única vez: depois de fechar, ninguém consegue ver esse valor de novo, nem a Kamino.
Clique em Copiar segredo e guarde num cofre de senhas.
Entregue o segredo a quem vai integrar por um canal seguro. A Kamino não o envia por e-mail.
Marque Guardei o segredo em lugar seguro. e clique em Concluir.
O sistema usa o segredo no cabeçalho Authorization: Bearer <segredo>. O segredo de teste começa com pak_test_, e o de produção, com pak_live_. Se o segredo se perder, rotacione a chave.
Acompanhar as chaves de API
A lista mostra, para cada chave, o Ambiente, Onde atua, as Permissões, o Último uso e o Vencimento. A situação de cada uma:
Ativa — aceita nas chamadas das permissões concedidas.
A vencer — aceita normalmente e vence em até 30 dias. Rotacione antes de vencer.
Vencida — não é mais aceita. Use Emitir nova chave no menu da linha.
Revogada — não é mais aceita. O que ela fez continua na trilha de auditoria.
Clique na linha para ver o detalhe: quem criou, quem recebe o aviso de vencimento e as permissões.
Passo a passo para revogar uma chave de API
Na linha da chave, abra o menu ⋯ e clique em Revogar.
Escolha o Motivo: Parceiro encerrado, Segredo comprometido, Substituída por rotação ou Outro motivo.
Clique em Revogar chave.
A chave deixa de ser aceita em até 60 segundos. Não dá para desfazer. Se a chave ainda está em uso, a integração do parceiro para.
Regras e limites das chaves de API
Até 10 chaves ativas por conta. Um par em rotação conta como uma.
Vencimento de amanhã até 1 ano, ou sem vencimento. A chave sem vencimento só sai de circulação quando é revogada, e emiti-la pede a funcionalidade Chaves de API — Sem vencimento, que vem com os perfis de administrador. A chave com prazo vale até o fim do dia do vencimento, no horário de Brasília, e não se prorroga. A exceção é o prazo máximo: a chave que vence em 1 ano expira no mesmo horário em que foi criada, 365 dias depois, e não no fim daquele dia.
Aviso de vencimento: a Kamino avisa duas vezes, 30 dias e 7 dias antes do vencimento, na plataforma e por e-mail, a quem foi escolhido em Quem recebe o aviso de vencimento. Sem ninguém escolhido, o aviso vai para os administradores da conta, na plataforma. A chave emitida com prazo de até 30 dias recebe só o aviso de 7 dias.
Limite de chamadas: 600 por minuto por integração e ambiente, das quais até 120 escritas.
Nome único entre as integrações da conta, incluindo as revogadas.
Mensagens ao criar ou revogar uma chave de API
Já existe uma integração com este nome. Para dar outra chave a ela, use Emitir nova chave na lista. — escolha outro nome, ou emita uma chave nova para a integração existente.
A conta já atingiu o limite de chaves ativas. Revogue uma para emitir outra. — revogue uma chave que não está mais em uso.
Esta chave precisa de uma data de vencimento, de amanhã até 365 dias a partir de hoje. — escolha um vencimento dentro do prazo.
Você não pode liberar grupos ou empresas a que você mesmo não tem acesso. — escolha só grupos e empresas que você administra.
Perguntas frequentes sobre chaves de API
Perdi o segredo da chave. Como recupero?
Não dá para ver o segredo de novo. Rotacione a chave para gerar um segredo novo. Veja "Como trocar a chave de API sem parar a integração".
A chave pode pagar contas ou enviar dinheiro ao banco?
Não. Nenhuma permissão de chave paga, aprova ou envia dinheiro ao banco.
Como vejo o que a chave fez?
Pela trilha de auditoria. Veja "Como ver o que a integração do parceiro fez".