Aqui você vai encontrar a documentação dos métodos relativos à empresas e notas fiscais eletrônicas, incluindo URL de acesso (definição), parâmetros esperados e retornados, além dos potenciais códigos HTTP adicionais aos já documentados na relação genérica.
Na nossa documentação interativa você pode ver os métodos em detalhes e também testá-los na prática (recomendamos muito).
Basicamente, o fluxo de forma geral é:
- Crie sua conta no eNotas Gateway
- Ative um webhook (opcional)
- Cadastre uma empresa emissora via API ou UI
- Solicite a emissão de uma nota fiscal eletrônica via API
- Aguarde um retorno no seu webhook ou consulte a nota fiscal (status/motivoStatus) pelo nfeId obtido no passo anterior
- Se a emissão ocorreu com sucesso você pode baixar seu PDF/XML ou até tentar cancelá-la
Empresa Emissora
Também chamada de CNPJ emissor, a empresa concentra os dados de identificação, localização e afins que não só identifiquem uma empresa como também, opcionalmente, o serviço prestado por padrão.
[POST] Cadastrar
O cadastro de uma empresa pode passar por um processo de homologação caso não tenhamos nenhum cliente ainda operando no município, você poderá avaliar o resultado do cadastro consultando seu status.
Definição
https://api.enotasgw.com.br/v1/empresas
Parâmetros
Parâmetro com comportamento ou preenchimento variável de acordo com a prefeitura, consulte o artigo sobre o município.
Parâmetro de preenchimento obrigatório.
id | string | ID externo do sistema de origem | |
cnpj | string | CNPJ emissor | |
inscricaoMunicipal | string | ||
inscricaoEstadual | string | Se isento não precisa informar | |
razaoSocial | string | ||
nomeFantasia | string | ||
optanteSimplesNacional | bool | ||
string | |||
telefoneComercial | string | Formatação será removida | |
endereco | [] | Consultar próxima tabela | |
incentivadorCultural | bool | ||
regimeEspecialTributacao | string | | |
aedf | string | | |
configuracoesNFSeProducao | [] | Consultar próxima tabela | |
configuracoesNFSeHomologacao | [] | Consultar próxima tabela | |
codigoServicoMunicipal | string | Código municipal que identifica o serviço prestado | |
descricaoServico | string | Descrição municipal do serviço prestado | |
itemListaServicoLC116 | string | | |
cnae | string | | |
aliquotaIss | number | Alíquota de ISS padrão que será utilizada caso não informada na própria nota fiscal | |
certificadoDigital | [] | Consultar próxima tabela |
endereco
uf | string | Estado com 2 caracteres | |
cidade | string | Nome da cidade ou seu código IBGE | |
logradouro | string | ||
numero | string | ||
complemento | string | ||
bairro | string | ||
cep | string |
configuracoesNFSeProducao
Essas informações serão utilizadas sempre que a requisição for direcionada ao ambiente de produção.
- | string | - | |
- | string | - |
configuracoesNFSeHomologacao
Essas informações serão utilizadas sempre que a requisição for direcionada ao ambiente de homologação.
- | string | - | |
- | string | - |
Resultado
empresaId | string | ID único gerado pelo eNotas Gateway para identificar uma empresa emissora |
[GET] Consultar empresas
Com este método você poderá navegar entre as empresas cadastradas e buscar todas as suas informações cadastradas.
Definição
https://api.enotasgw.com.br/v1/empresas
Parâmetros
Resultado
Nota Fiscal Eletrônica
Concentra todas as informações da nota fiscal, inclusive as informações extraídas da prefeitura após a emissão ou cancelamento.
[POST] Emitir
A emissão da nota fiscal pode ser realizada logo após a empresa emissora passar para o status de LIBERADA.
Definição
https://api.enotasgw.com.br/v1/empresas/{empresaId}/nfes
Parâmetros
Parâmetro com comportamento ou preenchimento variável de acordo com a prefeitura, consulte o artigo sobre o município.
Parâmetro de preenchimento obrigatório.
id | string | ID único da nota fiscal gerado pelo Gateway que servirá principalmente na consulta | |
idExterno | string | ID único de sua escolha. | |
cliente | [] | Tomador do serviço, consultar próxima tabela | |
tipo | string | Tipo da nota fiscal a emitir. "NFS-e" para NFe de Serviço e "NF-e" para NFe de Produto (inativo no momento) | |
servico | [] | Identificação do serviço prestado, consultar próxima tabela | |
valorTotal | number | Valor total da nota fiscal | |
enviarPorEmail | boolean | True: Envia a nota fiscal por email ao cliente, incluindo um link para o seu PDF e XML. | |
ambienteEmissao | string | "Homologacao" para emitir no ambiente de homologação da prefeitura (caso ela possua) ou "Producao" para emitir oficialmente a nota fiscal em produção. |
cliente
O cliente pode ser opcional em determinados municípios, na dúvida consulte o artigo sobre a prefeitura desejada.
endereco | [] | Consultar próxima tabela | |
tipoPessoa | string | "F" para pessoa física e "J" para pessoa jurídica | |
nome | string | Nome ou razão social do tomador do serviço | |
string | Tipo da nota fiscal a emitir. "NFS-e" para NFe de Serviço e "NF-e" para NFe de Produto (inativo no momento) | ||
cpfCnpj | string | CPF para pessoa física e CNPJ para jurídica | |
telefone | string |
endereco
Caso opte por informar o endereço do cliente a maioria dos campos é obrigatória.
uf | string | Sigla do estado | |
cidade | string | Nome da cidade ou seu código IBGE | |
logradouro | string | ||
numero | string | ||
complemento | string | ||
bairro | string | ||
cep | string |
servico
Identifica o serviço prestado na nota fiscal, inclusive valores de impostos.
descricao | string | Descrição do serviço prestado | |
aliquotaIss | number | Valor da aliquota de ISS. Caso não seja preenchido será considerado o valor padrão configurado no cadastro da empresa emissora | |
issRetidoFonte | number | Indica se o ISS é retido na fonte | |
cnae | string | Código CNAE que identifica o serviço prestado. Caso não seja informado será considerado o valor padrão configurado no cadastro da empresa emissora | |
codigoServicoMunicipio | string | Código do serviço municipal conforme cadastro na prefeitura. Caso não seja informado será considerado o valor padrão configurado no cadastro da empresa emissora. | |
descricaoServicoMunicipio | string | Descrição do serviço municipal conforme cadastro na prefeitura. Caso não seja informado será considerado o valor padrão configurado no cadastro da empresa emissora.
| |
itemListaServicoLC116 | string | Item da lista de serviço conforme a Lei Complementar 116 (LC116). Caso não seja informado será considerado o valor padrão configurado no cadastro da empresa emissora. | |
ufPrestacaoServico | string | Sigla do Estado onde o serviço foi prestado. Opcional caso o serviço tenha sido prestado no mesmo munícipio da empresa emissora. | |
municipioPrestacaoServico | string | Nome ou código IBGE do município onde o serviço foi prestado. Opcional caso o serviço tenha sido prestado no mesmo munícipio da empresa emissora. | |
valorCofins | number | | |
valorCsll | number | ||
valorInss | number | | |
valorIr | number | ||
valorPis | number |
Resultado
Sucesso (200)
nfeId | string | ID único gerado pelo eNotas Gateway para identificar a nota fiscal |
[GET] Consultar pelo nfeId ou idExterno
Com este método você poderá obter todas as informações relativas a uma determinada nota fiscal, inclusive sua situação (status) e o motivo dela estar naquela situação. Você pode consultar usando o nfeId gerado pelo Gateway ou o seu idExterno caso tenha o informado na emissão.
Definição
nfeId - https://api.enotasgw.com.br/v1/empresas/{empresaId}/nfes/{nfeId}
idExterno - https://api.enotasgw.com.br/v1/empresas/{empresaId}/nfes/porIdExterno/{idExterno}
Parâmetros
empresaId | string | ID único da empresa emissora que emitiu a nota fiscal | |
nfeId ou idExterno | string | Identificador único da nota fiscal ou id externo |
Resultado
Sucesso (200)
numero | string | ID único da empresa emissora que emitiu a nota fiscal | |
codigoVerificacao | string | Utilizado em certas prefeituras para identificar uma nota no site do município | |
chaveAcesso | string | Utilizado em certas prefeituras para identificar uma nota no site do município | |
linkDownloadPDF | string | Link público para download do PDF da nota | |
linkDownloadXML | string | Link público para download do XML da nota | |
status | string | Status (situação) atual da nota fiscal: AguardandoAutorizacao: Status inicial EmProcessoDeAutorizacao: Nota fiscal está em processo de autorização junto à prefeitura Autorizada: Nota fiscal foi autorizada pela prefeitura Negada: Nota fiscal foi rejeitada pela prefeitura, nesse caso o parâmetro motivoStatus contém a mensagem de erro retornada pela prefeitura EmProcessoDeCancelamento: Nota fiscal está em processo de cancelamento junto à prefeitura Cancelada: Nota fiscal cancelada com sucesso na prefeitura CancelamentoNegado: Cancelamento da nota fiscal foi negado pela prefeitura e o parâmetro motivoStatus contém a mensagem de erro retornada pela prefeitura | |
motivoStatus | string | Razão pela qual a nota fiscal encontra-se no status (situação) atual | |
cliente | [] | Cliente (tomador do serviço) da nota fiscal, consulte próxima tabela | |
id | string | ||
tipo | string | Tipo da nota fiscal: NFS-e: Nota fiscal de serviço NF-e: Nota fiscal de produto | |
idExterno | string | Caso tenha informado um ID próprio na emissão da nota fiscal ele será retornado aqui | |
servico | [] | Detalhamanento do serviço prestado na nota fiscal, consulte próxima tabela | |
valorTotal | number | ||
enviadaPorEmail | boolean | Indica se a nota fiscal foi enviada com sucesso por email ao cliente pelo Gateway |
Códigos HTTP
404 | Nota fiscal não encontrada |
[DELETE] Cancelar pelo nfeId
Com esse método você poderá tentar cancelar uma nota fiscal a partir de seu ID único gerado pelo Gateway.
Definição
https://api.enotasgw.com.br/v1/empresas/{empresaId}/nfes/{nfeId}
Parâmetros
empresaId | string | ID único da empresa emissora que emitiu a nota fiscal | |
nfeId | string | Identificador único da nota fiscal |
Resultado
Como a execução desse método é assínncrona o resultado do cancelamento será enviado ao web hook ou pode ser obtido mediante consulta à nota fiscal
Caso o cancelamento ocorra com sucesso o status da nota fiscal mudará para cancelada, em caso contrário mudará para cancelamentoNegado e o parâmetro motivoStatus indicará o motivo.
Sucesso (200)
nfeId | string | ID único gerado pelo eNotas Gateway para identificar a nota fiscal |
Códigos HTTP
400 | Nota fiscal não encontrada |
[DELETE] Cancelar pelo idExterno
Com esse método você poderá tentar cancelar uma nota fiscal a partir de seu ID externo.
Definição
https://api.enotasgw.com.br/v1/empresas/{empresaId}/nfes/porIdExterno/{nfeId}
Parâmetros
empresaId | string | ID único da empresa emissora que emitiu a nota fiscal | |
nfeId | string | Identificador único da nota fiscal |
Resultado
Como a execução desse método é assíncrona o resultado do cancelamento será enviado ao web hook ou pode ser obtido mediante consulta à nota fiscal.
Caso o cancelamento ocorra com sucesso o status da nota fiscal mudará para cancelada, em caso contrário mudará para cancelamentoNegado e o parâmetro motivoStatus indicará o motivo.
Sucesso (200)
nfeId | string | ID único gerado pelo eNotas Gateway para identificar a nota fiscal |
Códigos HTTP
400 | Nota fiscal não encontrada |
[GET] Baixar PDF pelo nfeId
Com esse método você poderá baixar o PDF de qualquer nota fiscal já autorizada (emitida).
Definição
https://api.enotasgw.com.br/v1/empresas/{empresaId}/nfes/{nfeId}/pdf
Parâmetros
empresaId | string | ID único da empresa emissora que emitiu a nota fiscal | |
nfeId | string | Identificador único da nota fiscal |
Resultado
Sucesso (200)
bytes | Bytes do PDF da nota fiscal |
Códigos HTTP
400 | Nota fiscal não encontrada |
[GET] Baixar PDF pelo idExterno
[GET] Baixar XML pelo nfeId
Com esse método você poderá baixar o XML de qualquer nota fiscal já autorizada (emitida) caso a prefeitura trabalhe com XML.
Definição
https://api.enotasgw.com.br/v1/empresas/{empresaId}/nfes/{nfeId}/xml
Parâmetros
empresaId | string | ID único da empresa emissora que emitiu a nota fiscal | |
nfeId | string | Identificador único da nota fiscal |
Resultado
Sucesso (200)
bytes | Bytes do PDF da nota fiscal |
Códigos HTTP
400 | Nota fiscal não encontrada |
Leave A Comment?