Balde de Fichas

Entenda o comportamento do endpoint de consulta de chaves no DICT

Esse endpoint de consulta de chaves [API Reference] adota um “sistema de baldes e fichas" em conformidade com o Manual Operacional do DICT (seção 13: “mecanismos de prevenção a ataques de leitura”).

O objetivo da política de baldes e fichas é garantir o uso adequado e equilibrado da API do DICT, evitando sobrecarga no sistema e protegendo a segurança e a privacidade das informações dos clientes bancários.

É importante que os parceiros respeitem as limitações impostas pelo Banco Central para evitar a interrupção da operação ou o cancelamento do acesso à API.

Esse mecanismo é utilizado para controlar o número de consultas que podem ser feitas em um determinado intervalo de tempo e funcionará da seguinte maneira:

• Cada parceiro possuirá um balde com uma quantidade específica de fichas que poderão ser usadas para consultar chaves Pix no DICT, com o objetivo de iniciar uma transação. O balde de fichas é individualizado por PayerID informado na consulta e segue os tamanhos definidos pelo Banco Central para Pessoa Física ou Pessoa Jurídica.
• Cada busca com sucesso ao DICT (código 200) consumirá 1 ficha, independente de haver um pagamento posterior.
• Cada consulta que resulte em pagamento com sucesso (Pix cash-out) passando o end-to-end da consulta da chave fará a reposição de 1 ficha.
• Múltiplas consultas da mesma chave com um único pagamento utilizando um end-to-end irá repor 1 ficha.
• Cada consulta de uma chave inválida (um CPF, CNPJ, telefone, e-mail ou chave aleatória não registrados como chave, por exemplo), que retorna um erro 404, consumirá 20 fichas.
• Caso seja realizado um pagamento sem consulta DICT (pagamento por meio de dados completos de instituição, agência e conta) não há consumo do balde de fichas.
• O balde de cada cliente terá uma taxa fixa de reposição por minuto definida pelo Banco Central, conforme regras do arranjo Pix.
• Quando o cliente entra em regra anti-scam da Celcoin passará a receber um retorno de erro 429, e esse retorno pode acontecer mesmo que o balde de fichas não esteja zerado, porque além da quantidade de fichas existe também o monitoramento qualitativo.
  Por exemplo, um cenário hipotético onde o cliente realize 300 consultas com sucesso e não efetive nenhum pagamento, deixa o cliente em uma relação de muitas consultas e nenhum pagamento, o que pode colocar o sistema em modo alerta, mesmo que o balde de fichas indique que ainda existem fichas disponíveis.

Desta forma, pedimos atenção ao número de consultas ao DICT que realizam, a fim de evitar qualquer tipo de transtorno.