Testar antes de codificar

É muito importante considerar a aplicação de testes de emissão antes de realizar qualquer procedimento de desenvolvimento ou implantação em seu sistema. Isso garante o entendimento no uso da API Focus, além de fornecer informações a respeito dos campos dos documentos fiscais. Além disso, a depender do modelo de documento ou resposta do sistema da Focus e/ou prefeitura, haverão retornos síncronos e assíncronos.
Nesse ponto, além de recomendar, nós possuímos uma coleção de requisições a partir da ferramenta POSTMAN. É um bom ponto de part ida para iniciar os seus testes.

Como usar a referência e boas práticas

As referências são uma forma de vincular as requisições do seu sistema à API da Focus. Elas estão presentes em praticamente todas as chamadas que seu sistema realiza, seja para enviar, consultar ou cancelar um documento.
Você e sua equipe terão liberdade para usar qualquer padrão para gerar essas referências, mas é importante lembrar que elas não podem se repetir em mais de um documento fiscal, mesmo que esteja tratando de outro tipo de nota.

Por exemplo, considere que esteja enviando uma NFC-e pela primeira vez à API. Nesse ponto, você estará realizando uma requisição HTTP com o método POST na seguinte URL de homologação:

https://homologacao.focusnfe.com.br/v2/nfce?ref=REFERENCIA

Note que a palavra “REFERENCIA” está atribuída a variável “ref” da URL. O texto “REFERENCIA” poderia ser substituído por “001”, “teste” ou qualquer outro texto.

Se em algum momento precisar consultar esse documento no futuro, o conteúdo do texto será usado para identificá-lo, como no exemplo abaixo:

https://homologacao.focusnfe.com.br/v2/nfce/REFERENCIA

Note que o parâmetro “ref” já não existe mais na consulta, e o texto anteriormente atribuído, agora se tornou parte do caminho da URL.

No envio de um documento, será possível utilizar a mesma referência quantas vezes seja necessário, mas somente até o documento ser autorizado. Em outras palavras, é possível reaproveitar e realizar reenvios do mesmo documento em caso de retornos com erro. Basta ajustar e reenviar.

No entanto, quando um determinado documento estiver autorizado, já não será mais possível usar a mesma referência em outro envio, mas apenas consultar aquele que está autorizado.

Por fim, como um padrão de qualidade ou sugestão de boas práticas, recomendamos que sua aplicação crie referências a partir da ID do banco de dados ou mesmo padrões de forma aleatória e não repetidos.

Delegar a atribuição de número às notas fiscais ou controlar em seu sistema

Sempre recomendamos que permita à API da Focus realizar o controle da numeração dos documentos fiscais, independente do modelo. Nosso sistema conta com mecanismos sofisticados e robustos para lidar com enfileiramento, reaproveitamento, contingências, inutilização e muitas outras rotinas que necessitam do controle do número do documento.

Apesar da nossa recomendação, permitimos que realize o controle da numeração e série dos seus documentos a partir do seu sistema, informando esses dados no payload de cada requisição. Para saber quais campos usar, recomendamos que utilize a documentação técnica.

Autenticação: usando o token global ou token por empresa

Quando realizar o cadastro na Focus NFe, você receberá acesso ao nosso Painel. Ele possui diversas rotinas, e permite consultar várias informações. Entre elas, estão os tokens das empresas.
Cada empresa cadastrada como emitente possui um par de tokens: um para homologação, e outro para o ambiente de produção.

No entanto, mesmo que não tenha cadastrado nenhuma empresa emitente, você perceberá que dentro do Painel existe uma área com um Token principal. Esse token é vinculado automaticamente em todas as empresas criadas dentro do seu acesso, seja por meio do Painel ou mesmo por API de empresas. Dessa forma, caso deseje, é possível utilizar esse token em qualquer CNPJ emitente para o ambiente de produção. Caso precise realizar testes em homologação, será necessário usar o token individual do emitente, presente dentro do cadastro da empresa.

Recomendamos nesse ponto que observe o seguinte fato:

As referências dos documentos (parâmetro REF) estão vinculadas ao token, ou seja, ao optar pela centralização das emissões no Token principal, você deverá cuidar para que não haja repetição das referências mesmo que esteja tratando de empresas diferentes.

Como tratar erros nas respostas da API

A maior parte dos tipos de documentos fiscais possuem processamento de envio assíncrono, ou seja, primeiro o documento é enviado ao órgão que realizará o processamento, seja Sefaz ou prefeitura, e depois ocorrerá a consulta. Em outras palavras, significa que você deverá enviar sua requisição, aguardar e depois consultá-la. A exceção é se estiver utilizando webhooks. Se for o caso, a API Focus notificará seu sistema acerca do processamento, sendo necessário apenas realizar o envio.

No entanto, não é sempre que um envio é realizado com sucesso. Algumas vezes, por preenchimento incorreto ou falta de informações, haverá a negativa da autorização, sendo necessário corrigir para reenviar.

Nesse ponto, é importante saber que podem existir dois tipos de resposta: erros de schema e erros provenientes da Sefaz ou prefeituras.

Caso esteja recebendo um erro de schema, provavelmente sua aplicação não considerou o padrão de campos necessários àquele documento ou, ainda, preencheu-os de maneira incorreta. Nesse caso, o retorno será realizado pela API Focus e será imediato, ou seja, de forma síncrona.

Para as demais mensagens, provenientes da Sefaz ou prefeituras, esse retorno ocorrerá de forma assíncrona porque dependem do processamento dessas instituições. Nesse caso, provavelmente, estamos falando do preenchimento do documento, mas com relação maior às regras fiscais e tributárias.