"""
Módulo de métodos para operações de Solicitação de Confirmação de Recorrência (SolicRec) PIX.
Este módulo define a classe `SolicRecMethods`, que implementa métodos para criar, consultar e revisar
solicitações de confirmação de recorrência via API Pix. Deve ser herdada por classes que implementam
a interface de comunicação com bancos que suportam o recurso de SolicRec.
Requisitos:
- A classe base deve fornecer o método auxiliar `_request()`.
- Atributo `session` deve ser uma instância de requests.Session ou compatível.
Exemplo de uso:
class MeuBancoPixAPI(SolicRecMethods):
...
api = MeuBancoPixAPI(...)
resposta = api.criar_solicrec({...})
"""
from typing import Any
from pypix_api.models.enums import StatusSolicRec
[docs]
class SolicRecMethods: # pylint: disable=E1101
"""
Classe que implementa os métodos para operações de Solicitação de Confirmação de Recorrência PIX.
Esta classe deve ser herdada pela classe BankPixAPIBase.
"""
[docs]
def criar_solicrec(self, body: dict[str, Any]) -> dict[str, Any]:
"""
Cria uma solicitação de confirmação de recorrência (SolicRec) via API Pix.
Parâmetros:
body (dict): Dados da solicitação de confirmação de recorrência conforme especificação Pix.
Retorna:
dict: Dados da solicitação criada retornados pela API.
Exceções:
HTTPError: Em caso de erro na requisição HTTP.
Exemplo:
body = {
"calendario": {"expiracao": 3600},
"devedor": {"cpf": "12345678909", "nome": "Fulano"},
...
}
resposta = self.criar_solicrec(body)
"""
resp = self._request('POST', '/solicrec', json=body)
return self._json(resp)
[docs]
def consultar_solicrec(self, id_solic_rec: str) -> dict[str, Any]:
"""
Consulta uma solicitação de confirmação de recorrência (SolicRec) existente.
Parâmetros:
id_solic_rec (str): ID da solicitação de confirmação de recorrência.
Retorna:
dict: Dados da solicitação retornados pela API.
Exceções:
HTTPError: Em caso de erro na requisição HTTP.
Exemplo:
dados = self.consultar_solicrec("123e4567-e89b-12d3-a456-426614174000")
"""
resp = self._request('GET', f'/solicrec/{id_solic_rec}')
return self._json(resp)
[docs]
def revisar_solicrec(
self, id_solic_rec: str, body: dict[str, Any]
) -> dict[str, Any]:
"""
Revisa uma solicitação de confirmação de recorrência (SolicRec) existente.
Parâmetros:
id_solic_rec (str): ID da solicitação de confirmação de recorrência.
body (dict): Dados da revisão da solicitação conforme especificação Pix.
Retorna:
dict: Dados da solicitação atualizada retornados pela API.
Exceções:
HTTPError: Em caso de erro na requisição HTTP.
Observação:
O schema `SolicRecRevisada` aceita apenas o campo `status`, e o
único valor permitido é `CANCELADA`. `REJEITADA` é um status de
resposta, atribuído pelo PSP do pagador — nunca deve ser enviado.
Para cancelar, prefira `cancelar_solicrec`, que monta o corpo.
O cancelamento só é aceito enquanto o status da solicitação for
`CRIADA`, `ENVIADA` ou `RECEBIDA`; fora disso o PSP retorna 400.
Exemplo:
body = {"status": StatusSolicRec.CANCELADA.value}
resposta = self.revisar_solicrec("123e4567-e89b-12d3-a456-426614174000", body)
"""
resp = self._request('PATCH', f'/solicrec/{id_solic_rec}', json=body)
return self._json(resp)
[docs]
def cancelar_solicrec(self, id_solic_rec: str) -> dict[str, Any]:
"""
Cancela uma solicitação de confirmação de recorrência (SolicRec).
Atalho para `revisar_solicrec` com `{"status": "CANCELADA"}`.
Parâmetros:
id_solic_rec (str): ID da solicitação de confirmação de recorrência.
Retorna:
dict: Dados da solicitação cancelada retornados pela API.
Exceções:
HTTPError: Em caso de erro na requisição HTTP. O PSP retorna 400
quando o status da solicitação é diferente de `CRIADA`,
`ENVIADA` ou `RECEBIDA`.
"""
return self.revisar_solicrec(
id_solic_rec, {'status': StatusSolicRec.CANCELADA.value}
)