Pular para o conteúdo principal
Recursos para IAAbra o contexto completo da documentação em Markdown para ChatGPT, Claude, Cursor, Copilot e outros agentes.
Abrir contexto completo para LLMs

Limites e cotas

A ACBr API utiliza um modelo de consumo por franquia pré-paga. A maioria das operações realizadas na plataforma incrementa o consumo da cota prepago-creditos, de acordo com o tipo e a quantidade de operações processadas.

Regras de comercialização das cotas​

Ao contratar os planos do ACBR API você escolhe a franquia que se enquadra de acordo com sua demanda de emissões.

  • não há mensalidade;
  • as franquias podem ser adquiridas a qualquer momento;
  • os créditos da franquia são cumulativos entre as compras;
  • o consumo ocorre conforme o uso efetivo da API;
  • os créditos expiram em caso de inatividade de uso da API por 1 ano;
  • a resguarda automática de XML por 5 anos está inclusa nas operações com documentos fiscais;
  • o cadastro de empresas é ilimitado;
  • não há limite de CNPJs ou empresas cadastrados na conta;
  • existem franquias referenciais de 1.000, 2.000, 5.000, 10.000, 20.000 e 50.000 operações, além de planos customizados sob consulta.

As faixas comerciais e eventuais condições específicas de contratação podem ser consultadas em https://projetoacbr.com.br/api/#preco ou diretamente com o time comercial.

Cotas​

Atualmente, o consumo é contabilizado em uma única cota: prepago-creditos.

prepago-creditos​

Essa cota é utilizada para contabilizar o consumo das operações da API. O valor consumido depende do tipo de operação realizada.

Operações com documentos fiscais​

As operações com documentos fiscais consomem 1 crédito por documento fiscal processado.

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 créditos, mesmo que todas as notas estejam incluídas 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 créditos.

Todos os eventos em documentos fiscais são contabilizados nessa cota: não só pedidos de emissão, 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 contabilizadas na cota prepago-creditos.

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​

NFC-e​

Distribuicao NF-e​

NFS-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. A franquia gratuita é de 1 (um) download por arquivo.

Por exemplo, após a emissão de uma NFS-e (onde é contabilizado 1 crédito pela operação fiscal), você pode fazer o download do XML e do DANFSe (PDF) dessa nota, sem que essa operação contabilize um crédito adicional. Porém, se você tentar fazer pela segunda vez o download do XML e/ou do PDF, para essa mesma nota, será contabilizado 1 crédito por download.

Consulta de CNPJ​

As operações de consulta dos dados de um CNPJ consomem 0,1 crédito por consulta. 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:

Listagem de CNPJ por CNAE​

As operações de consulta de estabelecimentos por CNAE consomem 0,1 crédito por estabelecimento retornado. A quantidade de estabelecimentos retornada é contabilizada na cota, independentemente do número de chamadas na API. Por exemplo, se uma chamada na API retornou 30 estabelecimentos, o consumo de sua conta é incrementado em 3 créditos. 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:

Consulta de CEP​

As operações de consulta de CEP consomem 0,1 crédito por consulta. 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
  • x-quota-limit: Contém o limite 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: prepago-creditos
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://prod.acbr.api.br/conta/cotas retornaria uma resposta similar à seguinte:

{
    "data": [
        {
            "nome": "prepago-creditos",
            "consumo": 3585.4,
            "limite": 5000
        }
    ]
}

Consumo da cota pré-paga​

O endpoint ConsultarCotaPrePago permite consultar o resumo da cota de créditos pré-pagos. Por exemplo, uma chamada à URL https://prod.acbr.api.br/conta/cotas/prepago retornaria uma resposta similar à seguinte:

{
    "nome": "prepago-creditos",
    "consumo": 3585.4,
    "limite": 5000
}

Erro 402 - Payment Required​

Quando uma operação não puder ser concluída por falta de créditos disponíveis ou por ultrapassar o limite da cota, a API retornará o status code HTTP 402.

402 por falta de créditos​

Quando não houver créditos suficientes para processar a operação, a API retornará:

HTTP/1.1 402 Payment Required

Código de erro:

  • InsufficientCredits

Mensagem:

  • Créditos insuficientes para concluir a operação. Adquira uma nova franquia para continuar.

Para continuar processando novas operações, é necessário adquirir novos créditos na sua conta em console.acbr.api.br.

402 por limite da cota excedido​

Quando a requisição ultrapassar o limite permitido para a cota, a API retornará:

HTTP/1.1 402 Payment Required

Código de erro:

  • QuotaExceeded

Mensagem:

  • A requisição ultrapassa o limite de {limite} operações para a cota "{nome-da-cota}".
info

Se o seu sistema tratava essas situações como 403, atualize a integração para considerar 402 nos cenários relacionados a créditos insuficientes e extrapolação de cota.

Limite de Requisições​

Visão Geral​

A API da ACBr API 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​

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 ACBr API.

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://prod.acbr.api.br/endpoint"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = make_request(url, headers)

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