Key de API

O que é uma Key de API, em palavras simples?

Uma Key de API funciona como o crachá de um sistema. Quando um ERP, uma loja virtual ou um software de gestão conversa com uma API, ele precisa se identificar. Em vez de digitar usuário e senha, o sistema envia essa chave junto com cada pedido.

A expressão mistura português e inglês e é a mesma coisa que API Key ou chave de API. Normalmente a chave é um texto longo e aparentemente aleatório, gerado pelo próprio provedor da API, difícil de adivinhar.

Para que serve uma Key de API na emissão fiscal?

Em uma API fiscal, a chave diz ao serviço qual conta está pedindo a emissão de uma NF-e, NFS-e, NFC-e, CT-e ou MDF-e. Com isso, a plataforma sabe quais empresas emissoras, certificados e franquias pertencem àquele cliente e impede que outra pessoa acesse esses dados.

Ela também permite controlar o que cada integração pode fazer. Dependendo do provedor, uma chave pode ter permissão apenas para consultar documentos, enquanto outra pode emitir e cancelar. Esse mesmo controle vale quando agentes de inteligência artificial acessam o serviço via MCP, com ações limitadas e registradas para auditoria.

Como funciona uma Key de API na prática?

O cliente gera a chave em um painel ou console do provedor e a configura no seu sistema. A cada requisição, o sistema envia a chave, geralmente em um cabeçalho HTTP (header de autenticação), por uma conexão segura HTTPS.

A API recebe o pedido, confere se a chave existe, se está ativa e se tem permissão para aquela ação. Se estiver tudo certo, a operação é executada; caso contrário, a resposta é um erro de autenticação ou de permissão, e nada é processado.

Qual a diferença entre Key de API e certificado digital?

São coisas diferentes que costumam aparecer juntas. A Key de API autentica o seu sistema perante o provedor da API, como o Conota. Já o certificado digital A1 identifica a empresa emitente perante a SEFAZ ou a prefeitura e é usado para assinar o XML do documento fiscal.

Em resumo: a chave abre a porta da plataforma de emissão; o certificado dá validade jurídica à nota. Perder uma não substitui a outra, e as duas precisam ser protegidas.

Como guardar uma Key de API com segurança?

A chave dá acesso real a operações fiscais, então deve ser tratada como senha. Ela não deve ficar escrita no código-fonte, em repositórios, em planilhas ou em mensagens. O ideal é armazená-la em variáveis de ambiente ou em ferramentas de gerenciamento de segredos, como um key vault.

Também é boa prática usar chaves separadas para homologação e produção, dar a cada integração apenas as permissões necessárias e trocar a chave periodicamente (key rotation). Se houver suspeita de vazamento, a chave deve ser revogada e substituída imediatamente.

Exemplos de Key de API

• Uma software house que vende um ERP configura a Key de API no servidor do sistema; sempre que um cliente fatura um pedido, o ERP envia os dados da NF-e à API fiscal com essa chave no cabeçalho.
• Um marketplace cria uma chave para o ambiente de homologação, faz todos os testes de emissão de NFS-e e só depois gera uma chave de produção para emitir notas com validade fiscal.
• Após um desenvolvedor sair da equipe, a empresa revoga a Key de API que ele usava e gera uma nova, atualizando o segredo no servidor sem interromper as emissões.
• Uma empresa cria uma chave apenas de leitura para que um agente de inteligência artificial consulte o status de documentos via MCP, sem permissão para cancelar notas.