Pular para o conteúdo principal

Consultas de chave Pix sem pagamento

Pelo Regulamento do Pix, a consulta de uma chave no DICT, o diretório de chaves do Banco Central, só pode ser feita para identificar o destinatário de um Pix que vai ser pago em seguida. Por isso, toda Verificação de Chave Pix precisa ser seguida de um pagamento para a chave consultada.

Para garantir isso, a Woovi acompanha as consultas que cada conta faz sem pagamento. Quando a conta chega ao limite, ela fica um dia sem poder consultar chaves.

Como funciona​

  • É por conta. Cada conta do modo BaaS tem o seu próprio limite: a conta vinculada à chave de API (AppID) que fez a consulta. Uma conta no limite não afeta as outras.
  • O limite é de 10 consultas sem pagamento. Não é por dia nem por mês: contam as consultas feitas sem que os pagamentos correspondentes tenham sido feitos.
  • Na 10ª consulta sem pagamento, a conta fica 24 horas sem poder consultar chaves.

O que conta como pagamento​

O pagamento por chave Pix criado com o pixKeyEndToEndId devolvido pela consulta. É esse identificador que liga a consulta ao pagamento no Banco Central. Veja Criar Pagamento.

cuidado

Transferência para agência e conta e pagamento de boleto não contam como pagamento da consulta. Se a consulta é usada só para conferir o destinatário e o pagamento sai por agência e conta, as consultas se acumulam até o limite.

Quando a consulta é bloqueada​

Durante as 24 horas, toda consulta de chave da conta responde 429:

{
"error": "Muitas consultas de chave Pix sem pagamento. Tente novamente amanhã."
}
  • Só a consulta de chave fica bloqueada (GET /api/v1/pix-keys/{pixKey}/check e POST /api/v1/pix-keys/check). A conta não é bloqueada: pagamentos, saques e cobranças seguem funcionando.
  • O bloqueio termina sozinho depois de 24 horas. Não é preciso pedir a liberação.
Dois tipos de 429

A consulta de chave tem outro limite, o Token Bucket, que pesa as consultas a chaves inexistentes e volta em cerca de 1 minuto. Para saber qual dos dois limites a conta atingiu, veja a mensagem:

  • Muitas consultas de chave Pix sem pagamento. Tente novamente amanhã.: limite de consultas sem pagamento, descrito nesta página. Dura 24 horas.
  • You tried to consult many Pix keys that do not exist. (errorCode: TOO_MANY_REQUESTS): token bucket. Aguarde o nextRefresh de GET /api/v1/pix-keys/tokens.

Validar os dados bancários sem pagar​

Se o objetivo for validar a conta de um cliente no cadastro, e não pagar em seguida, não use a consulta de chave. Use o envio de 1 centavo: ele é um pagamento de verdade, devolve o titular confirmado da conta de destino e funciona com chave Pix ou com agência e conta. Veja Validação de dados bancários.

Boas práticas​

  1. Consulte só quando houver um pagamento a fazer. Não use a consulta para validar cadastro, onboarding, KYC ou montar base de chaves.
  2. Guarde o pixKeyEndToEndId de cada consulta e envie no pagamento correspondente.
  3. Não repita a consulta da mesma chave antes de pagar: cada consulta conta.
  4. Trate o 429 pela mensagem. O limite de consultas sem pagamento não volta com retry: espere as 24 horas.
  5. Se o pagador desistir, não consulte a chave de novo automaticamente.

Prompt para IA​

Copie o trecho abaixo numa IA de coding (Claude / Cursor / Gemini / ChatGPT) pra tratar o limite de consultas sem pagamento no seu app:

Ajuste a integração com a API da Woovi para respeitar o limite de consultas de chave Pix sem pagamento nas contas do modo BaaS.

Regra: cada conta (a conta da chave de API que faz a chamada) pode fazer no máximo 10 consultas em GET /api/v1/pix-keys/{pixKey}/check ou POST /api/v1/pix-keys/check sem o pagamento correspondente. Na 10ª consulta sem pagamento, a conta recebe 429 em todas as consultas por 24 horas, com o corpo { "error": "Muitas consultas de chave Pix sem pagamento. Tente novamente amanhã." }. Transferência para agência e conta e boleto não contam como pagamento da consulta.

Requisitos:

  • Chame a consulta só quando houver um pagamento a ser feito para a chave. Nunca use para validar cadastro ou montar base de dados.
  • Guarde o pixKeyEndToEndId retornado pela consulta e envie no corpo da criação do pagamento (POST /api/v1/payment).
  • Não consulte a mesma chave de novo antes de pagar.
  • Diferencie os dois 429: com a mensagem Muitas consultas de chave Pix sem pagamento..., pare de consultar por 24 horas e não faça retry; com errorCode: TOO_MANY_REQUESTS, é o token bucket: espere o nextRefresh de GET /api/v1/pix-keys/tokens.
  • Para validar dados bancários sem pagamento, use o envio de 1 centavo descrito em https://developers.woovi.com/docs/flows/validate-bank-data-manual.