Balde de Fichas
Conhecer o funcionamento do Balde de Fichas para consultas de chaves no DICT é essencial para evitar interrupção nos serviços.
Glossário
DICT -> O Diretório de Identificadores de Contas Transacionais - é o serviço do arranjo Pix que permite buscar detalhes de contas transacionais com chaves de endereçamento mais convenientes para quem faz um pagamento. Entre os tipos de chave atualmente disponíveis estão CPF, CNPJ, telefone, e-mail e chave aleatória.
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 (definida pela Celcoin com base no seu histórico de uso) que poderão ser usadas para consultar chaves Pix no DICT, com o objetivo de iniciar uma transação.
- 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. O pagamento sem uso do end-to-end não irá repor a ficha consumida na consulta.
- 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) ou com má formatação do request (bad request), que retorna um erro 400 ou 404, consumirá 3 fichas.
- Ao realizar consultas sequenciais com o retorno 400 ou 404 que ultrapassam a somatória de 20 fichas consumidas, será ativado o antiscan e o consumo passará a ser de 20 fichas por consulta.
- 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 pela Celcoin com base no seu histórico de uso.
- Quando todas as fichas de um balde são usadas, o cliente ficará temporariamente impedido de consultar o DICT e irá receber um erro do tipo 429 (HTTP). A partir daí, será necessário esperar até que o balde esteja novamente positivo para que as consultas sejam reiniciadas.
Desta forma, pedimos atenção ao número de consultas ao DICT que realizam, a fim de evitar qualquer tipo de transtorno.
Updated 10 months ago