Pular para o conteúdo principal
Ver como Markdown

Primeiros Passos para Integração da Nota Fiscal Eletrônica.

A Nota fiscal eletrônica é o documento digital fiscal usada para a documentação de operaçóes de circulação de mercadorias ou prestação de serviço, seja transporte no mesmo estado, quanto entre estados.

Saiba mais: O que é nota fiscal eletrônica?

Ao final desse tutorial, você será capaz de:​

[1. Cadastrar uma empresa][16]
[2. Fazer upload de um certificado na plataforma][17]
[3. Cadastrar uma inscrição estadual][18]

Próximos passos​

  1. Emitir uma nota fiscal de produto
  2. Emitir uma nota fiscal de produto utilizando o Motor de Cálculo de Tributos
  3. Consultar uma nota fiscal
  4. Consultar o XML de uma nota fiscal emitida
  5. Consultar o PDF (danfe) de uma nota fiscal emitida

Requisitos​

Tutorial​

A partir desse momento faremos uma breve explicação de como realizar cadastros necessários para possibilitar a integração de Nota fiscal de Produto com a API oferecida pela NFE.io.

Veja mais sobre a Documentação da API

Você pode realizar a importação da url no Postman para ter todos os seguintes exemplos através do link:

https://api.postman.com/collections/13456751-f3769b82-5291-445b-b7bf-8fc0ffcab9b2?access_key=PMAT-01JKDTXTXB7DN8645BWG6K7C7K

Tutorial de como importar a url no postman Clique aqui

Primeiros passos​

Antes de tudo, você precisará realizar um cadastro na nossa plataforma app.nfe.io. Depois, você terá que pegar a chave de autorização do nosso sistema.

Devemos atentar para copiar a autorização referente 'Nota fiscal'

Ambiente: Homologação ou Produção​

A NFE.io oferece dois ambientes para emissão de NF-e e NFC-e. O ambiente é configurado na Inscrição Estadual (campo environmentType), não na empresa — uma mesma empresa pode ter IEs em estados diferentes, cada uma com seu próprio ambiente.

RecursoHomologação (Test)Produção (Production)
Inscrição EstadualObrigatória, com environmentType: "Test"Obrigatória, com environmentType: "Production"
Certificado Digital⚠️ Obrigatório⚠️ Obrigatório
Trânsito da notaSEFAZ de homologação (ambiente real do órgão)SEFAZ de produção (ambiente real do órgão)
Validade fiscalSem validade fiscalCom validade fiscal
NFC-e (nFCe)CSC obrigatório (Código de Segurança do Contribuinte)CSC obrigatório

Por que o certificado é obrigatório mesmo em homologação?​

Diferente da NFS-e (que roda em servidores NFE.io simulando prefeituras), o ambiente de Homologação da SEFAZ é o ambiente real do órgão estadual — apenas marcado como teste. A SEFAZ valida e responde a cada requisição assim como em produção, e por isso exige assinatura digital ICP-Brasil em todas as transmissões, inclusive em homologação.

Você precisa do certificado A1 vinculado à empresa antes de qualquer tentativa de emissão, mesmo só para testes.

Diferente de NFS-e

Para NFS-e, o certificado digital é opcional em ambiente de testes, porque o ambiente de testes da NFE.io para NFS-e usa servidores próprios simulando prefeituras (sem trânsito real ao órgão municipal). Veja a cadência para NFS-e em Primeiros Passos — NFS-e.

Inscrição Municipal não se aplica

NF-e e NFC-e não usam Inscrição Municipal (IM). Se você está usando o wizard de criar empresa pelo painel, marque a Etapa de IM como "É isento" e prossiga. A IM só é exigida para empresas que emitem NFS-e.

1. Obter a chave de autorização (apikey).​

Veja como pegar a chave de autorização na plataforma: Autenticação

Lembre-se: Após importar a url do postman e copiar a chave de autenticação para nota fiscal eletrônica, você deverá adicionar em cada requisição na aba "Auth", Auth Type "API Key", Key "Authorization", Value "inserir a chave" ou na aba "Headers" (cabeçalhos) a chave em "Authorization" (autorização).

  • Como configurar a chave de autorização no Postman.

2. Criar uma empresa​

Para emitir as notas fiscais, é necessário criar uma empresa. Neste momento será obrigatório a identificação do CNPJ, endereço e tipo de regime tributário.

Ao sucesso da requisição, será gerada um chave de identificação (ID), e você deve copiá-la para os passos seguintes.

Abaixo, a url e um json de exemplo contendo os dados para a criação de uma empresa.

Saiba mais: Entendendo a estrutura do json (layout de integração)

O método HTTP utilizada na criação da empresa é o "POST", portanto, verifique no seu postman se está preenchido corretamente.

POST: https://api.nfse.io/v2/companies/
 {  
  "company": {
    "name":"RAZAO SOCIAL DA EMPRESA",
    "federalTaxNumber": 99999999000199,
    "taxRegime": "SimplesNacional",
    "address":{  
     "state":"SP",
     "city":{   
        "code":"3550308",
        "name":"São Paulo"
     },
     "district":"BAIRRO",
     "additionalInformation":" INFORMAÇÃO ADICIONAL",
     "street":"AV NOME DA RUA",
     "number":"1111",
     "postalCode":"14940001",
     "country":"BRA"
    }
  }
}
  1. Você deverá enviar os dados preenchidos corretamente com as informações da sua empresa e clicar no botão "Send" (Enviar).
  • Create a Company
  1. Você receberá uma ID de empresa após o envio e sucesso da requisição.
    Será necerrário copiá-la para dar continuidade nos passos seguintes.
  • Company Id

Atenção: Em todas as requisições na API, deverá ser informado a ID da empresa fornecida no sucesso de requisição.

3. Fazer upload do certificado na plataforma​

O que é um certificado digital?​

Para entender mais sobre o que é um certificado digital, escrevemos um resumo em: Tudo sobre Certificado Digital.

Na nota fiscal eletrônica de produto devemos realizar uma requisição para o envio do certificado digital que será utilizado como autenticador com o Governo, onde deverá ser enviado o arquivo .pfx e a senha.

Atenção: Não se preocupe, após a inserção do certificado na nossa plataforma, todos os dados são criptografados para maior segurança.

Abaixo, a url e um json de exemplo contendo os dados para realizar o envio do certificado.

Observação: Substitua {companyId} pela ID gerada no passo de criação da empresa.
O método HTTP utilizada no envio do certificado é o "POST", portanto verifique no seu postman se está preenchido corretamente.

POST: https://api.nfse.io/v2/companies/{companyId}/certificates

  1. Você deverá selecionar o arquivo .pfx em seus arquivos juntamente com a senha e clicar no botão "Send" (Enviar).
  • Uploading a Certificate
  1. Após o sucesso da requisição, será informado alguns dados sobre o certificado, tais como:
    • A validade do certificado
    • Status se está ativou ou inativo na plataforma
    • Thumbprint
    • Dados sobre o emissor do certificado

4. Criar inscrição estadual​

O terceiro passo será criar o "State Tax", que identifica na nossa plataforma a Inscrição Estadual usada pela empresa.

Saiba mais sobre Inscrição Estadual.

  1. No cadastro da Inscrição Estadual você vai definir as seguintes informações:
    • "processingDetails" - Estratégia para emissão de nota fiscal em contingência.
      (clique aqui para mais informações).
    • "type" - Tipo de nota fiscal (NF-e [nFe] ou NFC-e [nFCe]).
    • "environmentType" -Ambiente da SEFAZ (Produção [production] ou Homologação [test]).
    • "serie" - Série da nota fiscal.
    • "number" - Número inicial da nota fiscal.
    • "code" - UF (define qual é a SEFAZ que vai recepcionar as notas fiscais).
    • "specialTaxRegime" - Regime especial de tributação (specialTaxRegime).
    • "taxNumber" - Número da Inscrição Estadual.
    • "securityCredential" - Código de segurança do contribuinte (necessário para emissão de NFCe).

A inscrição estadual tem possibilidade de ser uma ou mais por estado para o mesmo CNPJ. Portanto, separamos a requisição para melhor identificação e organização das sequências númericas.

Ela também é responsável por identificar o ambiente em que a nota fiscal será emitida, sendo disponível como "EnvironmentType" (tipo de ambiente), com os valores "Test" (desenvolvimento) e "Production" (produção).

Por padrão o ambiente criado na plataforma é "Test" (desenvolvimento).

O grupo de parâmetros "processingDetails" se refere ao detalhamento da estratégia de contingência que será adotada. Clique aqui para obter mais informações.

Abaixo, a url e um json de exemplo contendo os dados básicos para a criação de uma inscrição estadual.

Observação: Substitua {companyId} pela ID gerada no passo anterior.

O método HTTP utilizada na criação da inscrição estadual é o "POST", portanto, verifique no seu postman se está preenchido corretamente.

POST: https://api.nfse.io/v2/companies/{companyId}/stateTaxes

{
  "stateTax": {
    "code": "SP",
    "taxNumber": "99999999999",
    "specialTaxRegime": "automatico",
    "environmentType": "Test",
    "type": "nFe",
    "serie": 1,
    "number": 1,
    "processingDetails": {
        "SwitchAuthorizerStrategy" : "StateTaxAuthorityStatusUnavailable"
        // "SwitchAuthorizerStrategy" : "Manual"
    },
    //O grupo abaixo deve ser informado somente se o 'type' for 'nFCe'
    "securityCredential": {
        "id": 1,
        "code": "999999999999999"
    }
  }
}

Devemos atentar para os valores de Série e Número (serie e number), que são utilizados pela SEFAZ para sequenciar as notas emitidas por uma empresa.

Caso você já emita nota, precisará identificar qual a série e o último número emitido, com isso podemos continuar a emissão de onde parou.

Se preferir, poderá identificar com seu contador, uma nova série e número para emissão de nota com a nossa plataforma.

  1. Você deverá enviar os dados preenchidos corretamente com as informações da sua inscrição estadual e clicar no botão "Send" (Enviar).
  • Create a StateTax
  1. Você receberá uma ID da inscrição estadual após o envio e sucesso da requisição.
  • StateTax Id

Importação da url do postman​

Novamente, fornecemos uma URL de importação no POSTMAN com todas essas requisiçôes já inclusas. Basta inserir sua Autorização em cada requisição e alterar os dados fornecidos.

https://api.postman.com/collections/13456751-f3769b82-5291-445b-b7bf-8fc0ffcab9b2?access_key=PMAT-01JKDTXTXB7DN8645BWG6K7C7K

Próximos passos​

  1. Emitir uma nota fiscal de produto
  2. Emitir uma nota fiscal de produto utilizando o Motor de Cálculo de Tributos
  3. Consultar uma nota fiscal
  4. Consultar o XML de uma nota fiscal emitida
  5. Consultar o PDF (danfe) de uma nota fiscal emitida

Veja também:​

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.