Boas práticas na integração com a API Tomadas

Ao integrar sua aplicação com a API de tomadas, é importante seguir algumas boas práticas para garantir a segurança, eficiência e qualidade da integração. Neste documento, vamos abordar os principais aspectos a serem considerados.

Documentações de apoio:

• Como utilizar a API de Tomadas na prática
• Guia Geral API de Tomadas

1. Autenticação e Autorização

• A autenticação e autorização são cruciais para garantir o acesso seguro à API de tomadas. Siga estas recomendações:
  O método de autenticação utilizado para integrar às rotas da API é token_sh, obtido no cadastro do Tecno Account em: https://conta.tecnospeed.com.br/
• A maioria das prefeituras exigem o certificado digital para autenticação, portanto, será necessário cadastrar seu certificado antes de realizar as consultas. Caso o município tenha autenticação por Login e Senha será necessário que esses parâmetros sejam enviados na requisição dentro do grupo "autenticacao"  ao Adicionar uma consulta de notas.

2. Otimização de Desempenho

Para garantir um bom desempenho da sua aplicação, considere as seguintes práticas:

• Paginação: Utilize paginação quando necessário para obter maiores volumes de notas da API, na rota de consulta das notas por protocolo. Isso evita sobrecarregar a conexão e melhorar a experiência do usuário. O retorno será paginado a cada 100 registros, devendo utilizar o parâmetro de consulta "pagina", para avançar. Utilize a ação "proximaPagina" na resposta da requisição para facilitar a implementação, parando a iteração somente quando não mais encontrar a ação de "proximaPagina".
• Cache: Armazene em cache os dados que não mudam frequentemente, como configurações. Isso reduz o número de chamadas desnecessárias à API. Outro exemplo seria o caso em que a API retorna uma mensagem informando que não existem notas para um determinado período. Nesse caso, você pode armazenar essa informação em cache e exibi-la diretamente, sem a necessidade de fazer uma nova chamada à API dentro do tempo de no mínimo 1h.

3. Controle de consultas

3.1 Recomendação de Consulta D-1

Recomendamos que o período das consultas sejam realizadas sempre referente ao dia anterior. Isso evita que uma mesma data precise ser consultada várias vezes, o que é uma boa prática para evitar duplicidade de notas e, processamento de requisições de forma excessiva.

Por exemplo, a data atual é 10 de maio e você realizou uma consulta dessa mesma data às 13h00, recebendo 5 notas. Posteriormente, às 22h,  se o mesmo CNPJ tiver recebido mais notas, essa mesma consulta precisaria ser realizada novamente para obter as outras notas. No entanto, as 5 notas já retornadas anteriormente serão retornadas novamente pela prefeitura, devido à falta de controle de duplicidade por NSU.

Por esse motivo, recomendamos fortemente que a consulta do dia 10 de maio seja realizada apenas no dia 11, de forma que uma única consulta seja realizada, retornando todas as notas. Essa abordagem também é vantajosa para obter corretamente as notas canceladas.

3.2 Tempo mínimo para consultas 

A partir do momento que uma consulta é adicionada pela rota Adicionar consulta, aconselhamos que seja aguardado no mínimo 1h para ser feita a consulta por protocolo. Após receber sucesso na consulta de protocolo, será possível requisitar a rota para consultar todas as notas . Isso evita sobrecarregar a API com requisições consecutivas de um mesmo recurso. Vamos verificar alguns exemplos:

1. Às 14h, do dia 02/03/2024 ,estou adicionando uma consulta, para o período inicial 01/03/2024 e final 01/03/2024
   •  Esta rota me retornou um protocolo, com uma mensagem de "Nota(as) em processamento"
2. Às 15h, ou seja, 1h depois da adição da consulta, vou consultar a situação do protocolo

   • Existem apenas 3 situações possíveis para um protocolo, são elas:

     • PROCESSANDO -> Ainda não terminamos de processar sua solicitação, consulte novamente mais tarde. Aconselhamos que essa consulta seja feita novamente daqui 1h.
     • CONCLUIDO -> Finalizamos as consultas junto a prefeitura, podendo ou não retornar notas. Nesse status, já é possível chamar a rota para consultar todas as notas.
     • ERRO -> Ocorreu um erro ao tentar realizar a consulta junto a prefeitura. Nesse caso, já poderei adicionar a mesma consulta novamente pela rota Adicionar consulta. Quando eu receber erro, não preciso ficar consultando o protocolo novamente pois a situação 'ERRO' é uma situação final e o produto não realiza novas tentativas de consulta ao webservice nesta situação.

A partir do momento em que é adicionada uma consulta, nós já realizamos a busca no webservice da prefeitura. No entanto, em determinados casos, a prefeitura pode demorar para retornar, pode ocorrer falha na comunicação e, portanto, pode ser necessário realizar tentativas por nossa parte para consultar na prefeitura. Somente após essas tentativas, iremos tentar salvar essas notas em nossa base de dados.
Portanto, é aconselhado aguardar no mínimo 1 hora para conseguir de fato ter os retornos da prefeitura e poder consolidá-los em nossa base. Além disso, temos implementado um cache de 1 hora para a rota de adição de consulta. Isso significa que, se o protocolo estiver em processamento, não será possível adicionar a mesma consulta novamente durante esse período, evitando duplicidade de registros.

Seguindo estas boas práticas, você irá garantir o uso eficiente da API, evitando bloqueios ou sobrecargas na aplicação com requisições excessivas e consecutivas para os mesmos recursos, além de ter uma integração segura, eficiente e satisfatória da sua aplicação com a API de tomadas.