Esta seção do Guides Focus NFe irá explicar tudo o que é necessário em seu sistema para uma boa integração com a Focus NFe. Na realidade, as práticas aqui exploradas são válidas para qualquer sistema que queira gerenciar documentos fiscais, independente de utilizar uma API como a Focus NFe ou até mesmo integrar diretamente com as receitas e prefeituras.
Recomendamos a leitura atenta dos tópicos desta seção, pois uma boa estruturação do seu sistema pode ser determinante para o sucesso do seu projeto.
Para implementar a gestão de documentos fiscais com sucesso em seu sistema, dedique um tempo para entender todos os documentos que existem, mesmo que não se aplique a seus clientes.
No Brasil hoje existem diversos tipos de documentos fiscais. Provavelmente nem todos se aplicam aos seus usuários. Além disso há bastante confusão sobre qual documento fiscal deve ser utilizado por quais empresas e em quais situações. É por isso que antes de começar a integrar a gestão de documentos fiscais em seu sistema é extremamente importante que você e sua equipe tenham um conhecimento básico sobre cada tipo de documento fiscal. Preparamos um resumo sobre todos eles abaixo. Depois de ler este resumo você já deverá ser capaz de saber quais os documentos que se aplicam ao seu contexto.
NF-e: É um documento utilizado para operações com produtos, como vendas, transferências, devoluções e ajustes. Esse documento também é conhecido como nota modelo 55 ou, simplesmente, NF-e. Quando realizamos uma compra de produtos em um e-commerce, por exemplo, o documento fiscal emitido é uma NF-e.
NFC-e: Documento utilizado para operações presenciais com consumidores finais e não contribuintes. Ela também é permitida em deliveries. Esse documento também é conhecido como cupom fiscal, nota fiscal modelo 65 ou, simplesmente, NFC-e. Quando um consumidor comum realiza uma compra presencial em uma farmácia, mercado ou posto de combustível, o documento fiscal emitido é uma NFC-e.
NFS-e: Utilizado para operações de prestação de serviços, sejam eles para destinatários pessoas físicas ou jurídicas. Esse documento é conhecido como nota fiscal de serviços eletrônica ou, simplesmente, NFS-e.
NFS-e Nacional: Assim como a NFSe, este documento é utilizado para operações de prestação de serviços, sejam eles para destinatários pessoas físicas ou jurídicas. Este documento foi criado por um esforço nacional pela unificação das emissões de Notas de Serviço. Tratamos como um documento diferente da NFS-e pois seu modelo e seus dados diferem substancialmente daquele.
MD-e: O MD-e ou Manifesto do destinatário não é um documento fiscal, mas um serviço disponibilizado pela Receita. Ele consiste no recebimento das NF-es pelo destinatário ou outras pessoas envolvidas e citadas em uma operação acobertada pelo documento fiscal. Dessa forma, todos tomam conhecimento da emissão e, ainda, é possível que o destinatário se manifeste sobre o conhecimento ou não acerca daquela operação, bem como a sua efetivação.
CT-e: É um documento utilizado em operações de transporte de cargas, por diversos modais, como rodoviário, aéreo, aquaviário, ferroviário, etc. A utilização do CT-e permite aos transportadores relacionar nesse documento diversas notas fiscais que compõem os objetos da carga, além de citar locais de origem e destino, assim como tomadores, recebedores e outras entidades envolvidas no processo.
MDF-e: Utilizado em operações de transporte, onde exista mais de uma CT-e ou NF-e. O objetivo é facilitar o registro e a fiscalização de documentos em lote. Dessa forma, durante uma operação ou fiscalização regular, o manifesto deverá ser apresentado e, nele, estará concentrada toda a operação daquele transporte.
As APIs da Focus NFe são APIs REST e a comunicação ocorre através de JSON. A comunicação com uma API REST ocorre através de chamadas HTTP, então a linguagem de programação utilizada em seu sistema precisa ter bibliotecas, nativas ou não, capazes de realizar este tipo de chamada.
É bastante importante também que a sua linguagem de programação possa criar e interpretar facilmente arquivos JSON.
Além disso, para receber o retorno de nossas APIs através de Webhooks (recomendado, porém não obrigatório), seu sistema deve ser capaz de lidar com chamadas HTTP e estar disponível na web.
Check List de tecnologias
O primeiro passo para integrar o seu sistema com a emissão de notas fiscais da Focus NFe é decidir a modelagem dos seus dados. A modelagem exata vai variar conforme o negócio atendido pelo seu software, os tipos de documentos fiscais que serão emitidos e a sua modelagem de dados atual. Abaixo elencamos algumas dicas e pontos de atenção neste sentido.
Apesar de não ser uma boa prática, caso seu sistema atenda a apenas uma empresa não há uma necessidade forte por inserir estes dados em seu banco de dados, porém se o sistema atende a mais de uma empresa será importante que os dados da empresa sejam armazenados em banco de dados.
Além dos dados padrão de qualquer empresa, como CNPJ, I.E., I.M, endereçamento e etc, os seguintes dados podem ser interessantes para sua aplicação:
É importante que seu sistema esteja preparado para armazenar informações importantes para o cálculo dos impostos. Este cadastro pode estar localizado em um ou mais níveis de informação em seu sistema, alguns mais típicos são:
Global por empresa: Para casos mais simples, em que todas as notas de uma determinada empresa seguem as mesmas regras de impostos, você pode criar uma tabela global, relacionada às empresas, para armazenar estes parâmetros. Por tipo de produto ou serviço: É possível que seja necessário armazenar parâmetros de cálculo de impostos para determinados tipos de produto ou serviço. Neste caso seu sistema pode utilizar o tipo para guiar o preenchimento dos campos de impostos. Por tipo de operação: Aqui seu sistema poderia parametrizar o preenchimento dos cálculos de impostos por tipo de operação realizada. Por produto ou serviço: Para casos mais complexos é possível que seja necessário armazenar os parâmetros de preenchimento com base no produto ou serviço em si.
O local onde estes parâmetros devem ser armazenados vai variar conforme o tipo de negócio atendido pelo seu sistema, a complexidade dos impostos e outros fatores. O importante é estar atento para a necessidade de armazenamento destes parâmetros.
Não é uma boa prática criar uma relação 1:1 entre a operação e a emissão do documento fiscal. Tenha uma modelagem específica para as tentativas de emissão.
Intuitivamente pensamos em armazenar os dados do documento fiscal como novas colunas na tabela que representa a operação realizada. Por exemplo, em um sistema comercial que possui uma tabela chamada “vendas” é natural que se pense em armazenar o número da nota, sua série, URL do XML e etc na própria tabela “vendas”. Isso pode ser um erro e causar problemas. Alguns motivos para isso são:
NFe denegada: Na tentativa de emissão de uma nota fiscal ela pode ser denegada. Neste caso existe um documento fiscal, que deve ser armazenado, porém com status denegado. Após ajustar as informações que causaram esta situação a nota fiscal pode ser autorizada, porém é importante que a informação das duas notas seja armazenada em banco de dados.
NFe cancelada e reemitida: Em alguns casos pode ocorrer uma emissão bem sucedida, porém com dados incorretos. Por exemplo, digamos que uma nota foi emitida com o endereço do destinatário incorreto, o cliente final pediu que a nota fosse reemitida. Neste caso a venda teria uma nota cancelada e outra emitida.
NFe emitida em contingência com a nota original cancelada: Em alguns casos específicos é possível que sejam emitidas duas notas para a mesma venda. Isso ocorre, por exemplo, quando o servidor da receita cai no momento da emissão de uma nota. A Focus NFe emite a nota em contingência e depois cancela a nota do ambiente padrão, caso também tenha sido emitida. Neste caso duas notas estarão associadas à venda, uma cancelada e outra autorizada.
Antes de iniciar a implementação da sua integração com a API da Focus NFe, recomendamos fortemente que você teste suas chamadas utilizando a nossa coleção pronta no Postman. Com essa coleção, você pode explorar e experimentar os principais endpoints da API, entendendo como eles funcionam na prática, sem a necessidade de escrever código.
Você pode acessar a nossa coleção de chamadas através do link: Focus NFe - Coleção Postman.
Você sabia que o Postman pode gerar código para diversas linguagens? Ao configurar uma chamada é possível exportar o código fonte que realiza aquela chamada em praticamente qualquer linguagem. Utilize isso e ganhe ainda mais tempo na integração com a Focus NFe.
Utilizando a coleção do Postman, você terá uma experiência mais fluida e segura, garantindo que sua integração esteja configurada corretamente antes de seguir para a implementação definitiva.
Como ocorre em qualquer API, a Focus NFe possui um rate-limit, ou limite de consumo. O rate-limit padrão da Focus NFe é de 100 requisições por minuto por token. Este volume de requisições permitido é o suficiente para a maior parte das aplicações. Aplicações com grande volume de emissões podem precisar de rate-limits maiores, ou que pode ser solicitado para que nossa equipe de suporte avalie e aumente o limite.
Algumas boas práticas são recomendadas para que seu sistema não seja limitado pelo rate-limit. Além de não ser bloqueado estas boas práticas servem para que seu sistema se integre à Focus NFe da maneira mais adequada e eficiente possível.
A maior parte dos documentos fiscais são processados de forma assíncrona, ou seja, enviamos a requisição para a entidade do governo que processará a informação, e aguardamos o processo se completar, consultando novamente a entidade e obtendo uma resposta. Dessa forma, sua aplicação também participa desse processo de maneira assíncrona. Assim, você deverá observar os seguintes cuidados:
Tempo: O tempo médio de processamento de um documento fiscal depende do volume de requisições, da disponibilidade do órgão governamental e do manejo de filas da API Focus. Em média, esse processo é de poucos segundos para a maior parte dos documentos, embora possa levar alguns minutos quando falamos de notas fiscais de serviço.
Consultas: Consultas com intervalos muito pequenos são desnecessárias, e consomem recursos computacionais.
Webhooks: A API Focus disponibiliza uma forma mais simples e assertiva para trabalhar com documentos assíncronos: webhooks. Os webhooks (gatilhos) podem ser configurados em nosso serviço, a fim de acionar um endereço especificado por você. Dessa forma, avisamos imediatamente quando um documento for processado, economizando tempo e recursos do seu sistema.
Ao integrar com a API da Focus NFe, você pode optar por utilizar Webhooks para receber notificações em tempo real sobre o status das suas notas fiscais. Utilizar webhooks em vez de realizar consultas frequentes (polling) traz diversas vantagens:
A API da Focus NFe mantém uma espécie de reputação dos seus servidores. Toda vez que acionamos o seu endpoint através de um webhook, medimos a velocidade de resposta dele. Se seu endpoint possui uma boa reputação, ou seja, se ele responde de maneira rápida e consistente, nossa API irá acionar os seus webhooks mais rapidamente.
Para uma experiência mais rápida e acionamento em tempo real de seus endpoints recomendamos que implemente seus endpoints para serem ágeis e confiáveis.
Se você deseja criar uma integração mais eficiente e responsiva, recomendamos fortemente o uso de webhooks. Além de simplificar o seu código, você garante uma experiência mais fluida para os seus usuários e evita problemas relacionados ao excesso de chamadas à API.
Caso a chamada ao seu endpoint falhe, tentaremos novamente em intervalos que ficam mais espaçados a cada tentativa. Após 48 horas de tentativas nossa API desiste e não tentará novamente, sendo necessário que se faça uma consulta ao documento fiscal para resgatar seu status.
Mesmo que ainda não esteja preparado para emitir um documento fiscal, é possível conferir se está apto a acionar a API Focus. Após completar o seu cadastro em nosso sistema, disponibilizamos um token que permitirá sua autenticação. Dessa forma, será possível realizar requisições simples, mesmo sem uma empresa cadastrada. Sugerimos que tente, por exemplo, utilizar nossas API acessórias. Um bom começo, é tentar consultar um CNPJ.