Design de nova funcionalidade: Reuso de Location no QR Code Dinâmico

[HMPannuti]

No Manual de Padrões para Iniciação do Pix v 1.1, a nota de rodapé 30 informa que: "No Pix, como um mesmo BR Code dinâmico pode ser reutilizado para vários pagamentos, Valor e txId - obtidos via URL - podem mudar a cada transação. Assim, esses campos BR Code devem ser ignorados pelo pagador em qualquer caso de uso de QR Code dinâmico."

Porém, a v. 2 da API de Recebimento não permite ainda este funcionamento, já que não é possível associar uma nova cobrança (com novos valor e txid) a um Endpoint de acesso ao Payload JSON (campo "location") criado para outra cobrança. Certo?

Ou existe uma forma, com a versão atual da API de Recebimentos, de usar o mesmo BR Code Dinâmico para múltiplos pagamentos?

[ninrod]

@HMPannuti , essa nota de rodapé do manual acabou "passando". Na versão corrente da API Pix, não é possível implementar esse fluxo.

Por outro lado, sim, essa é uma possibilidade que estamos estudando para a próxima versão. A de tornar o "location" uma espécie de "vitrine" em que se possa mostrar diferentes cobranças, cada uma com seu txid, mas apenas uma de cada vez em função de configuração por parte do usuário recebedor.

Essa funcionalidade atenderia seu caso de uso específico? Pode falar mais sobre isso?

[HMPannuti]

@ninrod, sim, atenderia perfeitamente.

Isto seria utilizado, por exemplo, no caso de um lojista que não tem como exibir o QR-Code em tela ou em outro dispositivo, para o cliente pagador. Mas tem um volume de vendas grande, de modo que o QR-Code Estático impresso não o atende.

Neste caso, ele teria um QR-Code impresso previamente, que seria afixado ao lado do caixa, e seria utilizado para todos os pagamentos daquele caixa. Ou seja, a cada novo comprador da fila, o "location" seria atualizado, com os dados da nova compra (txid, valor etc).

[VFernandezRojas]

Concordo com o @HMPannuti, a gente tem o mesmo caso de uso aonde precisamos de um QR-Code impresso previamente associado ao caixa na loja (1 QR - 1 caixa), e por cada transação é atualizado. Um exemplo disso poderia ser uma fila em um fast food, ou um supermercado, aonde só uma pessoa pode pagar ao mesmo tempo, e talvez nem possua uma tela para apresentar o QR que muda por cada transação.

[franciscotfmc]

@HMPannuti pensando aqui em um outro caso de uso específico, que também se beneficiaria de um "update no location".

Em uma loja de departamentos, na qual existem, por exemplo, 100 produtos iguais com o mesmo QrCode Dinâmico impresso e colado numa etiqueta.

Se eu decidir alterar o valor do produto, não preciso imprimir novamente 100 etiquetas iguais. Faz sentido?

[ninrod]

@franciscotfmc , bem interessante o caso de uso.

Como vocês visualizam o funcionamento do "reuso de location", na API? Quais elementos a API teria que apresentar para atender a essa funcionalidade?

Exemplo:

-> PUT /loc/{idloc}: endpoint para "criar uma location sua": você "batizaria" uma location gerada pelo PSP. Por exemplo, caixa 01. A partir daí, o usuário recebedor está apto a controlar qual cobrança esta location batizada de "caixa01" apresenta.

O usuário recebedor poderia, a qualquer momento, especificar qual é a cobrança que estaria sendo apresentada via esse location. Inclusive poderia especificar que nenhuma cobrança deveria ser apresentada (o caixa 01 está vazio).

O que acham?

@franciscotfmc, @VFernandezRojas e @HMPannuti , ideias?

[franciscotfmc]

@ninrod interessante este endpoint, e me parece que, desde que ele consiga atualizar o payload de uma URL de um QR Code dinâmico, estaria sim atendendo ao caso de uso em discussão.

E neste momento é que me parece fazer sentido a semântica de nome do QR Code Dinâmico, pois fica claro pra mim onde está a possibilidade da "dinamicidade".

PS.: Talvez PATCH ao invés de PUT, para que o revision seja incrementado?

[ninrod]

@franciscotfmc ,

sim haveria um PATCH /cob/{txid} para alterar o location. DELETE /cob/{txid}/loc para desassociar um location de uma cobrança.

[franciscotfmc]

@ninrod ,

Apenas para complementar com mais um caso de uso que pode tirar proveito desse cenário.

Negócios que cobram por hora ou por algum intervalo de tempo bem definido, de forma que o valor do serviço ou produto vai aumentando com o passar do tempo.

Nesse contexto:

• O integrador poderia consumir o PATCH para incrementar o valor da cobrança com o passar do tempo;
• O pagador, de posse de um QR Code impresso em um ticket, por exemplo, efetua o pagamento antes de ir embora (já com o valor atualizado, de forma transparente);

Por último, gostaria de confirmar o entendimento com você de que, sem isso, o QR Code Dinâmico não é muito dinâmico. Ele simplesmente permite mais informações agregadas para a iniciação do pagamento.

Concorda?

[ninrod]

@franciscotfmc , boa noite.

Negócios que cobram por hora ou por algum intervalo de tempo bem definido, de forma que o valor do serviço ou produto vai aumentando com o passar do tempo. Nesse contexto: O integrador poderia consumir o PATCH para incrementar o valor da cobrança com o passar do tempo; O pagador, de posse de um QR Code impresso em um ticket, por exemplo, efetua o pagamento antes de ir embora (já com o valor atualizado, de forma transparente);

É interessante este caso de uso citado por você. Mas entendo que nesse caso específico a API atual já atende via PATCH /cob/{txid} passando { valor: { original: [novovalor] } } no request porque não é necessário alterar o location, apenas o valor da cobrança.

Por último, gostaria de confirmar o entendimento com você de que, sem isso, o QR Code Dinâmico não é muito dinâmico. Ele simplesmente permite mais informações agregadas para a iniciação do pagamento.

Concordo. Apenas ressaltando que mesmo sem a feature do "reuso do location", o QR Code Dinâmico, da forma como especificado no momento, já é bem "dinâmico" possibilitando essa alteração dos elementos da cobrança a critério do usuário recebedor.

[HMPannuti]

-> PUT /loc/{idloc}: endpoint para "criar uma location sua": você "batizaria" uma location gerada pelo PSP. Por exemplo, caixa 01. A partir daí, o usuário recebedor está apto a controlar qual cobrança esta location batizada de "caixa01" apresenta.

@ninrod , confirme o meu entendimento da sua solução proposta:

1 - PUT /loc/{idloc}: PSP retornaria uma location, e a associaria ao nome informado pelo usuário recebedor no campo idloc. Com isso, já seria possível, para o usuário recebedor, imprimir um QR-Code Dinâmico contendo a location infomada, e afixá-lo no seu PDV, por exemplo. Porém, neste momento, se um usuário pagador ler o QR-Code, o PSP recebedor retornaria erro, pois ainda não existe nenhuma cobrança associada àquela location.

2 - Ao criar uma cobrança (PUT ​/cob​/{txid}), seria possível informar o campo idloc, o que indicaria qual location que deseja-se associar àquela cobrança. Após criar a cobrança, se um usuário pagador ler o QR-Code, o PSP retorna o payload da desta cobrança criada.

3 - Caso seja feita a tentativa de criar uma cobrança informando um idloc para a qual existe associada uma cobrança com status 'ATIVA', essa chamada será negada. Para poder associar uma nova cobrança ao idloc, seria necessário que a cobrança anterior tivesse sido paga, e portanto estivesse com status 'CONCLUIDA'. Ou que o próprio usuário recebedor a removesse via PATCH ​/cob​/{txid}, alterando o status para REMOVIDA_PELO_USUARIO_RECEBEDOR

[ninrod]

bom dia @HMPannuti,

1 - PUT /loc/{idloc}: PSP retornaria uma location, e a associaria ao nome informado pelo usuário recebedor no campo idloc. Com isso, já seria possível, para o usuário recebedor, imprimir um QR-Code Dinâmico contendo a location infomada, e afixá-lo no seu PDV, por exemplo. Porém, neste momento, se um usuário pagador ler o QR-Code, o PSP recebedor retornaria erro, pois ainda não existe nenhuma cobrança associada àquela location.

Exatamente, perfeito. Pode ser exatamente isso que o usuário recebedor queira, por exemplo, quando ninguém estiver no PDV.

2 - Ao criar uma cobrança (PUT ​/cob​/{txid}), seria possível informar o campo idloc, o que indicaria qual location que deseja-se associar àquela cobrança. Após criar a cobrança, se um usuário pagador ler o QR-Code, o PSP retorna o payload da desta cobrança criada.

Perfeito. Especificamente, se o usuário pagador ler o QR Code afixado no PDV é isso que vai acontecer.

3 - Caso seja feita a tentativa de criar uma cobrança informando um idloc para a qual existe associada uma cobrança com status 'ATIVA', essa chamada será negada. Para poder associar uma nova cobrança ao idloc, seria necessário que a cobrança anterior tivesse sido paga, e portanto estivesse com status 'CONCLUIDA'.

É nessa linha. Estamos pensando em uma cardinalidade 1x1 entre cobrança e location, então para reaproveitar uma location, ela deveria ter sido desassociada da cobrança a que estava associada anteriormente, se for o caso.

Ou que o próprio usuário recebedor a removesse via PATCH ​/cob​/{txid}, alterando o status para REMOVIDA_PELO_USUARIO_RECEBEDOR

seria DELETE /cob/{txid}/loc. Ou, alternativamente, DELETE /loc/{idLoc}/txid

[ninrod]

resolvido na 2.1.0