Introdução

Esta seção contém informações essenciais para o aproveitamento integral da API de gerenciamento de documentos fiscais no Brasil. Abrange os principais protocolos, métodos de autenticação, padrões de requisição e respostas, além de diretrizes de uso que são fundamentais para desenvolvedores e integradores que desejam trabalhar eficientemente com a API. Consulte os documentos relacionados e os exemplos de código para uma compreensão completa das funcionalidades disponíveis.

Esta é a nossa API, é um passo importante para o lançamento do produto que criamos para você, temos orgulho em dizer que estamos realizando um salto gigantesco para o mercado de emissão de documentos fiscais brasileiro.

A API é Restful, isso significa que usamos URLs previsíveis e orientados a recursos para operar em larga escala. A própria API fala exclusivamente em JSON, incluindo erros, mas nossas bibliotecas SDK convertem respostas em objetos específicos de linguagem apropriados.

Suporte Técnico

Se você tiver alguma dúvida sobre nossa API ou SDKs, entre em contato conosco pelo chat (horário comercial) ou envie-nos um e-mail. Nós responderemos você rapidamente, prometo S2. Estamos aqui para ajudá-lo a se integrar conosco o mais rápido possível. Também adoramos feedback, então não tenha vergonha de compartilhar suas ideias conosco.

Autenticação

Para as solicitações o corpo da requisição [body] deve ser enviado no formato JSON com o header Content-Type definido para application/json.

A autenticação é realizada através do cabeçalho HTTP (HTTP headers). É necessário o envio do TOKEN da sua empresa, que pode ser obtido pelo painel ou via API.

-H "Token: seu_token"
-H "Content-Type: application/json"

Mantenha as credenciais de acesso em segurança. Nunca publique as credenciais de acesso no código fonte do site, aplicativo ou software onde o usuário possa ter fácil acesso.

Para aplicações web e aplicativos mobile iOS/Android recomendamos que o processo de emissão seja realizado no servidor (back-end). No código fonte do aplicativo deve possuir somente as solicitações, enquanto o processo deve ser realizado em seu servidor.

Segurança

Sabemos da importância que é a segurança da informação por isso adotamos as melhores praticas do mercado.

É efetuado “backup” (copia de segurança) em tempo real, inclusive nos sábados, domingos e feriados nacionais dos arquivos que compõem as bases de dados existentes em nossos servidores.

Todos os dados sensíveis são armazenados criptografados.

Data e hora

Todas as datas retornadas/solicitações em nossa API estarão no formato UTC ISO no horário de Brasília -03:00. Isso significa que não importa onde você esteja, você sempre receberá os horários UTC e deverá lidar com as conversões para o horário local sempre que necessário.

Exemplo: 2021-01-01T23:59:00

Percentual

Tratando de porcentagem os retornos/solicitações em nossa API deve seguir de acordo com o seguinte exemplo:

18% –> 18.00;
7.60 –> 7.60.

De maneira alguma deve ser enviado

18% –> 0.18;
7.60 –> 0.0760.

Arquivos

Os retornos/solicitações que possuem arquivos (pdf, xml e excel) são bytes convertidos em BASE64, ou seja, nas solicitações que possui a necessidade de envio de arquivos deve-se converter os bytes do mesmo em BASE64 antes do envio, e para tratar os retornos deve fazer a conversão de BASE64 para bytes.

NF-e e NFC-e

Esta seção abrange os métodos específicos para a emissão de Nota Fiscal Eletrônica (NF-e) e Nota Fiscal do Consumidor Eletrônica (NFC-e). Aqui, você encontrará descrições detalhadas de como implementar e usar corretamente esses métodos em sua integração, garantindo a emissão correta de ambas as notas fiscais conforme os requisitos legais e técnicos.

Transmissão

Emite a NF-e/NFC-e para a SEFAZ e retorna o número do recibo e o número da nota fiscal.

POST: https://api.brasilnfe.com.br/services/fiscal/EnviarNotaFiscal

JSON Envio

Parâmetro Tipo Descrição
Serie numérico Série da nota Fiscal
Numero numérico Número da nota fiscal
Lote numérico Lote da Nota Fiscal
DataEntradaSaida data e hora
DataEmissao data e hora Data e Hora da saída ou de entrada da produto/serviço (Envia a data atual caso não informada)
Codigo texto B03 – Código numérico que compõe a Chave de Acesso. Número aleatório gerado pelo emitente para cada NF-e.
Modalidade numérico Tipo do documento fiscal (Padrão 1 – Saída)
0 - Entrada
1 - Saída
Justificativa texto Utilizar quando o tipo de emissão for diferente normal
NFReferencia Lista(texto) Notas fiscal de Referência
IndicadorPresenca numérico Indicador de presença do comprador no estabelecimento comercial no momento da operação
0 - Não se aplica;
1 - Operação presencial;
2 - Operação não presencial, pela Internet;
3 - Operação não presencial, Teleatendimento;
4 - NFC-e em operação com entrega a domicílio;
5 - Presencial fora do estabelecimento;
9 - Operação não presencial, outros.
IndicadorIntermediador true ou false Indicador de intermediador/marketplace
falso - Operação sem intermediador
verdadeiro - Operação em site ou plataforma de terceiros
ConsumidorFinal true ou false Indica operação com Consumidor final
Falso - Normal;
Verdadeiro - Consumidor final;
DestinoOperacao numérico Identificador de local de destino da operação
1 - Interna;
2 - Interestadual;
3 - Exterior.
CalcularIBPT true ou false Efetuar calculo do IBPT automáticamente
Falso - Não Calcular;
Verdadeiro - Calcular;
NaturezaOperacao texto Descrição da Natureza da Operação
ModeloDocumento numérico Código do modelo do Documento Fiscal.
55 = NF-e;
58 = MDFe;
65 = NFC-e.
Finalidade numérico Finalidade da emissão da NF-e
1 - NFe normal
3 - NFe de ajuste
4 - Devolução/Retorno
TipoAmbiente texto Identificação do Ambiente
1 - Produção
2 - Homologação
Observacao texto Observação da NF
ObservacaoFisco texto Observação Fisco da NF
IdentificadorInterno texto Identificador Interno
Cliente -> CPFCNPJ texto CPF/CNPJ do cliente
Cliente -> NmCliente texto Nome do cliente
Cliente -> CEP texto Número do CEP
Cliente -> Logradouro texto Logradouro do endereço do cliente
Cliente -> Complemento texto Complemento do endereço do cliente
Cliente -> Numero texto Número do endereço do cliente
Cliente -> Bairro texto Bairro do endereço do cliente
Cliente -> CodMunicipio texto Código do município
Cliente -> NmMunicipio texto Nome do município
Cliente -> UF texto Unidade Federativa
Cliente -> CodPais numérico 1058 – Código do Brasil (setado por padrão)
Cliente -> NmPais texto “BRASIL” (setado por padrão)
Cliente -> Telefone numérico Número de telefone do cliente
Cliente -> Email texto Email do cliente
Cliente -> IndicadoIE numérico
Cliente -> IE texto Inscrição Estadual
Produtos[] -> NmProduto texto Descrição do Produto
Produtos[] -> CodProdutoServico texto Código do produto ou serviço
Produtos[] -> EAN texto GTIN (Global Trade Item Number) do produto, antigo código EAN ou código de barras (Noramalmente sem GTIN)
Produtos[] -> NCM texto Código NCM (8 posições). Em caso de item de serviço ou item que não tenham produto (Ex. transferência de crédito, crédito do ativo imobilizado, etc.), informar o código 00 (zeros) (v2.0)
Produtos[] -> CEST texto Código CEST
Produtos[] -> Quantidade decimal Quantidade Comercial do produto, alterado para aceitar de 0 a 4 casas decimais e 11 numéricos.
Produtos[] -> UnidadeComercial texto Unidade comercial (Unidade de Medida)
Produtos[] -> ValorDesconto decimal Valor do Desconto
Produtos[] -> ValorUnitario decimal Valor Unitário
Produtos[] -> ValorTotal decimal Valor Total Bruto
Produtos[] -> ValorSeguro decimal Valor Seguro
Produtos[] -> ValorFrete decimal Valor Frete
Produtos[] -> ValorOutrasDespesas decimal Valor Outras Despesas
Produtos[] -> CFOP numérico Código Fiscal de Operações e Prestações
Produtos[] -> NItemPed numérico Número do item do Pedido de Compra
Produtos[] -> xPed texto Número do Pedido de Compra
Produtos[] -> InformacaoAdicional texto Informaçoes adicional
Produtos[] -> OrigemProduto numérico 0 - Nacional, exceto as indicadas nos códigos 3, 4, 5 e 8
1 - Estrangeira - Importação direta, exceto a indicada no código 6
2 - Estrangeira - Adquirida no mercado numéricoerno, exceto a indicada no código 7
3 - Nacional, mercadoria ou bem com Conteúdo de Importação superior a 40% e inferior ou igual a 70%
4 - Nacional, cuja produção tenha sido feita em conformidade com os processos produtivos básicos de que tratam as legislações citadas nos Ajustes
5 - Nacional, mercadoria ou bem com Conteúdo de Importação inferior ou igual a 40%
6 - Estrangeira - Importação direta, sem similar nacional, constante em lista da CAMEX e gás natural
7 - Estrangeira - Adquirida no mercado numéricoerno, sem similar nacional, constante lista CAMEX e gás natural
8 - Nacional, mercadoria ou bem com Conteúdo de Importação superior a 70%
Produtos[] -> CodTributação texto Código do grupo tributário cadastrado no Painel, para automação de impostos
Produtos[] -> Imposto -> ICMS -> CodSituacaoTributaria texto Código da Situação Tributária (CST ou CSOSN)
Produtos[] -> Imposto -> ICMS -> AliquotaICMS decimal Alíquota ICMS – Obrigatório para situação tributária nº 101 e 201
Produtos[] -> Imposto -> ICMS -> AliquotaICMSST decimal Alíquota ICMS ST – Obrigatório para situação tributária nº 101 e 201
Produtos[] -> Imposto -> ICMS -> AliquotaMVA decimal Alíquota – Obrigatório para situação tributária nº 201, 202 e 203
Produtos[] -> Imposto -> ICMS -> AliquotaCredito decimal Alíquota aplicável de cálculo de crédito – Obrigatório para situação tributária nº 101 e 201
Produtos[] -> Imposto -> ICMS -> RedICMS decimal Redução ICMS
Produtos[] -> Imposto -> ICMS -> RedICMSST texto Redução ICMS ST
Produtos[] -> Imposto -> IPI -> CodEnquadramento texto Código de Enquadramento Legal do IPI
Produtos[] -> Imposto -> IPI -> CodSituacaoTributaria texto Código da Situação Tributária do IPI
Produtos[] -> Imposto -> IPI -> Aliquota decimal Aliquota do IPI
Produtos[] -> Imposto -> IPI -> ValorIpiDevolvido decimal Valor do IPI devolvido
Produtos[] -> Imposto -> IPI -> PercentualMercadoriaDevolvida decimal Percentual da mercadoria devolvida
Produtos[] -> Imposto -> PIS -> CodSituacaoTributaria texto Código da Situação Tributária do PIS
Produtos[] -> Imposto -> PIS -> Aliquota decimal Alíquota do PIS
Produtos[] -> Imposto -> COFINS -> CodSituacaoTributaria texto Código da Situação Tributária do COFINS
Produtos[] -> Imposto -> COFINS ->Aliquota decimal Alíquota do COFINS
Produtos[] -> Combustivel -> CodProdutoANP texto Código do produto ANP
Produtos[] -> Combustivel -> DescricaoProdutoANP texto Descrição do produto ANP
Produtos[] -> Combustivel -> UFConsumo texto UF do consumo
Pagamentos[] -> IndicadorPagamento numérico 0 - A vista
1 - Prazo
Pagamentos[] -> Descricao texto Descrição do pagamento
Pagamentos[] -> FormaPagamento texto 01 - Dinheiro
02 - Cheque
03 - Cartão de Crédito
04 - Cartão de Débito
05 - Crédito Loja
10 - Vale Alimentação
11 - Vale Refeição
12 - Vale Presente
13 - Vale Combustível
14 - Duplicata Mercantil
16 - Depósito Bancário
17 - Pagamento Instantâneo (PIX)
18 - Transferencia Bancária, Carteira Digital
19 - Programa de fidelidade, cashback, crédito virtual
90 - Sem pagamento
99 - Outros
Pagamentos[] -> VlPago decimal Valor pago
Pagamentos[] -> VlTroco decimal Valor troco
Pagamentos[] -> TipoIntegracao true ou false Pagamento numéricoegrado com automação?
Pagamentos[] -> CNPJCredenciadora texto CNPJ da credenciadora
Pagamentos[] -> BandeiraOperadora texto 01 – Visa
02 – Mastercard
03 – American Express
04 – Sorocred
05 – Diners Club
06 – Elo
07 – Hipercard
08 – Aura
09 – Cabal
99 – Outros
Pagamentos[] -> BandeiraOperadora texto Bandeira da operadora
Pagamentos[] -> NumeroAutorizacao texto Numero da autorização
Cobranca -> Fatura -> Numero texto Número da fatura
Cobranca -> Fatura -> Valor decimal Valor da fatura
Cobranca -> Fatura -> Desconto decimal Desconto da fatura
Cobranca -> Fatura -> ValorLiquido decimal Valor liquido da fatura
Cobranca -> Parcelas[] -> Vencimento data e hora Vencimento da parcela
Cobranca -> Parcelas[] -> Valor decimal Valor da parcela
Transporte -> ModalidadeFrete numérico 0 - Contratação do Frete por conta do Remetente (CIF)
1 - Contratação do Frete por conta do Destinatário (FOB)
2 - Contratação do Frete por conta de Terceiros
3 - Transporte Próprio por conta do Remetente
4 - Transporte Próprio por conta do Destinatário
9 - Sem Ocorrência de Transporte
Transporte -> NmTransportador texto Nome do(a) transportador(a)
Transporte -> CNPJ texto CNPJ do(a) transportador(a)
Transporte -> NmMunicipio texto Nome do município
Transporte -> DsEndereco texto Descrição do endereço
Transporte -> IE texto Inscrição estadual
Transporte -> UF texto Unidade Federativa do transporte
Transporte -> Vagao texto Descrição do vagão
Transporte -> Balsa texto Descrição da balsa
Transporte -> Veiculo -> Placa texto Placa do veículo
Transporte -> Veiculo -> UF texto Unidade Federativa do veículo
Transporte -> Veiculo -> RNTC texto Registro Nacional de Transporte de Carga do veículo
Transporte -> Reboque[] -> Placa texto Placa do reboque
Transporte -> Reboque[] -> UF texto Unidade Federativa do reboque
Transporte -> Reboque[] -> RNTC texto Registro Nacional de Transporte de Carga do reboque
Transporte -> Volumes[] -> QuantidadeVolume numérico Quantidade e volume da carga
Transporte -> Volumes[] -> Especie texto Espécie da carga
Transporte -> Volumes[] -> Marca decimal Marca da carga
Transporte -> Volumes[] -> PesoBruto decimal Peso bruto da carga
Transporte -> Volumes[] -> PesoLiquido decimal Peso liquido da carga
Transporte -> Volumes[] -> Lacres List Lacres da carga
Entrega -> CpfCnpj texto CNPJ ou CPF
Entrega -> Nome texto Nome do Entregador
Entrega -> Ie texto Inscrição Municipal
Entrega -> Endereco -> Cep texto CEP do local
Entrega -> Endereco -> Logradouro texto Descrição do Logradouro
Entrega -> Endereco -> Complemento texto Complemento do endereço
Entrega -> Endereco -> Numero texto Número da residencia
Entrega -> Endereco -> Bairro texto Descrição do Bairro
Entrega -> Endereco -> CodMunicipio texto Código do município de acordo com a tabela IBGE
Entrega -> Endereco -> Municipio texto Descrição do município
Entrega -> Endereco -> Uf texto Unidade federativa, Exemplos: MG, SP, RJ
Entrega -> Endereco -> CodPais numérico Código do país. Padrão: 1058 (Brasil)
Entrega -> Endereco -> Pais texto Descrição do País. Padrão: Brasil
Entrega -> Contato -> Telefone texto Telefone da empresa
Entrega -> Contato -> Email texto Email da empresa

NF-e Complementar

A Nota Fiscal Complementar é destinada para acrescentar dados e valores não informados no documento fiscal original. Utilizado para acréscimo no preço e quantidade da mercadoria ou somar valores faltantes dos impostos ICMS, ICMS-ST, IPI e ISSQN.

POST: https://api.brasilnfe.com.br/services/fiscal/EnviarNotaFiscalComplementar

JSON Envio

Parâmetro Tipo Descrição
Serie numérico Série da nota Fiscal
Numero numérico Número da nota fiscal
Lote numérico Lote da Nota Fiscal
DataEntradaSaida data e hora
DataEmissao data e hora Data e Hora da saída ou de entrada da produto/serviço (Envia a data atual caso não informada)
Codigo texto B03 – Código numérico que compõe a Chave de Acesso. Número aleatório gerado pelo emitente para cada NF-e.
Modalidade numérico Tipo do documento fiscal (Padrão 1 – Saída)
0 - Entrada
1 - Saída
Justificativa texto Utilizar quando o tipo de emissão for diferente normal
NFReferencia Lista(texto) Notas fiscal de Referência
IndicadorPresenca numérico Indicador de presença do comprador no estabelecimento comercial no momento da operação
0 - Não se aplica;
1 - Operação presencial;
2 - Operação não presencial, pela Internet;
3 - Operação não presencial, Teleatendimento;
4 - NFC-e em operação com entrega a domicílio;
5 - Presencial fora do estabelecimento;
9 - Operação não presencial, outros.
IndicadorIntermediador true ou false Indicador de intermediador/marketplace
falso - Operação sem intermediador
verdadeiro - Operação em site ou plataforma de terceiros
ConsumidorFinal true ou false Indica operação com Consumidor final
Falso - Normal;
Verdadeiro - Consumidor final;
DestinoOperacao numérico Identificador de local de destino da operação
1 - Interna;
2 - Interestadual;
3 - Exterior.
CalcularIBPT true ou false Efetuar calculo do IBPT automáticamente
Falso - Não Calcular;
Verdadeiro - Calcular;
NaturezaOperacao texto Descrição da Natureza da Operação
ModeloDocumento numérico Código do modelo do Documento Fiscal.
55 = NF-e;
58 = MDFe;
65 = NFC-e.
Finalidade numérico Finalidade da emissão da NF-e
1 - NFe normal
3 - NFe de ajuste
4 - Devolução/Retorno
TipoAmbiente texto Identificação do Ambiente
1 - Produção
2 - Homologação
Observacao texto Observação da NF
ObservacaoFisco texto Observação Fisco da NF
IdentificadorInterno texto Identificador Interno

Carta de Correção

Esse artigo tem como objetivo apresentar a forma com que é enviada uma carta de correção. A Carta de Correção Eletrônica (CC-e) é um evento legal e tem por objetivo corrigir algumas informações da NF-e que já foi emitida.

O que NÃO é permitido corrigir com a carta de correção?
* Valores como base de cálculo, alíquota, diferença de preço e quantidade.
* Dados cadastrais que implique mudança do remetente ou do destinatário.
* A data de emissão ou de saída.
* Série e número da nota fiscal.

A sua alteração não se enquadra na carta de correção?
Emita uma nota fiscal de devolução para anular os efeitos fiscais da NF-e emitida anteriormente, logo após emita uma nova Nota Fiscal normalmente.

POST: https://api.brasilnfe.com.br/services/fiscal/EnviarNotaFiscalComplementar

JSON Envio

Parâmetro Tipo Tamanho Descrição
TipoAmbiente numérico 1* Ambiente de emissão do evento
1 - Produção;
2 - Homologação;
ChaveNF texto 44* Chave da NF-e
Correcao texto 15-1000 Descrição da correção da NF-e
NumeroSequencial numérico * Número sequencial do evento

JSON Retorno

Parâmetro Tipo Tamanho Descrição
DsMotivo texto * Descrição do status do evento emitido
DsEvento texto * Descrição do evento emitido
DsAmbiente texto * Descrição do ambiente em que foi emitido o evento
NuProtocolo texto * Número de protocolo do evento
CodStatusRespostaSefaz numérico * Código de status de resposta da SEFAZ
NumeroSequencial numérico * Número sequencial do evento
Status numérico 1 Status do evento
1 - Evento Processado;
2 - Aguardando Processamento do Evento;
3 - Ocorreu um erro ao processar o evento;

Validações

Código Descrição
1001 A descrição da correção deve conter no mínimo 15 caracteres!
1002 A descrição da correção deve conter no máximo 1000 caracteres!
1003 Chave da nota fiscal não informada!
1004 O Tipo do Ambiente informado é inválido.!
1005 O número do sequencial deve ser maior que zero!
* Só é atingido quando enviado o parâmetro “NumeroSequencial”, o mesmo não é obrigatório, e quando não enviado é controlado por algoritmo interno.

Cancelamento

Esse artigo tem como objetivo apresentar a forma com que é efetuado o cancelamento de uma nota fiscal NF-e ou NFC-e.

Atenção!
Somente poderá ser cancelada uma NF-e cujo uso tenha sido previamente autorizado pelo Fisco e desde que não tenha ainda ocorrido o fato gerador, ou seja, ainda não tenha ocorrido a saída da mercadoria do estabelecimento.

Atualmente o prazo máximo para cancelamento de uma NF-e é de 24 horas (1 dia), contado a partir da autorização de uso. Caso já tenha passado o prazo de 24 horas ou já tenha ocorrido a circulação da mercadoria, emita uma NF-e de devolução para anular a NF-e anterior.

Já o prazo de cancelamento da NFC-e é de no máximo 30 minutos, contado a partir da autorização de uso.

POST: https://api.brasilnfe.com.br/services/fiscal/CancelNF

JSON Envio

Parâmetro Tipo Tamanho Descrição
ChaveNF texto 44* Chave da NF-e
Justificativa texto 15-1000 Justificativa descrevendo o motivo do cancelemtento da NF-e/NFC-e
NumeroSequencial numérico * Número sequencial do evento

JSON Retorno

Parâmetro Tipo Tamanho Descrição
DsMotivo texto * Descrição do status do evento emitido
DsEvento texto * Descrição do evento emitido
DsAmbiente texto * Descrição do ambiente em que foi emitido o evento
NuProtocolo texto * Número de protocolo do evento
CodStatusRespostaSefaz numerico * Código de status de resposta da SEFAZ
NumeroSequencial numerico * Número sequencial do evento
Status numerico 1 Status do evento
1 - Evento Processado;
2 - Aguardando Processamento do Evento;
3 - Ocorreu um erro ao processar o evento;
Error texto * Descrição do erro, caso o status retornado for igual a 3

Validações

Código Descrição
2001 A justificativa do cancelamento deve conter no mínimo 15 caracteres!
2002 A justificativa do cancelamento deve conter no máximo 1000 caracteres!
2003 Chave da nota fiscal não informada!
2005 O número do sequencial deve ser maior que zero!

Manifestação do Destinatário

Esse artigo tem como objetivo apresentar a forma com que é enviada a manifestação do destinatário referente a uma NF-e.

A Manifestação do Destinatário é um conjunto de eventos que permitem que o destinatário da NFe possa apontar a sua participação comercial descrita no documento fiscal, confirmando e controlando as operações e informações prestadas pelo seu fornecedor, que é o emissor do documento.

POST:https://api.brasilnfe.com.br/services/fiscal/ManifestarNotaFiscal

JSON Envio

Parâmetro Tipo Tamanho Descrição
Chave texto 44* Chave da NF-e
TipoAmbiente numérico 1* Ambiente de emissão do evento
1 - Produção;
2 - Homologação;
TipoManifestacao numérico 1* Tipo da manifestação
1 - Confirmacao da Operacao;
2 - Ciência da Operacao;
3 - Desconhecimento da Operacao;
4 - Operacao não Realizada;
NumeroSequencial numérico * Número sequencial do evento

JSON Retorno

Parâmetro Tipo Tamanho Descrição
DsMotivo texto * Descrição do status do evento emitido
DsEvento texto * Descrição do evento emitido
DsAmbiente texto * Descrição do ambiente em que foi emitido o evento
NuProtocolo texto * Número de protocolo do evento
CodStatusRespostaSefaz numerico * Código de status de resposta da SEFAZ
NumeroSequencial numerico * Número sequencial do evento
Status numerico 1 Status do evento
1 - Evento Processado;
2 - Aguardando Processamento do Evento;
3 - Ocorreu um erro ao processar o evento;
Error texto * Descrição do erro, caso o status retornado for igual a 3

Validações

Código Descrição
3001 O Tipo de manifestação informado é inválido!
3002 O Tipo de ambiente informado é inválido!
3003 Chave da nota fiscal não informada!
3005 O número do sequencial deve ser maior que zero!
* Só é atingido quando enviado o parâmetro “NumeroSequencial”, o mesmo não é obrigatório, e quando não enviado é controlado por algoritmo interno.

Inutilizar Numeração

Esse artigo tem como objetivo apresentar a forma com que é efetuada a inutilização de numerações.

A inutilização de número de NF-e tem a finalidade de permitir que o emissor comunique à SEFAZ, até o décimo dia do mês subsequente, os números de NF-e que não serão utilizados em razão de ter ocorrido uma quebra de sequência da numeração da NF-e. A inutilização de número só é possível caso a numeração ainda não tenha sido utilizada em nenhuma NF-e (autorizada, cancelada ou denegada).

POST:https://api.brasilnfe.com.br/services/fiscal/InutilizarNumeracao

JSON Envio

Parâmetro Tipo Tamanho Descrição
TipoAmbiente numérico 1* Ambiente de emissão do evento
1 - Produção;
2 - Homologação;
ModeloDocumento numérico 1* Ambiente de emissão do evento
55 - NF-e;
65 - NFC-e;
Serie numérico * Série referente ao modelo do documento
Justificativa texto 15-255 Justificativa da inulização
NumeracaoInicial numérico * Inicio da range numérico de inutilização
NumeracaoFinal numérico * Final da range numérico de inutilização

JSON Retorno

Parâmetro Tipo Tamanho Descrição
DsMotivo texto * Descrição do status do evento emitido
DsEvento texto * Descrição do evento emitido
DsAmbiente texto * Descrição do ambiente em que foi emitido o evento
NuProtocolo texto * Número de protocolo do evento
CodStatusRespostaSefaz numerico * Código de status de resposta da SEFAZ
Status numerico 1 Status do evento
1 - Evento Processado;
2 - Aguardando Processamento do Evento;
3 - Ocorreu um erro ao processar o evento;
Error texto * Descrição do erro, caso o status retornado for igual a 3

Validações

Código Descrição
4001 O Tipo de ambiente informado é inválido!
4002 O modelo do documento informado é inválido!
4003 A série deve ser maior que zero!
3004 A justificativa da inutilização deve conter no mínimo 15 caracteres!
3005 A justificativa da inutilização deve conter no máximo 255 caracteres!
3006 A numeração inicial deve ser maior que zero!
3007 A numeração final deve ser maior que zero!
3008 A numeração inicial não pode pode ser maior a numeração final!

Pré-Visualizar Documento

Esse artigo tem como objetivo apresentar a forma com que se efetua a pré-visualização de uma NF-e.

A pré-visualização permite visualizar o PDF ou XML de uma NF-e/CT-e/MDF-e sem a necessidade de efetuar a transmissão da mesma.

É possível efetuar a pré-visualização a partir do envio de um arquivo XML (enviado em BASE64) ou por parâmetro (mesmo objeto de envio da NF-e) que contém as informações da NF-e.

POST:https://api.brasilnfe.com.br/services/fiscal/PreVisualizarNotaFiscal

JSON Envio

Parâmetro Tipo Tamanho Descrição
TipoArquivo numérico 1* Tipo do arquivo que deseja pré-visualizar
0 - XML;
1 - PDF;
TipoEnvio numérico 1* Tipo do envio no qual será convertido para o tipo do arquivo informado

0 - Base64 contendo as informações do XML;
1 - Objeto contendo as informações das notas fiscais;
Base64Xml BASE64 * Arquivo XML em Base64
notaFiscal Objeto Visualizar * Objeto contendo as informações da nota fiscal

JSON Retorno

Parâmetro Tipo Tamanho Descrição
Status true ou false * Verdadeiro caso o arquivo ser gerado com sucesso e Falso caso contrário
Base64File texto * Base64 contendo o arquivo PDF ou XML
Error texto * Descrição do erro, caso o status retornado for igual a false

Validações

Código Descrição
6001 O tipo do arquivo informado é inválido!
6002 O tipo do envio informado é inválido!
6003 O arquivo Base64 é obrigatório quando o tipo de envio for igual a 0 (Base64 contendo as informações do XML)!
6004 O objeto contendo as informações das notas fiscais é obrigatório quando o tipo de envio for igual a 1 (Objeto contendo as informações das notas fiscais)!

Nota Fiscal de Serviço (NFS-e)

Esta seção abrange os métodos específicos para a emissão de Nota Fiscal de Serviço (NFS-e). Aqui, você encontrará descrições detalhadas de como implementar e usar corretamente esses métodos em sua integração, garantindo a emissão correta conforme os requisitos legais e técnicos.

Transmissão

O método de transmissão de NFS-e cataloga as informações de acordo com o layout do provedor e efetua a transmissão para prefeitura e retorna o número do lote e o número da NFS-e.

Algumas prefeituras opera somente de forma assíncrona (retornando o Status 2 - Em processamento), com o número do lote é possível realizar consultas posteriores e verificar se a NFS-e já foi processada.

POST: https://api.brasilnfe.com.br/services/fiscal/EnviarNotaFiscalServico

JSON Envio

Parâmetro Tipo Tamanho Descrição
TipoAmbiente numérico 1 Tipo de Ambiente de Transmissão
1 - Produção;
2 - Homologação;
Lote numérico * Número do lote de envio
nFSInfo Lista(objeto) * Lista contendo as informações dos documentos fiscais
nFSInfo[] -> EnviarEmail true ou false *
nFSInfo[] -> SerieRps texto *
nFSInfo[] -> NumeroRps texto *
nFSInfo[] -> IdentificadorInterno texto * Identificador Interno
nFSInfo[] -> DataCompetencia texto * Data da competência
Caso não informado será considerada a data de emissão
nFSInfo[] -> DataEmissao texto * Data da emissão
nFSInfo[] -> Tomador -> CpfCnpj texto 14 ou 11 CNPJ ou CPF
nFSInfo[] -> Tomador -> NmTomador texto * Nome do Tomador
nFSInfo[] -> Tomador -> Im texto * Inscrição Municipal
nFSInfo[] -> Tomador -> Endereco -> Cep texto * CEP do local
nFSInfo[] -> Tomador -> Endereco -> Logradouro texto * Descrição do Logradouro
nFSInfo[] -> Tomador -> Endereco -> Complemento texto * Complemento do endereço
nFSInfo[] -> Tomador -> Endereco -> Numero texto * Número da residencia
nFSInfo[] -> Tomador -> Endereco -> Bairro texto * Descrição do Bairro
nFSInfo[] -> Tomador -> Endereco -> CodMunicipio texto * Código do município de acordo com a tabela IBGE
nFSInfo[] -> Tomador -> Endereco -> Municipio texto * Descrição do município
nFSInfo[] -> Tomador -> Endereco -> Uf texto * Unidade federativa, Exemplos: MG, SP, RJ
nFSInfo[] -> Tomador -> Endereco -> CodPais numérico * Código do país. Padrão: 1058 (Brasil)
nFSInfo[] -> Tomador -> Endereco -> Pais texto * Descrição do País. Padrão: Brasil
nFSInfo[] -> Tomador -> Contato -> Telefone texto * Telefone da empresa
nFSInfo[] -> Tomador -> Contato -> Email texto * Email da empresa
nFSInfo[] -> IntermediarioServico -> RzSocial texto * Razão social
nFSInfo[] -> IntermediarioServico -> CPFCNPJ texto 14 ou 11 CNPJ ou CPF
nFSInfo[] -> IntermediarioServico -> InscricaoMunicipal texto * Inscrição Municipal
nFSInfo[] -> ConstrucaoCivil -> CodObra texto *
nFSInfo[] -> ConstrucaoCivil -> Art texto *
nFSInfo[] -> Servico -> Descricao texto * Descrição do serviço
nFSInfo[] -> Servico -> ItemListaServico texto * Itens dos serviços
nFSInfo[] -> Servico -> RegimeEspecialTributacao numérico *
0 - Sem Regime Especial;
1 - Microempresa municipal;
2 - Estimativa;
3 - Sociedade de profissionais;
4 - Cooperativa;
5 - MEI - Simples Nacional;
6 - ME EPP - Simples Nacional;
nFSInfo[] -> Servico -> NaturezaOperacao numérico *
1 - Tributação no município;
2 - Tributação fora do município;
3 - Isenção;
4 - Imune;
5 - Exigibilidade suspensa por decisão judicial;
6 - Exigibilidade suspensa por procedimento administrativo;
7 - Não tributada (Governador Valadares);
nFSInfo[] -> Servico -> IncentivadorCultural true ou false * Incentivo Cultural?
falso - Não é incentivador cultiral
verdadeiro - É incentivador cultural
nFSInfo[] -> Servico -> IncentivoFiscal true ou false * Incentivo Fiscal?
falso - Não é incentivador fiscal
verdadeiro - É incentivador fiscal
nFSInfo[] -> Servico -> IssRetido true ou false * Iss Retido?
falso - Valor não será retido
verdadeiro - Valor retido
nFSInfo[] -> Servico -> CodTributacaoMunicipio texto * Código de tributação do município
nFSInfo[] -> Servico -> ExigibilidadeISS numérico * Exigibilidade ISS (Padrão 1)
1 - Exigível;
2 - Não incidência;
3 - Isenção;
4 - Exportação;
5 - Imunidade;
6 - Exigibilidade Suspensa por Decisão Judicia;
7 - Exigibilidade Suspensa por Processo Administrativo;
nFSInfo[] -> Servico -> CodMunicipioIncidencia texto * Código do municipio da incedência do serviço (Padrão - Município do Prestador)
nFSInfo[] -> Servico -> CodMunicipioPrestacao texto * Código do municipio da prestação do serviço (Padrão - Município do Prestador)
nFSInfo[] -> Servico -> Valores -> ValorServico decimal *
nFSInfo[] -> Servico -> Valores -> ValorInss decimal *
nFSInfo[] -> Servico -> Valores -> Aliquota decimal *
nFSInfo[] -> Servico -> Valores -> DescontoCondicionado decimal *
nFSInfo[] -> Servico -> Valores -> DescontoIncondicionado decimal *
nFSInfo[] -> Servico -> Valores -> OutrasRetencoes decimal *
nFSInfo[] -> Servico -> Valores -> TotalTributos decimal *
nFSInfo[] -> Servico -> Valores -> AliquotaIr decimal *
nFSInfo[] -> Servico -> ConfiguracaoImposto -> IncidePis true ou false * Incide 0,65% de PIS caso o valor for maior que R$215,05
falso - Não incide o valor
verdadeiro - Incide o valor
nFSInfo[] -> Servico -> ConfiguracaoImposto -> IncideCofins true ou false * Incide 3,00% de COFINS caso o valor for maior que R$215,05
falso - Não incide o valor
verdadeiro - Incide o valor
nFSInfo[] -> Servico -> ConfiguracaoImposto -> IncideCsll true ou false * Incide 1,00% de CSLL caso o valor for maior que R$215,05
falso - Não incide o valor
verdadeiro - Incide o valor
nFSInfo[] -> Servico -> ConfiguracaoImposto -> IncideIr true ou false * Incide 1,50% (ou a alíquota informada em (Valores -> AliquotaIr)) de IR caso o valor for maior que R$666,66
falso - Não incide o valor
verdadeiro - Incide o valor
nFSInfo[] -> Servico -> ConfiguracaoImposto -> ForcarIncidenciaPis true ou false * Incide 0,65% de PIS independente do valor
falso - Não incide o valor
verdadeiro - Incide o valor
nFSInfo[] -> Servico -> ConfiguracaoImposto -> ForcarIncidenciaCofins true ou false * Incide 3,00% de COFINS independente do valor
falso - Não incide o valor
verdadeiro - Incide o valor
nFSInfo[] -> Servico -> ConfiguracaoImposto -> ForcarIncidenciaCsll true ou false * Incide 1,00% de CSLL independente do valor
falso - Não incide o valor
verdadeiro - Incide o valor
nFSInfo[] -> Servico -> ConfiguracaoImposto -> ForcarIncidenciaIr true ou false * Incide 1,50% (ou a alíquota informada em (Valores -> AliquotaIr)) de IR independente do valor
falso - Não incide o valor
verdadeiro - Incide o valor

JSON Retorno

Parâmetro Tipo Tamanho Descrição
DataRecebimento data 1 Data que foi recebido o lote
Lote numérico * Número do Lote das NFS-e
CodLote texto * Número do Lote do Brasil NF-e
Protocolo texto * Número do Lote das NFS-e
CodTipoAmbiente numérico 1 Tipo de Ambiente de Transmissão
1 - Produção;
2 - Homologação;
MunicipioEnvio texto 1 Nome do município de transmissão da NFS-e
StatusLote numérico 1 Status da transmissão do lote
1 - Lote processado;
2 - Aguardando processamento;
3 - Ocorreu um erro ao processar o lote;
4 - Ocorreu um erro ao analisar as informações do lote;
Error texto * Descrição do erro, caso o status retornado for igual a 3
Notas[] -> Cancelada true ou false * Informa se a NFS-e encontra-se cancelada
Notas[] -> NumeroRPS numérico * Número do RPS
Notas[] -> DtEmissao data * Data da emissao da NFSe
Notas[] -> CpfCnpjPrestador texto * Cpf ou Cnpj do Prestador
Notas[] -> CpfCnpjTomador texto * Cpf ou Cnpj do Tomador
Notas[] -> NumeroNFSe texto * Número da NFS-e
Notas[] -> CodVerificacao texto * Código de verificação da NFS-e gerado pela prefeitura
Notas[] -> IdentificadorInterno texto * Identificador interno da nfs (enviado pela API)
Notas[] -> Status numérico * Status da NFS-e
1 - NFSe Emitida;
3 - Erro ao emitir;
Notas[] -> Erro texto * Descrição do erro caso a nota não for emitida
Notas[] -> Base64Xml texto * Dados xml da nfs, bytes em base64
Notas[] -> Base64Doc texto * Documento pdf da nfs, bytes em base64
Notas[] -> Valores -> BaseCalculo decimal * Base de cálculo
Notas[] -> Valores -> ValorLiquido decimal * Valor Líquido
Notas[] -> Valores -> ValorISS decimal * Valor do ISS
Notas[] -> Valores -> ValorISSRetido decimal * Valor do ISS Retido
Notas[] -> Valores -> ValorPIS decimal * Valor do PIS
Notas[] -> Valores -> ValorCOFINS decimal * Valor do COFINS
Notas[] -> Valores -> ValorCSLL decimal * Valor do CSLL
Notas[] -> Valores -> ValorIR decimal * Valor do IR
Notas[] -> Valores -> Aliquota decimal * Alíquota do IIS em %

Municípios Homologados

Estado Município Certificado

Consultar Status

Esse artigo tem como objetivo apresentar a forma com que busca as informações do lote de NFS-e.

POST: https://api.brasilnfe.com.br/services/fiscal/BuscarNotaFiscalServico

JSON Envio

Parâmetro Tipo Tamanho Descrição
codLote texto * Código do Lote
Rps array [] * Números de RPS

JSON Retorno

Parâmetro Tipo Tamanho Descrição
DataRecebimento data 1 Data que foi recebido o lote
Lote numérico * Número do Lote das NFS-e
CodLote texto * Número do Lote do Brasil NF-e
Protocolo texto * Número do Lote das NFS-e
CodTipoAmbiente numérico 1 Tipo de Ambiente de Transmissão
1 - Produção;
2 - Homologação;
MunicipioEnvio texto 1 Nome do município de transmissão da NFS-e
StatusLote numérico 1 Status da transmissão do lote
1 - Lote processado;
2 - Aguardando processamento;
3 - Ocorreu um erro ao processar o lote;
4 - Ocorreu um erro ao analisar as informações do lote;
Error texto * Descrição do erro, caso o status retornado for igual a 3
Notas[] -> Cancelada true ou false * Informa se a NFS-e encontra-se cancelada
Notas[] -> NumeroRPS numérico * Número do RPS
Notas[] -> DtEmissao data * Data da emissao da NFSe
Notas[] -> CpfCnpjPrestador texto * Cpf ou Cnpj do Prestador
Notas[] -> CpfCnpjTomador texto * Cpf ou Cnpj do Tomador
Notas[] -> NumeroNFSe texto * Número da NFS-e
Notas[] -> CodVerificacao texto * Código de verificação da NFS-e gerado pela prefeitura
Notas[] -> IdentificadorInterno texto * Identificador interno da nfs (enviado pela API)
Notas[] -> Status numérico * Status da NFS-e
1 - NFSe Emitida;
3 - Erro ao emitir;
Notas[] -> Erro texto * Descrição do erro caso a nota não for emitida
Notas[] -> Base64Xml texto * Dados xml da nfs, bytes em base64
Notas[] -> Base64Doc texto * Documento pdf da nfs, bytes em base64
Notas[] -> Valores -> BaseCalculo decimal * Base de cálculo
Notas[] -> Valores -> ValorLiquido decimal * Valor Líquido
Notas[] -> Valores -> ValorISS decimal * Valor do ISS
Notas[] -> Valores -> ValorISSRetido decimal * Valor do ISS Retido
Notas[] -> Valores -> ValorPIS decimal * Valor do PIS
Notas[] -> Valores -> ValorCOFINS decimal * Valor do COFINS
Notas[] -> Valores -> ValorCSLL decimal * Valor do CSLL
Notas[] -> Valores -> ValorIR decimal * Valor do IR
Notas[] -> Valores -> Aliquota decimal * Alíquota do IIS em %

Cancelamento

Esse artigo tem como objetivo apresentar a forma com que é efetuado o cancelamento de uma nota fiscal NFS-e.

POST: https://api.brasilnfe.com.br/services/fiscal/CancelNF

JSON Envio

Parâmetro Tipo Tamanho Descrição
TipoAmbienteNFSe numérico * Ambiente de emissão da NFS-e (Padrão 1)
1 - Produção;
2 - Homologação;
TipoDocumento numérico * Tipo do documento fiscal (Padrão 0 - NF-e, NFC-e, MDF-e, CFe-SAT), sempre especificar 1 para NFS-e
0 - NF-e, NFC-e, MDF-e, CFe-SAT;
1 - NFS-e;
NumeroNFSe texto * Número da NFS-e a ser cancelada
CodCancelamentoNFSe numérico * Código do motivo de cancelamento da NFS-e (Padrão 1)
1 - Erro na emissão;
2 - Serviço não prestado;
3 - Duplicidade da nota;
9 - Outros;

JSON Retorno

Parâmetro Tipo Tamanho Descrição
DsMotivo texto * Descrição do status do evento emitido
DsEvento texto * Descrição do evento emitido
DsAmbiente texto * Descrição do ambiente em que foi emitido o evento
NuProtocolo texto * Número de protocolo do evento
CodStatusRespostaSefaz numerico * Código de status de resposta da SEFAZ
NumeroSequencial numerico * Número sequencial do evento
Status numerico 1 Status do evento
1 - Evento Processado;
2 - Aguardando Processamento do Evento;
3 - Ocorreu um erro ao processar o evento;
Error texto * Descrição do erro, caso o status retornado for igual a 3
{ "DsMotivo": "", "DsEvento": "CANCELAMENTO", "DsAmbiente": "Produção", "NuProtocolo": "", "NumeroSequencial": 0, "CodStatusRespostaSefaz": 0, "Status": 1, "Error": "" }

Nota Fiscal de Energia - 6, Comunicação - 21 e TeleComunicação - 22

Esta seção abrange os métodos específicos para a emissão de Nota Fiscal modelos (6, 21 e 22). Aqui, você encontrará descrições detalhadas de como implementar e usar corretamente esses métodos em sua integração, garantindo a emissão correta conforme os requisitos legais e técnicos.

As notas dos modelos 06, 21 e 22 são indicadas para prestadores de todo o país, desde que a atividade da empresa se encaixe em um ou mais dos serviços classificados em comunicação, telecomunicação ou fornecimento de energia elétrica.

Os 3 modelos se dividem da seguinte forma:

Modelo 06 - Nota Fiscal/Conta de Energia Elétrica: É a nota utilizada para empresas distribuidoras de energia elétrica.

Modelo 21 - Nota Fiscal de Serviço de Comunicação: É a nota utilizada pelas empresas prestadoras de serviços de comunicação, tais como provedores de internet, rádio, TV, transmissão de anúncios, etc.

Modelo 22 - Nota Fiscal de Serviço de Telecomunicação: É a nota utilizada pelas empresas prestadoras de serviços de telecomunicação, tais como telefonia fixa ou móvel, Voip, etc.

Existem duas formas de envio para notas fiscais de energia, comunicação e telecomunicação. A primeira é o envio individual, permitindo a integração para envio ao longo do período, com a possibilidade de gerar o arquivo magnético ao final, a partir da data especificada. A segunda opção é o envio em lote, no qual todas as notas são transmitidas de uma só vez.

Transmissão

O método de transmissão valida as informações e as armazena para futura geração de arquivo magnético.

POST: https://api.brasilnfe.com.br/services/fiscal/EnviarNFEnerCom

JSON Envio

Parâmetro Tipo Tamanho Descrição
modeloDocumento numérico * Modelo do Documento
6 - Energia elétrica;
21 - Comunicação;
22 - Telecomunicação;
tipoAmbiente numérico * Tipo de ambiente (Somente no envio individual)
1 - Produção;
2 - Homologação;
identificadorInterno texto * Código de controle interno unico da venda. Evita duplicidades, caso configurado.
serie texto * Série da nota fiscal. Quando não informado é controlado pelo Painel
numero numérico * Número da nota fiscal. Quando não informado é controlado pelo Painel
situacao numérico 1 Situação do documento (Padrão 4)
1 - documento fiscal cancelado dentro do mesmo período de apuração;
2 - documento fiscal emitido em substituição a um documento fiscal cancelado dentro do mesmo período de apuração;
3 - documento fiscal complementar;
4 - demais casos;
valorTotalFatura decimal * Valor total da fatura comercial
dataEmissao DateTime * Data de emissão do documento
comunicao -> tipoUtilizacao numérico * Tipo de Utilização
1 - Telefonia;
2 - Comunicação de dados;
3 - TV por assinatura;
4 - Provimento de acesso à internet;
5 - Multimídia;
6 - Outros;
comunicao -> tipoAssinante numérico * Tipo de Assinante
1 - Comercial/Industrial;
2 - Poder público;
3 - Residencial/Pessoa física;
4 - Público;
5 - Semi-público;
6 - Outros;
energia -> classeConsumo numérico * Código Classe de Consumo
1 - Comercial;
2 - Consumo próprio;
3 - Iluminação pública;
4 - Industrial;
5 - Poder público;
6 - Residencial;
7 - Rural;
8 - Serviço Público;
energia -> subClasseConsumo numérico * Código da subclasse de consumo de energia elétrica.
1 - Residencial;
2 - Residencial baixa renda;
3 - Residencial baixa renda indígena;
4 - Residencial baixa renda quilombola;
5 - Residencial baixa renda benefício de prestação continuada da assistência social;
6 - Residencial baixa renda multifamiliar;
7 - Comercial;
8 - Serviços de transporte, exceto tração elétrica;
9 - Serviços de comunicação e telecomunicação;
10 - Associação e entidades filantrópicas;
11 - Templos religiosos;
12 - Administração condominial: iluminação e instalações de uso comum de prédio ou conjunto de edificações;
13 - Iluminação em rodovias: solicitada por quem detenha concessão ou autorização para administração em rodovias;
14 - Semáforos, radares e câmeras de monitoramento de trânsito, solicitados por quem detenha concessão ou autorização para controle de trânsito;
15 - Outros serviços e outras atividades da classe comercial;
16 - Agropecuária rural;
17 - Agropecuária urbana;
18 - Residencial rural;
19 - Cooperativa de eletrificação rural;
20 - Agroindustrial;
21 - Serviço público de irrigação rural;
22 - Escola agrotécnica;
23 - Aquicultura;
24 - Poder público Federal;
25 - Poder Público Estadual ou Distrital;
26 - Poder público Municipal;
27 - Tração Elétrica;
28 - Água esgoto ou saneamento;
99 - Outros;
energia -> grupoTensao numérico * Código do grupo de tensão
1 - A1 - Alta tensão (230kV ou mais);
2 - A2 - Alta tensão (88 a 138kV);
3 - A3 - Alta tensão (69kV);
4 - A3a - Alta tensão (30kV a 44kV);
5 - A4 - Alta tensão (2,3kV a 25kV);
6 - AS - Alta tensão subterrâneo;
7 - B1 - Residencial;
8 - B1 - Residencial baixa renda;
9 - B2 - Rural;
10 - B2 - Cooperativa de eletrificação rural;
11 - B2 - Serviço público de irrigação;
12 - B3 - Demais classes;
13 - B4a - Iluminação pública - rede de distribuição;
14 - B4b - Iluminação pública - bulbo de lâmpada;
energia -> tarifaAplicada decimal * Tarifa aplicada
energia -> dataLeituraAnterior DateTime * Data de leitura anterior
energia -> dataLeituraAtual DateTime * Data de leitura atual
destinatario -> codigo texto * Código interno que identifica o destinatário
destinatario -> cpfCnpj texto * CFP ou CNPJ
destinatario -> ie texto * Inscrição Estadual
destinatario -> razaoSocial texto * Razão Social
destinatario -> endereco -> cep texto * CEP do local
destinatario -> endereco -> logradouro texto * Descrição do Logradouro
destinatario -> endereco -> complemento texto * Complemento do endereço
destinatario -> endereco -> numero texto * Número da residência
destinatario -> endereco -> bairro texto * Descrição do Bairro
destinatario -> endereco -> codMunicipio texto * Código do município de acordo com a tabela IBGE
destinatario -> endereco -> municipio texto * Descrição do município
destinatario -> endereco -> uf texto * Unidade federativa, Exemplos: MG, SP, RJ
destinatario -> endereco -> codPais numérico 1058 Código do país. Padrão: 1058 (Brasil)
destinatario -> endereco -> pais texto BRASIL Descrição do País. Padrão: Brasil
produtos[] -> codigo texto * Código interno que identifica item
produtos[] -> descricao texto * Descrição do item
produtos[] -> codClassificacao texto * Código de classificação do serviço
produtos[] -> cfop numérico * Código CFOP
produtos[] -> unidadeMedida texto * Unidade de Medida
produtos[] -> quantidade decimal * Quantidade de itens
produtos[] -> valor decimal * Valor unitário do item
produtos[] -> desconto decimal * Desconto total aplicado no item
produtos[] -> outrasDespesas decimal * Acréscimos e Despesas Acessórias
produtos[] -> aliqIcms decimal * Alíquota de Icms
produtos[] -> aliqPis decimal * Alíquota de PIS
produtos[] -> aliqCofins decimal * Alíquota de Cofins
produtos[] -> codTributacao texto * Código do grupo tributário cadastrado no Painel, para automação de impostos
{ "modeloDocumento": 21, "tipoAmbiente": 2, "identificadorInterno": "123456", "serie": "SER", "numero": 1, "situacao": 4, "valorTotalFatura": 0, "dataEmissao": "2025-02-26T00:00:00", "comunicao": { "tipoUtilizacao": 1, "tipoAssinante": 1 }, "destinatario": { "codigo": "5522", "cpfCnpj": "000.000.000-84", "ie": "", "razaoSocial": "Teste", "endereco": { "cep": "29020300", "logradouro": "Avenida Alexandre Buaiz", "complemento": "", "numero": "100", "bairro": "Ilha do Principe", "codMunicipio": "3205309", "municipio": "Vitória", "uf": "ES", "codPais": 1058, "pais": "BRASIL" } }, "produtos": [ { "codigo": "123456", "descricao": "Provedor de Internet", "codClassificacao": "0102", "cfop": 0, "unidadeMedida": "UND", "quantidade": 1.0000, "valor": 15.00, "desconto": 0.00, "outrasDespesas": 0.00, "aliqIcms": 18.00, "aliqPis": 0.00, "aliqCofins": 0.00 }, { "codigo": "123456", "descricao": "Provedor de Internet", "codTributacao": "as2d54aswq23", "unidadeMedida": "UND", "quantidade": 3.0000, "valor": 10.00, "desconto": 0.00, "outrasDespesas": 0.00 } ] }

JSON Retorno

Parâmetro Tipo Tamanho Descrição
status true ou false 1 Status do Lançamento
erros Lista(objeto) * Lista de erros contendo informações detalhadas
erros[] -> codigo texto * Código do erro
erros[] -> descricao texto * Descrição do erro
erros[] -> correcao texto * Sugestão de correção para o erro
avisos Lista(texto) * Lista de avisos (mensagens de alerta)
{ "status": false, "erros": [ { "codigo": "ERR001", "descricao": "Campo 'nome' é obrigatório.", "correcao": "Por favor, preencha o campo 'nome'." }, { "codigo": "ERR002", "descricao": "Formato de data inválido.", "correcao": "Utilize o formato 'YYYY-MM-DD' para datas." } ], "avisos": [ "O campo 'telefone' não foi preenchido, mas não é obrigatório.", "O valor do campo 'idade' está próximo do limite mínimo recomendado." ] }

Obter Arquivo de Lote

Esse artigo tem como objetivo apresentar a forma com que gera e retorna arquivo de transmissão.

A validação e transmissão do arquivo é feito no validador externo ao sistema.

Para realizar o download do validador clique aqui.

Esse endpoint retona umm arquivo .zip em base64

POST: https://api.brasilnfe.com.br/services/fiscal/ObterArquivoNFEnerCom

JSON Envio

Parâmetro Tipo Tamanho Descrição
tipoGeracao numérico 1 Tipo de geração de arquivo
1 - Gera o arquivo a partir das notas enviadas no período informado;
2 - Gera o arquivo a partir da lista de notas;
tipoAmbiente numérico * Tipo de ambiente
1 - Produção;
2 - Homologação;
mes numérico * Mês de emissão das notas
ano numérico * Ano de emissão das notas
notas Lista(Objeto) * Notas Fiscais de Energia, Comunicação e Telecomunicações
{ "tipoGeracao": 1, "tipoAmbiente": 2, "mes": 10, "ano": 2023, "notas": [] }

JSON Retorno

Parâmetro Tipo Tamanho Descrição
status true ou false 1 Status de geração do arquivo
base64Zip base64 (Texto) 1 Base64 contendo o arquivo em zip
erros Lista(objeto) * Lista de erros contendo informações detalhadas
erros[] -> codigo texto * Código do erro
erros[] -> descricao texto * Descrição do erro
erros[] -> correcao texto * Sugestão de correção para o erro
avisos Lista(texto) * Lista de avisos (mensagens de alerta)
{ "status": false, "base64Zip": "UEsDBBQAAAAIAOh3SVZ...", "erros": [ { "codigo": "ERR001", "descricao": "Falha ao validar o campo 'dataEmissao'.", "correcao": "Verifique se a data está no formato 'YYYY-MM-DD'." }, { "codigo": "ERR002", "descricao": "Campo 'valorTotal' não pode ser negativo.", "correcao": "Insira um valor positivo para o campo 'valorTotal'." } ], "avisos": [ "O campo 'emitente' não foi preenchido, mas não é obrigatório.", "O arquivo gerado contém mais de 100 notas fiscais." ] }

Empresa

Aqui, nós abordaremos os principais métodos disponíveis que determina configurações cruciais para o uso dos serviços.

Cada empresa possui informações individuais que podem ser alteradas tanto pelo painel quanto pelo web-service, cada informação possui finalidade especifica para um ou mais serviços e a mesma é de total responsabilidade do usuário

Para o uso dos métodos dessa sessão é nescessário adicionar o cabeçalho (HTTP headers) na solicitação "UserToken".

-H "UserToken: token_usuario"
-H "Token: token_empresa" (Obrigatório nos métodos Editar, Alterar Cerificado, Verificar Certificado)
-H "Content-Type: application/json"

Adicionar ou Editar uma Empresa

Este método permite adicionar uma nova empresa ao painel, para que seja possível utilizar os serviços disponíveis.

POST: https://api.brasilnfe.com.br/services/empresa/AdicionarEmpresa

Este método permite editar uma empresa.

POST: https://api.brasilnfe.com.br/services/empresa/EditarEmpresa

JSON Envio

Parâmetro Tipo Tamanho Descrição
CNPJ texto 14 ou 11 CNPJ ou CPF
NmFantasia texto * Nome fantazia
RzSocial texto * Razão social
TipoEmpresa numérico 1 Classificação
1 - Matriz;
2 - Filial;
IE texto * Inscrição estadual
IM texto * Inscrição municipal
CRT numérico * Código do regime tributário
1 - Simples Nacional;
2 - Simples Nacional - Exesso Sublimite;
3 - Lucro Presumido (Regime Normal);
4 - Lucro Real (Regime Normal);
CNAE texto * Classificação Nacional de Atividades Econômicas
IdentificadorCSC texto * Identificado do código de segurança do contribuinte (NFC-e)
CodigoCSC texto * Código de segurança do contribuinte (NFC-e)
Site texto * Exemplo: www.brasilnfe.com.br
CodGrupo numérico * Código do grupo
Endereco -> Cep texto * CEP do local
Endereco -> Logradouro texto * Descrição do Logradouro
Endereco -> Complemento texto * Complemento do endereço
Endereco -> Numero texto * Número da residencia
Endereco -> Bairro texto * Descrição do Bairro
Endereco -> CodMunicipio texto * Código do município de acordo com a tabela IBGE
Endereco -> Municipio texto * Descrição do município
Endereco -> Uf texto * Unidade federativa, Exemplos: MG, SP, RJ
Endereco -> CodPais numérico * Código do país. Padrão: 1058 (Brasil)
Endereco -> Pais texto * Descrição do País. Padrão: Brasil
Contato -> Telefone texto * Telefone da empresa
Contato -> Email texto * Email da empresa
Configuração -> NFe -> CodTipoAmbiente numérico 1 Código Tipo Ambiente Emissão NF-e. Padrão: 1
1 - Produção;
2 - Homologação;
Configuração -> NFe -> ControleNumeracaoInterno Verdadeiro ou Falso 1 Controle de série e numeração interno?
Verdadeiro - A série e numeração e controlado pelo BrasilNFe;
Falso - A série e númeração e obrigatóriamente enviada pela API;
Configuração -> NFCe -> CodTipoAmbiente numérico 1 Código Tipo Ambiente Emissão NFC-e. Padrão: 1
1 - Produção;
2 - Homologação;
Configuração -> NFCe -> ControleNumeracaoInterno Verdadeiro ou Falso 1 Controle de série e numeração interno?
Verdadeiro - A série e numeração e controlado pelo BrasilNFe;
Falso - A série e númeração e obrigatóriamente enviada pela API;
Configuração -> NFSe -> CodTipoAmbiente numérico 1 Código Tipo Ambiente Emissão NFS-e. Padrão: 1
1 - Produção;
2 - Homologação;
Configuração -> NFSe -> TokenProcurador texto * Token da empresa que possui a procuração para emissão de notas
Configuração -> NFSe -> LoginWebService texto * Login para municípios que utilizam login/senha para autenticação no webservice
Configuração -> NFSe -> SenhaWebService texto * Senha para municípios que utilizam login/senha para autenticação no webservice
Configuração -> NFSe -> ControleNumeracaoInterno Verdadeiro ou Falso 1 Controle de série e numeração interno?
Verdadeiro - A série e numeração e controlado pelo BrasilNFe;
Falso - A série e númeração e obrigatóriamente enviada pela API;
Configuração -> Servicos -> MDFeCTe Verdadeiro ou Falso 1 Ativa ou desativa o serviço de MDF-e e CT-e (A modificação dessa informação interfere no valor a ser cobrado)?
Verdadeiro - Serviço ativado;
Falso - Serviço desativado;
Configuração -> Servicos -> NFeNFCe Verdadeiro ou Falso 1 Ativa ou desativa o serviço de NF-e e NFC-e (A modificação dessa informação interfere no valor a ser cobrado)?
Verdadeiro - Serviço ativado;
Falso - Serviço desativado;
Configuração -> Servicos -> NFSe Verdadeiro ou Falso 1 Ativa ou desativa o serviço de NFS-e (A modificação dessa informação interfere no valor a ser cobrado)?
Verdadeiro - Serviço ativado;
Falso - Serviço desativado;
Configuração -> Servicos -> Sped Verdadeiro ou Falso 1 Ativa ou desativa o serviço de SPED (A modificação dessa informação interfere no valor a ser cobrado)?
Verdadeiro - Serviço ativado;
Falso - Serviço desativado;
Configuração -> Servicos -> Sintegra Verdadeiro ou Falso 1 Ativa ou desativa o serviço de Sintegra (A modificação dessa informação interfere no valor a ser cobrado)?
Verdadeiro - Serviço ativado;
Falso - Serviço desativado;
Configuração -> Servicos -> CFeSat Verdadeiro ou Falso 1 Ativa ou desativa o serviço de CF-e SAT (A modificação dessa informação interfere no valor a ser cobrado)?
Verdadeiro - Serviço ativado;
Falso - Serviço desativado;

JSON Retorno

Parâmetro Tipo Tamanho Descrição
token texto 1 Token da empresa que foi adicionada ou editada
status Verdadeiro ou Falso 1 Status da operação de adição ou edição de empresa
Verdadeiro - empresa adicionada/editada com sucesso;
Falso - empresa não foi adicionada/editada;
Error texto * Descrição do erro, caso o status retornado for igual a false

Validações

Código Descrição
7001 CNPJ da empresa é inválido.
7002 Não foi informado os dados de endereço.
7003 Não foi informado o CEP da empresa.
7004 O CEP informado é inválido, o mesmo deve conter 8 dígitos.
7005 Não foi informado o logradouro da empresa.
7006 Não foi informado o bairro da empresa.
7007 O código do município do endereço da empresa é inválido, o mesmo deve conter 7 dígitos.
7008 O endereço de e-mail informado é inválido!

Buscar Empresa ou Buscar Todas Empresas

Este método permite buscar os dados de uma empresa cadastrada.

POST: https://api.brasilnfe.com.br/services/empresa/BuscarEmpresa

Este método permite buscar os dados de todas as empresas cadastradas no usuário.

POST: https://api.brasilnfe.com.br/services/empresa/BuscarTodasEmpresas

JSON Retorno

Esses metodos retorna o mesmo objeto JSON utilizado para adicionar uma empresa e pode ser visualizado clicando AQUI.

O método de buscar todas empresas retorna as mesmas informações do método de buscar uma empresa, porém, retorna um array com todas as empresas cadastradas.

Alterar Certificado

Esse método permite alterar o certificado digital de uma empresa, o certificado digital deve ser atualizado sempre que o mesmo expirar, caso contrário métodos de emissão de NF-e, NFC-e e NFS-e (em alguns municípios) não irão funcionar.

O certificado digital enviado é do tipo A1, é um arquivo com extensão .pfx ou .p12. Lembrando que o mesmo deve ser enviado em base64.

POST: https://api.brasilnfe.com.br/services/empresa/AlterarCertificado

JSON Envio

Parâmetro Tipo Tamanho Descrição
Senha texto * Senha do certificado digital
Base64File texto * Base64 contendo o arquivo PDF ou XML

JSON Retorno

Parâmetro Tipo Tamanho Descrição
Expirado Verdadeiro ou Falso * Situação do certificado digital
Verdadeiro - expirado;
Falso - não esta expirado;
DtExpiracao data * Data que o certificado expira
status Verdadeiro ou Falso * Status da solicitação de alteração
Verdadeiro - certificado alterado com sucesso;
Falso - não foi possível alterar o certificado;
Error texto * Descrição do erro, caso o status retornado for igual a false

Validações

Código Descrição
8050 Não foi possível salvar as informações do certificado digital.
8051 CNPJ do certificado digital (...) diferente do CNPJ cadastrado!
8052 O certificado digital informado venceu em ...!
8053 Ocorreu um erro ao analisar o arquivo, certifique-se que senha está correta!

Verificar Certificado

Esse método permite verificar se o certificado digital cadastrado está expirado ou não.

Caso a propriedade "Interno" for igual a "false" deve ser enviado um certificado digital do tipo A1, é um arquivo com extensão .pfx ou .p12. Lembrando que o mesmo deve ser enviado em base64 na propriedade "Base64File".

POST: https://api.brasilnfe.com.br/services/empresa/VerifyCertificate

JSON Envio

Parâmetro Tipo Tamanho Descrição
Senha texto * Senha do certificado digital
Base64File texto * Base64 contendo o arquivo PDF ou XML
Interno Verdadeiro ou Falso * Forma de verificação do certificado. Padrão: Falso
Verdadeiro - Vai verificar o certificado digital atual cadastrado na empresa;
Falso - Vai verificar o certificado digital enviado na propriedade Base64File;

JSON Retorno

Parâmetro Tipo Tamanho Descrição
Expirado Verdadeiro ou Falso * Situação do certificado digital

Verdadeiro - expirado;
Falso - não esta expirado;
DtExpiracao data * Data que o certificado expira
status Verdadeiro ou Falso * Status da analise

Verdadeiro - certificado analisado com sucesso;
Falso - não foi possível analisar o certificado;
Error texto * Descrição do erro, caso o status retornado for igual a false

Validações

Código Descrição
8060 Erro ao ler certificado digital!