Pular para o conteúdo principal

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​

CotaGrátisFiscal IFiscal II
dfe-eventos1.00010.000100.000
cnpj-consultas50.000150.000500.000
cnpj-listagem03.00010.000
cep-consultas100.000200.000700.000

API de sandbox​

CotaGrátisFiscal IFiscal II
dfe-eventos1001.00010.000
cnpj-consultas100150200
cnpj-listagem0150200
cep-consultas100150200

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.

Todos os eventos em documentos fiscais são contabilizados na cota: não só pedidos de emissões como também cancelamentos, inutilizações, 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.

Os seguintes endpoints da API podem gerar consumo nesta cota:

NFS-e​

NF-e​

NFC-e​

MDF-e​

CT-e​

NFCom​

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:

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:

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:

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
}