Latência da API fiscal

O que compõe a latência de uma API fiscal?

A latência é a soma de várias etapas. Primeiro, a requisição viaja pela internet do sistema do cliente até a API. Depois, a API confere a autenticação, valida os dados enviados, monta o XML do documento e faz a assinatura digital. Por fim, a resposta volta pelo mesmo caminho.

Quando a API espera a resposta do órgão autorizador antes de responder, o tempo da SEFAZ ou do sistema da prefeitura também entra na conta. Essa parte não depende da API e pode variar bastante conforme o estado, o município, o horário e a estabilidade do autorizador naquele momento.

Por que a latência importa na emissão de notas?

O impacto depende do tipo de operação. No varejo, a NFC-e costuma ser emitida com o cliente esperando no caixa ou no checkout da loja virtual, então cada segundo a mais é percebido como lentidão no atendimento.

Já um ERP que emite NF-e de pedidos faturados ou um sistema que gera NFS-e no fechamento do mês tolera tempos maiores, desde que o processo seja confiável. Por isso, mais importante do que buscar a menor latência possível é saber quanto tempo esperar e preparar o sistema para lidar com variações.

Qual a diferença entre latência da API e tempo de autorização do documento?

A latência da API mede quanto tempo leva para a API responder a uma chamada. O tempo de autorização mede quanto leva até o documento ser aprovado ou rejeitado pelo órgão fiscal. Em integrações síncronas, os dois praticamente se confundem, porque a resposta só chega depois da autorização.

Em um fluxo assíncrono, a API responde rápido confirmando que recebeu o pedido e devolve um identificador. A autorização acontece em seguida, e o resultado chega por webhook ou é consultado por polling. Assim, a latência da chamada fica baixa mesmo quando o autorizador demora, e o sistema do cliente não fica travado esperando.

Como medir a latência da API fiscal?

O jeito mais simples é registrar no próprio sistema o horário de envio e o de recebimento da resposta de cada requisição. Esses dados, guardados em logs, permitem acompanhar a evolução ao longo do dia e identificar picos.

A média sozinha engana, porque algumas chamadas muito lentas ficam escondidas. É comum olhar percentis, como o p95 e o p99, que mostram o tempo dentro do qual ficam 95% e 99% das requisições. Ferramentas de observabilidade e rastreamento de requisições ajudam a descobrir em qual etapa o tempo está sendo gasto.

Como lidar com latência alta na integração fiscal?

Algumas práticas reduzem o tempo de cada chamada: reaproveitar conexões com keep-alive HTTP, evitar enviar dados desnecessários no payload e preferir o fluxo assíncrono quando o processo de negócio permitir.

Outras práticas protegem o sistema quando a lentidão vem de fora. Configurar um timeout adequado evita que o sistema espere indefinidamente. Fazer novas tentativas com backoff exponencial e chave de idempotência evita emitir a mesma nota duas vezes. E prever contingência ou fallback garante que a operação continue quando o autorizador estiver instável.

Exemplos de Latência da API fiscal

• Uma loja virtual percebe que o checkout fica lento no horário de pico e descobre, pelos logs, que a latência da API fiscal ao emitir NFC-e sobe junto com a instabilidade da SEFAZ do seu estado.
• Um ERP passa a usar o fluxo assíncrono: envia a NF-e, recebe o identificador em poucos instantes e libera o usuário, enquanto o status final chega depois por webhook.
• Uma plataforma de serviços monitora o p95 da latência na emissão de NFS-e por município e identifica quais prefeituras respondem mais devagar.
• A equipe técnica de uma transportadora ajusta o timeout das chamadas de emissão de CT-e para evitar que requisições lentas travem a fila de documentos.