Atualizado em .
Limites por plano
O consumo da plataforma é organizado por cotas mensais. No início de cada mês, o consumo volta a zero e a nova franquia passa a valer integralmente para a conta.
quota_exceeded) até a recarga, upgrade ou reinício do ciclo.plan_upgrade_required.Franquia de homologação
Eventos emitidos em environment: "homologacao" não descontam da franquia de produção —
eles têm uma cota própria, separada, do mesmo jeito que a Nuvem Fiscal opera. Ao atingir o limite de
homologação do plano, a API responde 402 quota_exceeded apenas para escritas em
homologação; a franquia de produção continua intacta e as escritas em produção seguem liberadas
normalmente.
Avisos de uso
Em operações de escrita permitidas, a API devolve cabeçalhos de consumo para ajudar o integrador a avisar o cliente antes do bloqueio.
X-Fiscal-Plan: gratuito
X-Fiscal-Quota-Event-Used: 350
X-Fiscal-Quota-Event-Limit: 500
X-Fiscal-Quota-Event-Remaining: 150
X-Fiscal-Quota-Event-Usage: 70
X-Fiscal-Quota-Warning: attention
X-Fiscal-Sandbox-Quota-Event-Used: 40
X-Fiscal-Sandbox-Quota-Event-Limit: 100
X-Fiscal-Sandbox-Quota-Event-Remaining: 60
X-Fiscal-Sandbox-Quota-Event-Usage: 40noneattentioncriticalblockedRate limit de API
O rate limit não segmenta planos. Ele existe apenas como proteção da infraestrutura contra rajada anormal e tentativa de abuso. O que dimensiona o seu uso é a franquia mensal de eventos fiscais descrita acima — não um teto por minuto.
202 e o processamento
junto à SEFAZ/Prefeitura acontece de forma assíncrona, na fila. Rotas como criação de empresa, upload de
certificado, build, dispatch, cancelamento, correção e operações de webhook administrativo entram no
escopo pesado, e cada requisição consome apenas o escopo mais específico.
429, respeite o cabeçalho Retry-After e aplique backoff. Como as
rotas de escrita aceitam Idempotency-Key, reenviar após o backoff é seguro e não duplica
documento.
O que conta como evento fiscal na cota
Alinhado ao padrão de mercado (modelo Nuvem Fiscal), um evento fiscal é qualquer operação do ciclo de vida de um documento que demande comunicação direta e processamento com os órgãos governamentais (SEFAZ ou Prefeituras):
- Emissão de documento fiscal: Cada documento fiscal autorizado com sucesso (NF-e, NFS-e, NFC-e, CT-e, MDF-e).
- Rejeições oficiais do órgão emissor: Lotes de documentos submetidos à SEFAZ/Prefeitura com retorno de rejeição oficial decorrentes de erros de preenchimento ou regras fiscais do emitente (ex: Rejeições 539, 871, 733, etc.).
- Cancelamento de documento: Homologação de cancelamento de nota autorizada aceita pela SEFAZ.
- Carta de Correção Eletrônica (CC-e): Cada evento de correção de nota registrado e aceito pela SEFAZ.
- ❌ Erros de Validação Local (HTTP 422): Requisições com falha de validação prévia de schema que nem chegaram a ser enviadas ao órgão governamental.
- ❌ Erros Internos da Plataforma/Servidor (Exceções de Sistema): Falhas técnicas de infraestrutura da API ou indisponibilidade temporária de conectividade do nosso servidor.
- ❌ Consultas de Leitura e Status: Consultar o status da SEFAZ, consultar recibos ou realizar download de XML/PDF não consome a cota de eventos fiscais.
Política de inatividade e expurgo de contas (Plano Gratuito)
Para garantir a melhor performance da infraestrutura e otimizar recursos para todas as integrações ativas, adotamos uma política automática de suspensão e expurgo de contas sem uso exclusivo do plano Gratuito, em estrita consonância com a Cláusula 10.2 dos Termos de Uso e Seção 8 da Política de Privacidade:
- 30 dias sem uso: Notificação automática de inatividade enviada ao e-mail cadastrado alertando sobre a necessidade de movimentação ou backup de arquivos.
- 60 dias sem uso: As chaves de API são suspensas e a conta tem seus arquivos XMLs, PDFs e metadados expurgados e excluídos definitivamente dos servidores, cessando qualquer custódia técnica. Como a responsabilidade legal de guarda fiscal de 5 anos é do contribuinte emitente, o titular deve manter rotina própria de download e backup dos seus documentos.