Limites e cotas

A maioria das operações realizadas na API da Nuvem Fiscal incrementam o consumo de cotas específicas que possuem limites de uso. Os limites dependem do plano contratado na sua conta.

Limites por plano

A tabela a seguir mostra as cotas existentes na API e seus limites de uso em cada plano. A descrição do significado de cada cota é fornecida em seguida.

Os limites são mensais e referem-se ao mês corrente. No início de cada mês o consumo é reiniciado. Por exemplo, até 31 de janeiro de 2023 o consumo de sua cota foi 583. No dia 1 de fevereiro de 2023 o consumo dessa cota é reiniciado (zerado) e você pode utilizar todo o limite do seu plano para esse mês.

É importante ressaltar que, independente do plano, você pode cadastrar um número ilimitado de empresas, isto é, os seus clientes.

API de produção

Cota	Grátis	Fiscal I	Fiscal II
dfe-eventos	1.000	10.000	100.000
cnpj-consultas	50.000	150.000	500.000
cnpj-listagem	0	3.000	10.000
cep-consultas	100.000	200.000	700.000

API de sandbox

Cota	Grátis	Fiscal I	Fiscal II
dfe-eventos	100	1.000	10.000
cnpj-consultas	100	150	200
cnpj-listagem	0	150	200
cep-consultas	100	150	200

Cotas

A seguir informamos as cotas disponíveis e seus significados.

dfe-eventos

Essa cota é utilizada sempre que se realiza uma operação em um documento fiscal. Por exemplo, um pedido de emissão de nota fiscal de serviço utiliza essa cota.

O consumo é contabilizado por documento fiscal, não por chamada à API. Assim, um pedido de emissão em lote de 50 notas fiscais eletrônicas irá consumir 50 unidades dessa cota, mesmo que todas as notas estejam incluídas num único lote em uma única chamada à API. De forma análoga, um pedido de distribuição de documentos que retorne 50 notas fiscais eletrônicas (mesmo que de forma resumida) também irá consumir 50 unidades.

Todos os eventos em documentos fiscais são contabilizados na cota: não só pedidos de emissões como também cancelamentos, inutilizações, pedidos de distribuição, manifestações de destinatário, entre outros.

As operações em todos os tipos de documentos fiscais (NF-e, NFS-e, NFC-e, MDF-e, CT-e, NFCom) são contabilizados nessa mesma cota, dfe-eventos.

Uma operação em documento fiscal é contabilizada apenas quando encaminhada para comunicação com as APIs integradas (SEFAZ, Prefeituras, etc.), mesmo quando a operação falha. Por exemplo, se você solicitou uma emissão de NF-e e por algum motivo ela foi rejeitada pela SEFAZ, ainda assim ela é contabilizada no consumo da cota. Falhas ocorridas antes das requisições serem encaminhadas às APIs integradas não são contabilizadas. Por exemplo, JSON incorreto, validações que falham antes do encaminhamento, ou mesmo erros internos em nossos servidores.

Envios de e-mails são contabilizados apenas quando encaminhados para envio, mesmo quando não entregues. Por exemplo, ao enviar um email do XML e PDF de uma NF-e e ele não seja entregue pelo fato do endereço do email ser inexistente, caixa de entrada cheia, problemas ou indisponibilidade do provedor de email do destinatário ou por qualquer outra razão, ainda assim a cota será consumida.

Os seguintes endpoints da API podem gerar consumo nesta cota:

NF-e

• EmitirNfe
• EmitirLoteNfe
• CancelarNfe
• CriarCartaCorrecaoNfe
• InutilizarNumeracaoNfe
• Consultar contribuinte
• EnviarEmailNfe

NFC-e

• EmitirNfce
• EmitirLoteNfce
• CancelarNfce
• InutilizarNumeracaoNfce
• EnviarEmailNfce

Distribuicao NF-e

• GerarDistribuicaoNfe
• ManifestarNfe

NFS-e

• EmitirNfse
• EmitirLoteNfse
• CancelarNfse

MDF-e

• EmitirMdfe
• EmitirLoteMdfe
• CancelarMdfe
• EncerrarMdfe
• IncluirCondutorMdfe
• IncluirDfeMdfe

CT-e

• EmitirCte
• EmitirLoteCte
• CancelarCte
• CriarCartaCorrecaoCte
• InutilizarNumeracaoCte

NFCom

• EmitirNfcom
• CancelarNfcom
• InutilizarNumeracaoNfcom

Ainda, o download de documentos fiscais, como XML e DANFE (PDF), pode ser contabilizado na cota como uma operação fiscal. Portanto, você deve evitar o download excessivo desses arquivos para um mesmo documento fiscal.

Para clientes com plano de armazenamento de XML ativo, a franquia é de 5 (cinco) downloads por arquivo. Para clientes sem o plano de armazenamento de XML, a franquia é de 1 (um) download por arquivo.

Por exemplo, após a emissão de uma NFS-e (onde é contabilizada uma operação fiscal), você pode fazer o download do XML e do DANFSe (PDF) dessa nota, sem que essa operação contabilize uma operação fiscal adicional. Porém, se você tentar fazer pela segunda vez o download do XML e/ou do PDF, para essa mesma nota, será contabilizada uma operação fiscal por download. No caso de clientes com plano de armazenamento XML, pode-se fazer o download do XML e PDF de um mesmo documento fiscal até 5 vezes, sem que isso contabilize uma operação fiscal. A partir do sexto download, a operação será contabilizada.

cnpj-consultas

Essa cota é utilizada sempre que se realiza consulta dos dados de um CNPJ. Cada consulta é contabilizada no consumo da cota, ainda que o mesmo CNPJ já tenha sido consultado anteriormente, e mesmo que os dados do CNPJ não existam em nossa base de dados.

Os seguintes endpoints da API podem gerar consumo nesta cota:

• ConsultarCnpj

cnpj-listagem

Essa cota é utilizada sempre que se realiza uma consulta de estabelecimentos por CNAE. A quantidade de estabelecimentos retornada é contabilizada na cota, independente do número de chamadas na API. Por exemplo, se uma chamada na API retornou 30 estabelecimentos, o consumo de sua conta é incrementado em 30. Ainda, todo estabelecimento consultado é contabilizado, ainda que o mesmo estabelecimento já tenha sido consultado em uma chamada anterior à API.

Os seguintes endpoints da API podem gerar consumo nesta cota:

• ListarCnpj

cep-consultas

Essa cota é utilizada sempre que se realiza uma consulta de CEP. Cada consulta é contabilizada no consumo da cota, ainda que o mesmo CEP já tenha sido consultado anteriormente, ou mesmo que o CEP não exista.

Os seguintes endpoints da API podem gerar consumo nesta cota:

• ConsultarCep

Consulta do consumo

A informação do consumo das cotas é fornecida a você de diversas maneiras.

Cabeçalhos na resposta HTTP

Todos os endpoints que atualizam o consumo de alguma cota incluem na resposta HTTP os seguintes cabeçalhos:

• x-quota-name: Contém o nome da cota atualizada
• x-quota-used: Contém o consumo da cota no mês atual (após o processamento do endpoint)
• x-quota-limit: Contém o limite mensal de uso da cota

Por exemplo, após uma chamada a um endpoint de emissão de nota fiscal eletrônica, você pode receber os cabeçalhos a seguir:

x-quota-name: dfe-eventos
x-quota-used: 755
x-quota-limit: 1000

Consulta via API

A API oferece endpoints para a consulta do consumo das cotas. Para ter permissão a esses endpoints, o token utilizado precisa ter o scope conta.

Consumo de todas as cotas

O endpoint ListarCotasConta retorna o consumo e limite de todas as cotas existentes. Por exemplo, uma chamada à URL https://api.nuvemfiscal.com.br/conta/cotas retornaria uma resposta similar à seguinte:

{
    "data": [
        {
            "nome": "cep-consultas",
            "consumo": 5234,
            "limite": 200000
        },
        {
            "nome": "cnpj-consultas",
            "consumo": 8650,
            "limite": 50000
        },
        {
            "nome": "cnpj-listagem",
            "consumo": 0,
            "limite": 3000
        },
        {
            "nome": "dfe-eventos",
            "consumo": 985,
            "limite": 10000
        }
    ]
}

Consumo de uma cota

O endpoint ConsultarCotaConta permite consultar o consumo de uma cota específica. Por exemplo, uma chamada à URL https://api.nuvemfiscal.com.br/conta/cotas/dfe-eventos retornaria uma resposta similar à seguinte:

{
    "nome": "dfe-eventos",
    "consumo": 985,
    "limite": 10000
}

Limite de Requisições

Visão Geral

A API da Nuvem Fiscal possui um "rate limit" (limite de requisições permitidas em um intervalo de tempo) para cada endpoint. Esse limite é implementado para garantir a estabilidade e a performance da API, protegendo contra abusos e uso excessivo de recursos. Quando o limite é extrapolado, a API retorna o status code HTTP 429 (Too Many Requests).

Limites dos endpoints

Endpoints públicos

• Obtenção de token de acesso: 10 requisições por minuto.

Endpoints protegidos

• Requisições GET: 360 requisições por minuto.
• Demais requisições: 240 requisições por minuto.

Esses limites são aplicáveis globalmente a todos os endpoints protegidos da API. Caso não haja um valor explícito informado na referência da API para um endpoint específico, os limites acima serão os vigentes.

info

Se você acredita que está recebendo bloqueios indevidos ou se necessita aumentar a taxa de requisições para o seu IP, entre em contato com o suporte da Nuvem Fiscal.

Comportamento do HTTP 429

Quando o status code 429 é retornado, a resposta da API inclui os headers Retry-After e X-Retry-In, que indicam quanto tempo o cliente deve esperar até enviar a próxima requisição. Implementar corretamente o controle sobre esses retornos é essencial para evitar bloqueios temporários no acesso à API.

Headers na Resposta HTTP 429

• Retry-After: Este header indica o tempo, em segundos, que o cliente deve esperar antes de tentar enviar outra requisição. É uma forma mais direta de saber o tempo de espera.

• X-Retry-In: Este header fornece uma representação em string do tempo que o cliente deve aguardar antes de fazer uma nova tentativa.

Exemplo de Resposta HTTP 429

Abaixo está um exemplo de resposta que você pode receber ao extrapolar o limite de requisições:

HTTP/1.1 429 Too Many Requests
Retry-After: 2
X-Retry-In: 1.003928397s
Date: Fri, 24 May 2024 12:03:36 GMT
Content-Length: 17
Content-Type: text/plain; charset=utf-8

No exemplo acima, os valores dos headers Retry-After e X-Retry-In indicam que o cliente deve aguardar aproximadamente 2 segundos antes de tentar novamente, com X-Retry-In oferecendo uma precisão maior.

Evitando bloqueios

Para evitar o bloqueio temporário devido ao excesso de requisições 429, o cliente deve implementar um mecanismo de controle baseado nas informações retornadas pela API. Abaixo estão as etapas recomendadas para essa implementação:

1. Verificação do Status Code 429:

   • Sempre verifique o status code da resposta da API.
   • Se o status code for 429, siga para o próximo passo.

2. Leitura dos Headers Retry-After e X-Retry-In:

   • Extraia os valores dos headers Retry-After e X-Retry-In da resposta.
   • Esses valores indicam o tempo que você deve esperar antes de enviar uma nova requisição.

3. Implementação da Lógica de Espera:

   • Implemente uma lógica no seu código para aguardar o tempo especificado nos headers antes de tentar enviar a requisição novamente.
   • Utilize funções de espera ou temporizadores (e.g., sleep em Python, setTimeout em JavaScript).

4. Tratamento de Múltiplas Respostas 429:

   • Se múltiplas respostas 429 forem recebidas, aumente o tempo de espera exponencialmente para reduzir a taxa de requisições.
   • Considere utilizar um algoritmo de "backoff exponencial" para gerenciar o tempo de espera entre as requisições.

Exemplo de Código

Aqui está um exemplo de como implementar essa lógica em Python:

import requests
import time

def make_request(url, headers):
    while True:
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 1))
            retry_in = float(response.headers.get('X-Retry-In', retry_after))
            print(f"Limite de requisições excedido. Aguardando {retry_in} segundos antes de tentar novamente.")
            time.sleep(retry_in)
        else:
            return response

url = "https://api.nuvemfiscal.com/endpoint"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = make_request(url, headers)

print(response.status_code, response.json())