Entendendo os tipos de notas fiscais

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.

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.

Cuidados importantes na modelagem dos dados

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.

Empresas

O primeiro ponto a ser observado é com relação aos dados das empresas emitentes. 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:

id na Focus: id da empresa na Focus, para atualização de informações da empresa, certificado digital, próximo número e documentos habilitados.
token: token de acesso da empresa, para comunicação com a API da Focus. O token master também pode ser utilizado para este fim, neste caso esta informação não precisa ser armazenada.

Configuração de Impostos

É 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.

Dados das tentativas de emissão e documento fiscal emitido

Este ponto é muito importante. 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.

Decidindo o momento de enviar sua nota fiscal

1) Experimentando os recursos da API e modelando seu sistema:

Primeiro, é importante observar que os ambientes de teste e/ou homologação são disponibilizados pelas entidades do governo. Dessa forma, quando estamos testando possibilidades e o funcionamento do sistema, podemos obter a maior assertividade possível, sem a validade fiscal daquela emissão, ou seja, o comportamento esperado é igual ou muito próximo daquilo que ocorrerá no dia-a-dia.

No entanto, para que isso seja possível, a empresa emissora deverá estar preparada. Isso significa que os processos burocráticos junto ao governo devem estar resolvidos. Você deverá se certificar que a empresa esteja autorizada pelo governo a emitir o documento que pretende usar, mesmo no ambiente de testes.

A segunda parte desse processo é garantir que a empresa esteja devidamente cadastrada em nosso sistema, com o documento fiscal desejado habilitado, além do certificado digital (eCNPJ, modelo A1) vinculado.

Após as etapas acima estarem garantidas, será possível acionar a API a qualquer momento, mesmo que ainda não tenha modelado o seu sistema. Isso é possível por meio de ferramentas que possibilitem requisições HTTP, como exemplo o POSTMAN.

Sugerimos que aproveite o máximo possível o seu tempo de experimentação da API para testar o comportamento do sistema, modelar seus dados e observar o comportamento de emissão, consultas e cancelamentos das notas fiscais.

2) Direcionando o seu sistema para o modo de produção:

Embora ainda seja possível emitir documentos fiscais em produção a partir de ferramentas HTTP, esperamos que seu sistema esteja pronto quando chegar esse momento. Por isso, é importante aproveitar ao máximo a etapa anterior, a fim de garantir que todas as funções necessárias estejam implementadas para o uso cotidiano. Além de enviar documentos, o usuário espera que o seu sistema seja capaz de manejá-lo, ou seja, ele precisará consultar, cancelar, substituir e ajustar as notas fiscais.

Como não ser penalizado pelo rate-limit

Como ocorre em qualquer API, a Focus NFe possui um rate-limit, ou limite de consumo, de 100 requisições por minuto. 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. Porém algumas precauções são importantes para evitar o uso indevido da API.

• Utilize nossos web hooks: Com o uso de webhooks seu sistema não precisa consultar o processamento das suas notas fiscais. Nossa API, quando termina o processamento de um documento, irá disparar um webhook para seu sistema, informando do fim do processamento.
• Evite consultas em loop: As notas fiscais de natureza assíncrona (NFe, NFSe, etc) precisam de “um tempo” para serem processadas. As receitas podem levar até 5 minutos para autorizar uma nota e algumas prefeituras podem levar até vários minutos. Se o seu sistema, por algum motivo, não pode utilizar nossos webhooks, é importante tomar cuidado para que as consultas não sejam feitas de maneira descontrolada. Sugerimos que seu sistema dê um intervalo inicial antes de realizar a primeira consulta e aumente este intervalo para consultas subsequentes.
• Evite reconsultas: Uma vez recebido o retorno do processamento de um documento fiscal, é importante que seu sistema armazene as informações retornadas para evitar que sejam necessárias novas consultas para buscar informações da nota.
• Fique atento às mensagens de retorno: Muitas vezes percebemos sistemas tentando emitir a mesma nota repetidas vezes em sequência, mesmo recebendo alguma mensagem de erro. Se uma emissão deu uma mensagem de erro é importante que seu sistema a interprete e, sendo um erro definitivo, não tente emitir a mesma nota novamente sem que antes as suas informações sejam ajustadas.

Cuidados na emissão de documentos assíncronos

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.

Como testar o seu token e o acesso à API: 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.