Consulta e bloqueio de links de pagamento por API
A API permite consultar os links de pagamento gerados através do Pay by Link, verificar o seu estado e bloquear preventivamente links que ainda não tenham tentativas de pagamento associadas.
Estão disponíveis duas operações: pblLinksList_api (consulta) e pblLinkBlock_api (bloqueio).
1. Consulta de links — pblLinksList_api
Método: POST
Operação Cyclos: pblLinksList_api
Content-Type: application/jsonEsta operação permite consultar os links associados ao cliente autenticado, com filtros por encomenda/order id, datas de criação e estado de bloqueio.
Parâmetros de entrada
Parâmetro | Obrigatório | Descrição |
|---|---|---|
| Sim | Token de autenticação do cliente. |
| Sim | Identificador público do cliente. |
| Não | Filtrar pelo identificador da encomenda. |
| Não | Data inicial de criação do link (campo DATE do Cyclos). |
| Não | Data final de criação, inclusive (campo DATE do Cyclos). |
| Não |
|
| Não | Número da página. Por defeito: |
| Não | Número de resultados por página. Por defeito: |
Campos da resposta
Campo | Descrição |
|---|---|
| Indica se a consulta foi executada com sucesso. |
| Identificador público do cliente autenticado. |
| Página atual. |
| Lista de links encontrados. |
| Número total de links que correspondem aos filtros. |
| Número de links devolvidos nesta página. |
| Limite de resultados por página. |
Cada elemento de rows contém:
Campo | Descrição |
|---|---|
| Identificador único da raiz do link. |
| Identificador da encomenda. |
| Identificador público do cliente. |
| URL original de pagamento. |
| Valor do pagamento. |
| Moeda da operação. |
| Data e hora de criação. |
| Data da primeira abertura, quando existente. |
| Indica se o link é de utilização única. |
| Estado de pagamento registado. |
| Indica se o link está bloqueado. |
| Indica se o link está elegível para bloqueio. |
| Motivo da inelegibilidade, quando aplicável. |
| Número de registos da família do link, incluindo a raiz. |
Interpretação do bloqueio
blocked=falseecanBlock=true: link elegível para bloqueio.blocked=falseecanBlock=false: link não bloqueado, mas sem condições para bloqueio preventivo.blocked=trueecanBlock=false: link já bloqueado.
O filtro status=active identifica links não bloqueados, não garantindo que canBlock=true.
A simples abertura do formulário não impede o bloqueio, desde que não existam tentativas ou operações associadas.
2. Bloqueio de links — pblLinkBlock_api
Método: POST
Operação Cyclos: pblLinkBlock_api
Content-Type: application/jsonEsta operação permite bloquear preventivamente um link identificado pelo pblId, impedindo a sua utilização posterior.
Aplica-se a links de utilização única (OL=true) e reutilizáveis (OL=false).
Parâmetros de entrada
Parâmetro | Obrigatório | Descrição |
|---|---|---|
| Sim | Token de autenticação do cliente. |
| Sim | Identificador público do cliente proprietário do link. |
| Sim | Identificador único devolvido pela operação de consulta. |
| Não | Identificador da encomenda, para validação adicional. |
Campos da resposta
Campo | Descrição |
|---|---|
| Indica o sucesso da operação. |
| Identificador do link. |
| Resultado ou motivo da recusa. |
| Estado de bloqueio do link. |
| Indica se o estado foi alterado por este pedido. |
Possíveis motivos de inelegibilidade
| Descrição |
|---|---|
| O link já se encontra bloqueado. |
| Existem tentativas ou indícios de processamento associados. |
| Existe um pagamento concluído ou reconhecido como pago. |
| O link ultrapassou a data de expiração configurada. |
| O link não foi gerado através da API. |
| O registo não corresponde a um link individual elegível. |
| O link não existe ou não corresponde aos identificadores fornecidos. |
Quando o bloqueio não é autorizado, a operação devolve ok=false e o respetivo motivo.
3. Condições e segurança
As duas operações exigem lusopayToken válido e correspondência com o PID do cliente.
O bloqueio só é permitido quando não existem evidências de tentativas de pagamento ou processamento na família do link. A elegibilidade é novamente validada no momento da execução, mesmo que uma consulta anterior tenha devolvido canBlock=true.
O bloqueio é persistente, utiliza o estado url_bloqueado e não disponibiliza uma operação de reversão.
Recomenda-se consultar previamente o link através de pblLinksList_api e executar pblLinkBlock_api apenas quando canBlock=true.