Comece aquiAutenticação

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
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:ler
    Consultar notas e baixar XML e PDF
  • nfse:escrever
    Emitir, cancelar e substituir notas
  • empresas:ler
    Listar as empresas da carteira e seus certificados
  • empresas:escrever
    Cadastrar e editar empresas
  • cadastros:ler
    Consultar clientes e serviços
  • cadastros:escrever
    Criar e editar clientes e serviços
  • guias:ler
    Consultar guias e baixar o PDF
  • ecac:avisos
    Receber avisos de novas mensagens no e-CAC
  • webhooks:escrever
    Cadastrar 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_invalida
    Chave ausente, mal formatada, revogada ou do ambiente errado
  • 401chave_expirada
    A validade definida na criação terminou
  • 403permissao_insuficiente
    A chave não tem o escopo que o endpoint exige
  • 403empresa_nao_autorizada
    A empresa não está entre as liberadas para a chave
  • 403ip_nao_autorizado
    A chamada veio de um IP fora da lista
403 Forbidden
{  "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.