[Dúvida] no [QR Code] - Controle de versão QR dinâmico

[cbarril]

Com relação a documentação mais nova Manual de Padrões para Iniciação do Pix, do QR dinâmico, a URL deve seguir o seguinte formato: {fqdnPspReceiver} / {pixEndpoint} / {pixUrlAccessToken}

E o pixEndpoint está definido: {endpointOpcional} / {versãoAPIPix} / {fragmentoTipoCobrança} A documentação indica que versãoAPIPix é um dado obrigatório, mas atualmente existem QR Codes sem ele. Algum valor padrão é assumido na interpretação?

Por outro lado, entendo que a versão atual é / v2 / e corresponde à payload definida nesta documentação (versão atual 2.1). Agora, qual é a documentação final para / v1 /, se fosse necessário suportá-la? Lembrar mudanças no formato, como: "document.id", "calendar.recebivelAposVencimento", etc.

Finalmente, tenho mais uma consulta. Vemos que retiraram o campo "valor.permiteAlteracao". Isso nos permitiu o cenário onde o pagador pode escolher o valor a pagar (QR Code do valor em aberto). Como esse cenário pode ser resolvido agora?

[ninrod]

@cbarril , bom dia.

A documentação indica que versãoAPIPix é um dado obrigatório, mas atualmente existem QR Codes sem ele. Algum valor padrão é assumido na interpretação?

A documentação atual é bem recente, então acredito que não se deve rejeitar uma location que não apresente o v2, por hora. Esse fragamento que indica a versão da API será bastante útil futuramente para a convivência de várias versões da API.

Com a chegada da versão 2.2.0 e com sua obrigatoriedade estabelecida no começo de janeiro, pode-se pensar em rejeitar locations que não apresentem o v2 ou o v[n].

Agora, qual é a documentação final para / v1 /, se fosse necessário suportá-la? Lembrar mudanças no formato, como: "document.id", "calendar.recebivelAposVencimento", etc.

A documentação que deve ser observada é o manual 2.1 e a API Pix 2.1.0. Estamos em um período de adaptação, claro, porque a documentação é recente.Mas fora o eventual fragmento v2 faltando, o payload para cobranças imediatas deve ser o payload estabelecido pela versão 2.1.0 da API (compatível com o payload da 2.0.0, para cobranças imediatas).

Finalmente, tenho mais uma consulta. Vemos que retiraram o campo "valor.permiteAlteracao". Isso nos permitiu o cenário onde o pagador pode escolher o valor a pagar (QR Code do valor em aberto). Como esse cenário pode ser resolvido agora?

Veja que esse campo já não constava na API Pix 2.0.0.

Depende do caso de uso específico: Temos QR Estático, Reuso de Location ou alteração dos parâmetros da cobrança.

[VFernandezRojas]

@ninrod, boa tarde.

Com a chegada da versão 2.2.0 e com sua obrigatoriedade estabelecida no começo de janeiro, pode-se pensar em rejeitar locations que não apresentem o v2 ou o v[n].

Esse tema nos preocupou pois acreditamos que não será positivo para o ecossistema, dado que teremos a convivência de várias versões da API. Acreditamos que esse não é um bom caminho, pois nós e outras empresas já começamos a impressão e rollout dos QRs físicos que aceitam PIX. Falar que esses QRs não serão válidos ou serão rejeitados gera uma má experiência para os lojistas, que não vão entender o motivo da rejeição e podem pensar que o QR deixou de funcionar. Além disso, as trocas de QRs teriam que ser constantes. O que é que você acha disso?

Veja que esse campo já não constava na API Pix 2.0.0.

Por outro lado, com relação a esse dado, a gente usa os QR impressos, mas baseados numa URL para fazer a consulta dos dados da chave, etc. e em muitos cenários a gente retornava o valor 0, e permiteAlteracao true para que o PSP possa definir esse valor. Você acha que a gente poderia continuar com essa definição que se o PSP pagador recebe 0 permita definição do valor por parte do pagar (do mesmo modo que para QR estáticos)?

Att, Victor.

[ninrod]

Esse tema nos preocupou pois acreditamos que não será positivo para o ecossistema, dado que teremos a convivência de várias versões da API. Acreditamos que esse não é um bom caminho, pois nós e outras empresas já começamos a impressão e rollout dos QRs físicos que aceitam PIX. Falar que esses QRs não serão válidos ou serão rejeitados gera uma má experiência para os lojistas, que não vão entender o motivo da rejeição e podem pensar que o QR deixou de funcionar. Além disso, as trocas de QRs teriam que ser constantes. O que é que você acha disso?

Não se vislumbra, por agora, criar uma v3. Isso seria um evento realmente complicado. Mas por outro lado não podemos descartar essa possibilidade: por exemplo, a operação do Pix pode nos mostrar que a API atual teria que mudar de maneira incompatível e nesse caso, justamente para não quebrar os clientes que trabalham com a v2, o PSP recebedor teria que conversar nas duas versões da API. Apresentar essa "versão" de API e essa semântica, é uma prática normal para suavizar a transições incompatíveis entre versões. Dito isto, não pretendemos gerar versões incompatíveis, a não ser que seja estritamente necessário devido a um problema muito grave ou para abrigar uma feature super importante.

Por outro lado, com relação a esse dado, a gente usa os QR impressos, mas baseados numa URL para fazer a consulta dos dados da chave, etc. e em muitos cenários a gente retornava o valor 0, e permiteAlteracao true para que o PSP possa definir esse valor. Você acha que a gente poderia continuar com essa definição que se o PSP pagador recebe 0 permita definição do valor por parte do pagar (do mesmo modo que para QR estáticos)?

Obrigado pela contribuição. Tudo foi uma questão de timing. Podemos estabelecer que se não for apresentado o fragmento /v[n], então assume-se v2. E também normatizar que v1 e v2 são versões equivalentes. Acredito que isso resolve o problema.

[renatofrota]

(...) Podemos estabelecer que se não for apresentado o fragmento /v[n], então assume-se v2. (...)

Talvez estabelecer que assume-se a versão mais recente [compatível com o formato do QR lido]?

[VFernandezRojas]

Talvez estabelecer que assume-se a versão mais recente [compatível com o formato do QR lido]?

Eu pensei na alternativa de que o PSP pagador possa pedir por uma versão em particular usando um HTTP Header na chamada indicando qual versão da mensageria é requerida, o que é que vocês acham disso?

[ninrod]

@VFernandezRojas,

Eu pensei na alternativa de que o PSP pagador possa pedir por uma versão em particular usando um HTTP Header na chamada indicando qual versão da mensageria é requerida, o que é que vocês acham disso?

Mas aí tem a questão "this ship has sailed". O pagador tem que estar aderente ao padrão dia 16.nov.2020 para cobranças imediatas.

[VFernandezRojas]

@ninrod,

Com relação ao valor 0 e permiteAlteracao, o que é que você acha? podemos assumir que se o PSP pagador recebe 0 na resposta do QR dinâmico, deve pedir para o pagador inserir o valor dessa transação?

[ninrod]

@VFernandezRojas ,

O campo permiteAlteração não existe e não será aceito. Se este campo aparecer em alguma cobrança, é um erro e se for aceito é outro erro. Nem na 2.0.0 ele existia.

Para todos os efeitos, a API 2.1.X é a que vale para cobranças imediatas, para o go live.

Em tempo, essa questão do v1, v2 estamos analisando, mas o garantido é ficar com a v2.

[cryptographix]

@ninrod Infelizmente, no manual de iniciação 2.0 este campo existia, nas páginas 14 e 16, embora já estivesse removido do YAML.

Me parece que muitos desenvolvedores (nos inclusive) seguirem o manual e não o repositório, até porque não estava claro nas comunicações BACEN que o repositório era a referência definitiva (o "single source of truth".). A mesma questão vale para o "valor.final" que era obrigatório no referido manual e removido do YAML.

Como fica a questão do valor=0 no QR dinâmico? Pelo YAML é permitido (0.00) .. então podemos mesmo inferir que os PSP Pagador irão tratar isso como "valor definido pelo pagador"?

[ninrod]

@ninrod Infelizmente, no manual de iniciação 2.0 este campo existia, nas páginas 14 e 16, embora já estivesse removido do YAML.

Me parece que muitos desenvolvedores (nos inclusive) seguirem o manual e não o repositório, até porque não estava claro nas comunicações BACEN que o repositório era a referência definitiva (o "single source of truth".). A mesma questão vale para o "valor.final" que era obrigatório no referido manual e removido do YAML.

Perceba que na versão 2.0.0 estava especificado que esses campos estavam "em revisão" e que poderiam mudar.

Como fica a questão do valor=0 no QR dinâmico? Pelo YAML é permitido (0.00) .. então podemos mesmo inferir que os PSP Pagador irão tratar isso como "valor definido pelo pagador"?

Não existe valor definido pelo pagador no QR dinâmico.

[cryptographix]

Não existe valor definido pelo pagador no QR dinâmico.

Ok. Não encontrei esta definição na API ou no manual? Tem? Senão, talvez compense clarear a redação e incluir algo a respeito para evitar confusão com o estático sem valor definido, no qual "0" significa não informado.

Por exemplo, hoje na linha 1862 do YAML (valor do COB imediata) tem "Todos os campos que indicam valores monetários obedecem ao formato do ID 54 da especificação EMV/BR Code para QR Codes. O separador decimal é o caractere ponto. Não é aplicável utilizar separador de milhar. Exemplos de valores aderentes ao padrão: “0.00”, “1.00”, “123.99”, “123456789.23""

Isso leva a inferir que é válido o valor zero para este campo, mais ainda qdo se considera que este mesmo texto pode ser encontrado na página 17 do manual de iniciação 2.1, tbm exemplificando o valor 0.00 como válido.

Abraços

[ninrod]

Por exemplo, hoje na linha 1862 do YAML (valor do COB imediata) tem "Todos os campos que indicam valores monetários obedecem ao formato do ID 54 da especificação EMV/BR Code para QR Codes. O separador decimal é o caractere ponto. Não é aplicável utilizar separador de milhar. Exemplos de valores aderentes ao padrão: “0.00”, “1.00”, “123.99”, “123456789.23""

@SeanWykes , bem apontado. Vamos remover esse exemplo "0.00" na próxima versão.

[ninrod]

@SeanWykes , bem apontado. Vamos remover esse exemplo "0.00" na próxima versão.

exemplo removido, acredito que na 2.2.0.