Utils

Identificadores

Geração de identificadores da API Pix que possuem regra de formação semântica, onde um valor aleatório passa na validação de formato do schema e mesmo assim é recusado pelo PSP. Veja Pix Automático (Recorrência) para o contexto de uso.

pypix_api.utils.identificadores

Geração de identificadores da API Pix que possuem regra de formação semântica.

O idRec do Pix Automático não é um identificador livre: além de ter 29 caracteres alfanuméricos, ele codifica no próprio valor a política de retentativa, o ISPB do participante e a data de criação. Um valor aleatório passa na validação de formato do schema (pattern: [a-zA-Z0-9]{29}) e mesmo assim é recusado pelo PSP — daí a necessidade de um gerador.

Exemplo de uso:

from pypix_api.models.enums import PoliticaRetentativa from pypix_api.utils.identificadores import gerar_id_rec

id_rec = gerar_id_rec(‘12345678’, PoliticaRetentativa.PERMITE_3R_7D) # ‘RR12345678’ + data + sequencial

pypix_api.utils.identificadores.gerar_id_rec(ispb, politica_retentativa, data_criacao=None, sequencial=None)[source]

Gera um idRec válido para criação de recorrência (Pix Automático).

Monta o identificador conforme a regra de formação do schema RecId:

RAxxxxxxxxyyyyMMddkkkkkkkkkkk   (29 caracteres, case sensitive)

R           fixo, recorrência criada dentro do Pix
A           'R' permite retentativa pós-vencimento, 'N' não permite
xxxxxxxx    ISPB do participante (8 dígitos)
yyyyMMdd    data de criação da recorrência
kkkkkkkkkkk sequencial alfanumérico (11 caracteres)

O segundo caractere é derivado de politica_retentativa, garantindo que o identificador e o campo politicaRetentativa do corpo da recorrência não fiquem contraditórios — uma inconsistência que o schema não detecta.

Parameters:

  • ispb (str) – ISPB do participante direto/indireto ou os 8 primeiros dígitos do CNPJ do prestador de serviço de iniciação. 8 dígitos em [0-9].

  • politica_retentativa (PoliticaRetentativa | str) – Política de retentativa da recorrência. Aceita um membro de PoliticaRetentativa ou a string equivalente. Deve ser o mesmo valor enviado no corpo.

  • data_criacao (date | None) – Data de criação da recorrência. Padrão: data corrente.

  • sequencial (str | None) – Sequencial de 11 caracteres em [a-zA-Z0-9], único dentro da data de criação. Padrão: gerado aleatoriamente.

Returns:

identificador de 29 caracteres.

Return type:

str

Raises:

ValueError – Se o ISPB não tiver 8 dígitos em [0-9], se a política de retentativa for desconhecida ou se o sequencial informado não tiver 11 caracteres em [a-zA-Z0-9].

Nota:

O sequencial gerado automaticamente é aleatório (62^11 combinações), o que torna a colisão dentro de um mesmo dia improvável, mas não impossível. Quando houver controle transacional do lado da aplicação, informe sequencial explicitamente.

Demais utilitários

As outras funções auxiliares estão integradas às classes principais: