Políticas operacionais

A plataforma FazNota aplica continuamente mecanismos de proteção operacional para preservar a estabilidade do serviço e proteger a infraestrutura compartilhada entre integradores. Esta página descreve essas políticas em termos práticos para integradores.

Proteção operacional

A plataforma realiza:

Monitoramento contínuo do consumo por credencial.
Controle de throughput automático para preservar a disponibilidade.
Detecção de padrões anômalos que possam indicar abuso ou erro de integração.
Limitação de uso quando aplicável.

Esses mecanismos atuam independentemente da contratação comercial — protegem todos os integradores ao garantir capacidade compartilhada.

Níveis progressivos de medida

Comportamentos identificados como anormais podem resultar em medidas progressivas:

Nível 1 — Restrição temporária de throughput

Redução automática da taxa de processamento das requisições da credencial envolvida. Manifesta-se como:

Respostas HTTP 429 Too Many Requests.
Header X-RateLimit-Remaining próximo de zero.
Retomada automática após a janela informada em X-RateLimit-Reset.

Ação do integrador: reduzir o ritmo de envio, aguardar o reset, revisar lógica que possa estar gerando consumo excessivo (loops, polling agressivo, retries sem backoff).

Nível 2 — Suspensão temporária

Suspensão da integração ou da credencial por um período determinado. Manifesta-se como:

Respostas HTTP 401 ou HTTP 403 em todas as requisições.
Comunicação do suporte indicando o período de suspensão.

Ação do integrador: entrar em contato com o suporte. Não tentar reenviar requisições durante o período de suspensão — apenas prolonga o problema.

Nível 3 — Bloqueio preventivo

Revogação da credencial e bloqueio da integração até análise. Manifesta-se como:

Token revogado permanentemente.
Suporte acionará a empresa para entender o cenário.

Ação do integrador: colaborar com a investigação do suporte. Após validação, um novo token pode ser emitido.

Comunicação prévia

Alterações relevantes que possam impactar integrações ativas serão comunicadas previamente, permitindo adaptação. Tipos de alteração que recebem aviso prévio:

Mudanças de limites operacionais com impacto perceptível.
Alterações estruturais em endpoints.
Depreciação de comportamentos legados.
Mudanças em formato de payload (com janela de retrocompatibilidade).

A comunicação será feita via:

E-mail aos contatos cadastrados na empresa.
Avisos no Painel FazNota.
Atualização desta documentação com seção de Changelog.

Boas práticas alinhadas com as políticas

Para evitar qualquer restrição:

Prática	Por quê
Sempre enviar `numero-origem`	Protege contra duplicidade em retries; reduz consumo
Polling com intervalo ≥ 2s e backoff	Evita pressionar a plataforma
Cache local de listagens	Reduz consumo desnecessário
Concorrência limitada por token	Distribui carga ao longo do tempo
Retry só em erros transitórios	Não amplifica falhas
Monitorar `X-RateLimit-Remaining`	Auto-regulação
Sincronização incremental	Não percorre histórico completo a toda hora

O que não fazer

❌ Anti-padrão	Por que é problemático
`setInterval` com poll de 1 segundo	Gera 60× mais requisições que o necessário
Retries em loop sem backoff em erro 4xx	Amplifica falhas, ativa proteções
Listagens sem paginação em volume grande	Consome janelas inteiras em poucas chamadas
Reprocessamento agressivo de toda a base	Use sincronização incremental
Múltiplas integrações concorrentes no mesmo token	Comparilhamento indevido; use tokens separados se possível

Em caso de suspeita de bloqueio

Verifique o status do health check: GET /health (não requer token).
Se a aplicação responde mas suas chamadas autenticadas falham com 401/403/429:
- Confira X-RateLimit-Remaining na resposta (mesmo com 429 vem).
- Verifique no Painel FazNota se o Token ainda está ativo.
Acione o suporte com:
- Token (ou pelo menos os primeiros 6 caracteres + os últimos 6 para identificação).
- Range horário do problema.
- Pelo menos um X-Request-Id recente de uma requisição falha.

Contato

📧 [email protected]
🌐 myse.com.br