bacen / pix-api

API Pix: a API do Arranjo de Pagamentos Instantâneos Brasileiro, Pix, criado pelo Banco Central do Brasil.
https://bacen.github.io/pix-api
2.38k stars 269 forks source link

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

Closed cbarril closed 3 years ago

cbarril commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

(...) 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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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 commented 3 years ago

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

exemplo removido, acredito que na 2.2.0.