Integração da Nota Fiscal Eletrônica utilizando o Motor de Cálculo de Tributos (NF-e / NFC-e)
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:
Emitir uma nota fiscal eletrônica utilizando o motor de cálculo de tributos.
Próximos passos
- Consultar uma nota fiscal
- Consultar o XML de uma nota fiscal emitida
- Consultar o PDF (danfe) de uma nota fiscal emitida
- Motor de Cálculo de Tributos
Requisitos
Tutorial
A partir desse momento faremos uma breve explicação de como realizar a integração de Nota fiscal Eletrônica (NF-e / NFC-e) com a API oferecida pela NFE.io utilizando o Taxes (motor de cálculo de imposto).
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-01JKDTXTXB7DN8645BWG6K7C7KTutorial de como importar a url no postman Clique aqui
1. Introdução
Utilizamos uma API REST (Representational State Transfer), que é um padrão amplamente adotado para a integração entre sistemas.
-
Aqui estão os pontos principais sobre a forma de comunicação com a API NFE.io:
-
Protocolo HTTPS: HTTPS é uma combinação do protocolo HTTP com uma camada adicional de segurança chamada SSL/TLS (Secure Sockets Layer/Transport Layer Security). A comunicação é feita através do protocolo HTTP, o mesmo utilizado para navegar na web. Isso facilita a integração, pois é um protocolo bem conhecido e suportado por diversas plataformas.
-
Métodos HTTP: Utilizamos métodos HTTP para realizar diferentes operações:
- GET: Para obter informações.
- POST: Para enviar novas informações.
- PUT: Para atualizar informações existentes.
- DELETE: Para remover informações.
-
Formato de Dados: As requisições e respostas são geralmente em formato JSON, que é leve e fácil de interpretar. Isso torna a troca de dados eficiente e simples de manipular.
-
Códigos de Status: Cada resposta da API inclui um código de status HTTP que indica o resultado da operação, como:
- 200: Sucesso.
- 400: (BadRequest) Erros nos dados enviados.
- 404: Recurso não encontrado.
- 500: Erro no servidor.
-
-
A API NFE.io permitie que você escolha entre duas opções para emitir uma nota fiscal, são elas:
- Sem cálculo do imposto - As informações tributárias serão fornecidas por você, ou seja, a nota fiscal será emitida sem a utilização do motor de cálculo tributário.
Clique aqui para mais informações - Com cálculo do imposto - As informações tributárias serão fornecidas pela NFE.io, de acordo com os parâmetros informados no grupo "taxDetermination".
Veja o detalhamento mais abaixo.
- Sem cálculo do imposto - As informações tributárias serão fornecidas por você, ou seja, a nota fiscal será emitida sem a utilização do motor de cálculo tributário.
2. Visão Geral do fluxo de emissão de nota fiscal.
Primeiros passos
1. Emitir primeira nota fiscal
Pronto, todos os passos antecessores de emissão de suas notas fiscais eletrônicas estão concluídos.
Colocamos um exemplo do mínimo de dados para serem informados à nossa API, caso precise ou queira verificar o restante da documentação, estará disponível em: Documentação completa.
Os campos mínimos para serem enviados são os dados do comprador (buyer) e os produtos (items).
Obs.1: O grupo "taxDetermination" substituí o grupo "tax" (dados dos impostos da nota fiscal) para que o sistema acione automaticamente o Motor de Cálculo de Tributos. Desta forma o grupo "tax" será preenchido com o resultado da consulta no motor de cálculo de tributos de forma automática.
Saiba mais: O que é motor de cálculo de tributos
Abaixo, a url e um json de exemplo contendo os dados mínimos para a emissão de uma nota fiscal com a utilização do motor de cálculo de tributos.
Saiba mais: Entendendo a estrutura do json (layout de integração)
Observação: Substitua {companyId} pela ID gerada no passo de criação da Empresa e a {statetaxId} pela ID gerada no passo de criação da Inscrição Estadual.
O método HTTP utilizada no envio da nota fiscal é o "POST", então verifique no seu postman se está preenchido corretamente.
POST: https://api.nfse.io/v2/companies/{companyId}/statetaxes/{statetaxId}/productinvoices
{
"buyer": {
"name": "NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL",
"federalTaxNumber": 8662968678,
"address": {
"city": {
"code": "3550308",
"name": "jundiai"
},
"state": "SP",
"district": "centro",
"street": "rua petronilha antunes",
"postalCode": "13207760",
"number": "204",
"country": "BRA"
}
},
"items": [
{
"code": "2617",
"unitAmount": 9.98,
"quantity": 5,
"ncm": "47079000",
"cest": null,
"description": "FEIJAO BOLINHA CAMIL 500G NF ENTRADA 1030099 14/05/2018",
"codeGTIN": "9999999999999",
"taxDetermination": {
"BuyerTaxProfile": "<string>",
"IssuerTaxProfile": "<string>",
"acquisitionPurpose": "<string>",
"OperationCode": "<number>",
"Origin": "<string>"
}
}
]
}2. Detalhamento dos campos do grupo "taxDetermination":
O grupo "taxDetermination" define o cenário que representa a operação tributária realizada e é identificada por, basicamente, quatro códigos: natureza da operação, perfil do remetente, o perfil do destinatário e a finalidade da aquisição. Os quatro códigos combinados dão o significado para a operação realizada, exemplo: Industria rementendo para o varejo material de sua produção.
BuyerTaxProfile
- Para obter os valores disponíveis para preenchimento do campo "BuyerTaxProfile", faça uma chamada na API de listagem dos perfis fiscais do destinatário confome exemplo abaixo
Veja a documentação da API: BuyerTaxProfile
Destinatário/Perfil Destino
Tabela parcial com os perfis mais comuns.
| Código | Descrição |
|---|---|
| closed_warehouse | Depósito temporário (Fullfilment) |
| wholesale | Atacadista |
| company_abroad | Comercial exportadora (inclusive trading) |
| final_consumer_icms_contributor | Consumidor final contribuinte do ICMS |
| final_consumer_non_icms_contributor | Consumidor final não contribuinte do ICMS |
| importer | Importador |
| industry | Indústria |
| NationalSimple | Optante pelo Simples Nacional |
| retail | Varejista |
IssuerTaxProfile
- Para obter os valores disponíveis para preenchimento do campo "IssuerTaxProfile", faça uma chamada na API de listagem dos perfis fiscais do emissor confome exemplo abaixo:
Veja a documentação da API: IssuerTaxProfile
Remetente/Perfil Origem
Tabela parcial com os perfis mais comuns.
| Código | Descrição |
|---|---|
| wholesale | Atacadista |
| importer | Importador |
| industry | Indústria |
| retail | Varejista |
AcquisitionPurpose
- Para obter os valores disponíveis para preenchimento do campo "AcquisitionPurpose", faça uma chamada na API de listagem de finalidades de aquisição confome exemplo abaixo:
Veja a documentação da API: AcquisitionPurpose
Finalidade de aquisição
Tabela parcial com as finalidades de aquisição mais comuns.
| Código | Descrição |
|---|---|
| 220 | Compra de bem para o ativo imobilizado |
| 569 | Compra para comercialização |
| 202 | Compra para insumo |
| 43 | Compra de material para uso ou consumo |
| 197 | Entrada de amostra grátis |
| 353 | Entrada de bonificação |
| 198 | Entrada de mercadoria em demonstração |
| 201 | Entrada de mercadoria ou bem recebido para conserto ou reparo |
| 205 | Entrada de mercadoria recebida em consignação industrial |
| 204 | Entrada de mercadoria recebida em consignação mercantil |
| 189 | Entrada de mercadoria recebida para depósito em armazém geral |
| 188 | Entrada de mercadoria recebida para depósito em depósito fechado |
| 325 | Recebimento em transferência de material para uso ou consumo |
| 175 | Recebimento em transferência para comercialização |
| 174 | Recebimento em transferência para industrialização ou produção rural |
| 200 | Retorno de mercadoria remetida em exposição ou feira |
| 320 | Transferência de bem do ativo imobilizado |
OperationCode
- Para obter os valores disponíveis para preenchimento do campo "OperationCode", faça uma chamada na API de listagem de códigos da operação confome exemplo abaixo:
Veja a documentação da API: OperationCode
Natureza de Operação
Tabela parcial com as operações mais comuns.
| Código | Descrição |
|---|---|
| 159 | Remessa de amostra grátis |
| 549 | Remessa de mercadoria em consignação industrial |
| 547 | Remessa de mercadoria em consignação mercantil |
| 160 | Remessa de mercadoria em demonstração |
| 162 | Remessa de mercadoria ou bem para conserto ou reparo |
| 101 | Remessa de mercadoria ou bem para exposição ou feira |
| 537 | Remessa de mercadoria recebida de terceiros em bonificação |
| 105 | Remessa de mercadoria para armazém geral |
| 104 | Remessa de mercadoria para depósito fechado |
| 145 | Saída em transferência de bem do ativo imobilizado |
| 148 | Saída em transferência de material de uso ou consumo |
| 108 | Saída em transferência de mercadoria adquirida ou recebida de terceiros |
| 107 | Saída em transferência de produção do estabelecimento |
| 147 | Venda de bem do ativo imobilizado |
| 121 | Venda de mercadoria adquirida ou recebida de terceiros |
| 120 | Venda de produção do estabelecimento |
| 72 | Compra de mercadoria arrematada em leilão. |
| 569 | Compra para comercialização. |
| 630 | Compra pelo sistema de marketing direto para revendedores que operem na modalidade de venda porta-a-porta exclusivamente a consumidores finais ou em bancas de jornais e revistas. |
Origin
- Códigos do campo origem do material
- O código de origem do material é um código oficial e representa o conteúdo de importação do material. Segue a lista de todos os códigos disponíveis:
| Código | Descrição |
|---|---|
| 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 interno, 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 PPB 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 interno, sem similar nacional, constante em lista da CAMEX e gás natural |
| 8 | Nacional, mercadoria ou bem com Conteúdo de Importação superior a 70% |
3. Integração da nota fiscal no padrão "json".
- Você deverá enviar os dados preenchidos corretamente com as informações da sua nota fiscal e clicar no botão "Send" (Enviar).
- Ao sucesso da requisição, será fornecido uma ID da nota fiscal utilizada no processamento da emissão.
4. 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-01JKDTXTXB7DN8645BWG6K7C7KPróximos passos
- Consultar uma nota fiscal
- Consultar o XML de uma nota fiscal emitida
- Consultar o PDF (danfe) de uma nota fiscal emitida
- Motor de Cálculo de Tributos
