Autenticação
Toda chamada leva uma chave de API no cabeçalho Authorization. A chave identifica a organização e define quais empresas e recursos ela alcança.
Enviando a chave
Use o esquema Bearer. Chamadas sem HTTPS são recusadas, e a chave nunca vai na URL.
curl https://api.emissordenota.com/v1/nfse \ -H "Authorization: Bearer edn_live_SUA_CHAVE"Tipos de chave
O prefixo diz em qual ambiente a chave funciona. Uma chave de sandbox enviada para produção devolve 401, e vice-versa.
- edn_live_
- Ambiente
- Produção
- Comportamento
- Emite notas com valor fiscal e consulta dados reais da carteira
- edn_test_
- Ambiente
- Sandbox
- Comportamento
- Simula emissão e guias. Nada é transmitido
Permissões
Cada chave recebe permissões por recurso, escolhidas na hora de gerar. Dê só o que a integração usa.
EscopoPermite
- nfse:lerConsultar notas e baixar XML e PDF
- nfse:escreverEmitir, cancelar e substituir notas
- empresas:lerListar as empresas da carteira e seus certificados
- empresas:escreverCadastrar e editar empresas
- cadastros:lerConsultar clientes e serviços
- cadastros:escreverCriar e editar clientes e serviços
- guias:lerConsultar guias e baixar o PDF
- ecac:avisosReceber avisos de novas mensagens no e-CAC
- webhooks:escreverCadastrar e remover endpoints de webhook
Restrições opcionais
- Empresas: limite a chave a algumas empresas da carteira em vez de todas.
- Endereços IP: aceite chamadas apenas dos IPs fixos do seu servidor.
- Validade: defina expiração em 30, 90 ou 365 dias. Chaves sem validade continuam ativas até serem revogadas.
Quando a chave é recusada
StatusCódigoMotivo
- 401chave_invalidaChave ausente, mal formatada, revogada ou do ambiente errado
- 401chave_expiradaA validade definida na criação terminou
- 403permissao_insuficienteA chave não tem o escopo que o endpoint exige
- 403empresa_nao_autorizadaA empresa não está entre as liberadas para a chave
- 403ip_nao_autorizadoA chamada veio de um IP fora da lista
{ "erro": { "codigo": "permissao_insuficiente", "mensagem": "Esta chave não tem o escopo nfse:escrever.", "requisicao_id": "req_7Hc2Lq9Vx1" }}Rotação e revogação
Para trocar uma chave sem parar a integração, gere a nova, publique no seu sistema e só então revogue a antiga em Configurações › API e integrações. A revogação vale na hora e não pode ser desfeita.
Guarde a chave no servidor
Não coloque a chave em aplicativos, páginas web ou repositórios de código. Se ela vazar, revogue no painel e gere outra.