search

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.32k stars 262 forks source link

Obrigatoriedade do fragmento da versão /v2/ na URL a partir de 16/11 #180

Closed monise closed 3 years ago

monise commented 3 years ago

Olá, boa tarde!

Referente ao Informe Pix - 070/202 divulgado ontem (13/11/2020 às 19:39h), gostaríamos de tirar uma dúvida.

Dúvida: É obrigatório que a URL do payload JSON contenha o fragmento da versão /v2/ na URL para obter o payload JSON de um QR code dinâmico já a partir de 16/11?

Pois entendemos que a versão de payload que entra em vigor a partir de 16/11 é a definida no manual 2.0.0 (_IIManualdePadroesparaIniciacaodoPix-versao2.0.pdf) onde não é mencionado essa alteração na URL. O fragmento /v2/ foi introduzido no manual 2.1.0 (II_ManualdePadroesparaIniciacaodoPix-versao2.1.pdf).

Segue abaixo reprodução do trecho do [Informe Pix - 070/2020] Geração e tratamento de QR Code dinâmico (e “Pix Copia e Cola”) para cobranças com pagamento imediato que parece indicar a obrigatoriedade do fragmento /v2/.

image

Porém, entendemos que pelo [Informe Pix - 065/2020] Divulgação da API Pix – Versão 2.1.0 publicado no dia 06/11/2020 as 18:53h, é mencionado que a versão 2.1.0 é compatível com a versão 2.0.0, prevendo inclusive a compatibilidade dos aplicativos, conforme o trecho abaixo:

image

Ou seja, o nosso entendimento é que a partir de 16/11 a existência do fragmento /v2/ não é obrigatória e que os aplicativos deverão conseguir obter o payload JSON mesmo que na URL não contenha o fragmento /v2/.

Obrigada

masyaf commented 3 years ago

@monise poderia compartilhar o link desse normativo?

monise commented 3 years ago

@masyaf o comunicado chegou por e-mail, não tenho o link da publicação. Mas segue abaixo um print:

image

ninrod commented 3 years ago

Dúvida: É obrigatório que a URL do payload JSON contenha o fragmento da versão /v2/ na URL para obter o payload JSON de um QR code dinâmico já a partir de 16/11?

Sim. Lembrando que não é obrigatório para o PSP recebedor disponibilizar a API, mas se disponibilizar, o v2 tem que estar lá.

Ou seja, o nosso entendimento é que a partir de 16/11 a existência do fragmento /v2/ não é obrigatória e que os aplicativos deverão conseguir obter o payload JSON mesmo que na URL não contenha o fragmento /v2/.

Ressalto que A API 2.0.0 estabelece a obrigatoriedade do fragmento "v1", o que não estaria errado, mas seria muito melhor que o n do v[n] acompanhasse o major version. O principal problema é que o fragmento v[n] não está sendo exibido por alguns PSPs.

Detectamos várias situações problemáticas distintas com PSPs exibindo APIs com payloads especificados antes da 2.0.0, com ou sem o v1, causando problemas para os PSPs pagadores. Para resolver definitivamente a questão, o Bacen tomou a decisão de exigir o v2, conforme estabelecido na 2.1.0, para que o PSP recebedor "marque" que está respeitando o payload 2.x.x. Novamente, não há prazo para que o PSP recebedor implemente sua API em produção.

Para o PSP pagador, continua igual: basta esperar que o payload recuperado no acesso à location obedeça a API 2.X.X. Se a location não apresentar o v2, é um indício de que o payload não deve estar aderente ao "branch" 2.x.x

monise commented 3 years ago

@ninrod Mas se não estivermos disponibilizando a API Pix e sim uma API proprietária usada para aplicativos, é errado gerar a URL sem o fragmento /v2/ ?

rubenskuhl commented 3 years ago

@ninrod Mas se não estivermos disponibilizando a API Pix e sim uma API proprietária usada para aplicativos, é errado gerar a URL sem o fragmento /v2/ ?

O problema é que a parte do payload é API pública usada pelos aplicativos dos outros PSPs. A necessidade de obediência estrita nessa é muito maior.

Já as demais, se usadas apenas pelo aplicativo do próprio PSP pagador, nem estão no escopo de especificação da API, como há nota de esclarecimento a respeito. Mas se a API é oferecida a correntistas, aí precisa seguir o padrão.

ninrod commented 3 years ago

@monise ,

Como o @rubenskuhl pontuou, é uma questão de interoperabilidade.

O elemento mais importante do QR dinâmico é o "location", a URL que será utilizada pelo PSP do pagador para recuperar o payload JSON. Duas coisas são muito importantes para o PSP do pagador no momento da obtenção da "location":

1) Ela tem que estar bem formada (fragmento de versão está presente? é uma cobrança imediata ou é uma cobrança com vencimento? essas duas informações constam diretamente na url 2) O payload recuperado respeita o schema definido no endpoint GET /pixUrlAcessToken?

Lembre-se de que a ideia aqui é que diferentes PSPs pagadores possam pagar o QR emitido pelo seu PSP, então esta semântica deve ser respeitada, caso contrário, não há como garantir interoperabilidade.

monise commented 3 years ago

@ninrod obrigada pelo retorno!! Eu entendo a questão da interoperabilidade, meu ponto era mais que a /v2/ foi divulgada na versão 2.1.0, ou seja, não constava na versão 2.0.0. E pelas divulgações a versão 2.0.0 poderia ser utilizada a partir de 16/11, ou seja, uma URL sem o /v2/ poderia ser aceita sim pelo pagador.

rubenskuhl commented 3 years ago

Em várias discussões aqui no GitHub a falta de versão foi citada como bug da versão 2.0.0, e inclusive estava prevista para mudar numa versão 2.0.1 que acabou não saindo. Então não ter os escopos adicionais da 2.1.x é uma coisa, não corrigir os problemas da 2.0.0 é outra.

ninrod commented 3 years ago

Eu entendo a questão da interoperabilidade, meu ponto era mais que a /v2/ foi divulgada na versão 2.1.0, ou seja, não constava na versão 2.0.0.

@monise , constava a versão v1. Acontece que PSPs não estão exibindo nem mesmo a v1. Há casos de PSPs exibindo a v1, mas payloads com schema anterior à versão 2.x.x. Então, para evitar confusão (v1 pode-se entender incorretamente que o v1 da 2.0.0 na verdade quer dizer um payload que respeita schema da 1.x.x), o Bacen resolveu tratar como bug exigir v2 para payloads 2.x.x.

renatofrota commented 3 years ago

Opinião de observador: o BACEN deveria ser mais claro nos comunicados. Seria muito mais fácil falar abertamente algo nesse sentido: "Erramos numa versão anterior da documentação e, para garantia da padronização a partir de agora, é exigido a presença do /v2/ na URL de recuperação dos payloads json, apesar e independentemente das informações contidas nos releases anteriores a este". Evitariam issues desse tipo.

rubenskuhl commented 3 years ago

image

BS2 emitiu esse QR-Code dinâmico, mas Gerencianet, Nubank e C6 recusaram.

rubenskuhl commented 3 years ago

O conteúdo é: 00020126990014BR.GOV.BCB.PIX2577api-pix.bancobs2.com.br/spi/v1/documento/e8915c1f-fc7b-432e-84b7-c6fb13c9c41552040000530398654031.05802BR5905CESAR6014BELO HORIZONTE62090505Teste63043A78

ninrod commented 3 years ago

a url está mal formada. não tem esse documento entre o v1 e o pixUrlAccessToken

ninrod commented 3 years ago

@rubenskuhl , vc consegue pagar via gerencianet?

rubenskuhl commented 3 years ago

@rubenskuhl , vc consegue pagar via gerencianet?

Esse QR-Code mal-formado não. Demais sim.

ninrod commented 3 years ago

Legal. No caso, o payload retornado também está mal formado, ou é só a URL mesmo?

rubenskuhl commented 3 years ago

Legal. No caso, o payload retornado também está mal formado, ou é só a URL mesmo?

Os 3 aplicativos mobile reclamaram, mas não sei se o critério deles foi só a URL ou havia mais alguma coisa errada.

guibranco commented 3 years ago

Boa tarde, iremos verificar! provavelmente é a URL mesmo.

pnegri commented 3 years ago

@guibranco Se puderem gerar um qr code e deixar na #188 agradeço. Sobre a questão do v2, não é apenas isto, os apps estão com problema para pagar e ler códigos qr dinâmicos que não foram gerados por eles.

guibranco commented 3 years ago

@pnegri sem problemas!

renatofrota commented 3 years ago

Dúvida: É obrigatório que a URL do payload JSON contenha o fragmento da versão /v2/ na URL para obter o payload JSON de um QR code dinâmico já a partir de 16/11?

Sim. Lembrando que não é obrigatório para o PSP recebedor disponibilizar a API, mas se disponibilizar, o v2 tem que estar lá.

@ninrod ,

Um esclarecimento, por gentileza:

O fragmento /v2/ é obrigatório nos locations de recuperação de payload JSON (interoperabilidade) [OK aqui].

E a URL da API (comunicação titular da conta transacional <-> PSP), tem alguma exigência quanto a existência de algum fragmento que indique a versão? E, se obrigatório, esta deve corresponder à major version da especificação do próprio BACEN ou representaria a versão da API do próprio PSP (que pode ser a "sua" v1, compatível à v2 do BACEN em vigor)?

ninrod commented 3 years ago

E a URL da API (comunicação titular da conta transacional <-> PSP), tem alguma exigência quanto a existência de algum fragmento que indique a versão? E, se obrigatório, esta deve corresponder à major version da especificação do próprio BACEN ou representaria a versão da API do próprio PSP (que pode ser a "sua" v1, compatível à v2 do BACEN em vigor)?

@renatofrota , boa tarde.

Segue o mesmo padrão.

A partir do fragmento /v2 começariam os endpoints "fechados".

Exemplo:

GET https://psp-recebedor-que-implementa-e-disponibiliza-a-api-pix.example.com/api/v2/pix

(retorna a lista de pix recebidos por este usuário recebedor, paginada).

Entendo que a versão do implementador constará em algum outro local, dashboard, ou algo assim. O Bacen não entrou neste detalhe.

rubenskuhl commented 3 years ago

E a URL da API (comunicação titular da conta transacional <-> PSP), tem alguma exigência quanto a existência de algum fragmento que indique a versão? E, se obrigatório, esta deve corresponder à major version da especificação do próprio BACEN ou representaria a versão da API do próprio PSP (que pode ser a "sua" v1, compatível à v2 do BACEN em vigor)?

@renatofrota , boa tarde.

Segue o mesmo padrão.

A partir do fragmento /v2 começariam os endpoints "fechados".

Exemplo:

GET https://psp-recebedor-que-implementa-e-disponibiliza-a-api-pix.example.com/api/v2/pix

(retorna a lista de pix recebidos por este usuário recebedor, paginada).

Entendo que a versão do implementador constará em algum outro local, dashboard, ou algo assim. O Bacen não entrou neste detalhe.

Este PSP poderia receber um alerta, pois não segue isso: https://devs.bs2.com/manual/pix-clientes/ (webhook também parece não estar por chave)

ninrod commented 3 years ago

@rubenskuhl , o caminho seria o DECEM ou um RDR ou os dois.