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

[Correção] Conflito de rotas/operações e ajuste de nomenclatura na Spec 2.1.2 #210

Closed filipehcds closed 3 years ago

filipehcds commented 3 years ago

Olá pessoal,

Gostaria de solicitar um ajuste na Spec 2.1.2 se possível, atualmente estamos tendo problemas em publicar todas as operações da Spec 2.1.2 no ar por conta de um conflito de rotas:

1º Correção

1º Conflito [Relacionado ao CobPayload] GET /{pixUrlAcessToken} [O problema está aqui, como essa operação recebe um pathParam, conflita com todas as rotas abaixo GET /cob GET /cobv GET /lotecobv GET /loc GET /pix GET /webhook

2º Conflito [Novamente relacionado ao CobPayload] GET /cobv/{pixUrlAcessToken} [O problema está aqui, como essa operação recebe um pathParam, conflita com a rota abaixo GET /cobv/{txid}

Como medida de contorno, tomei a liberdade de acrescentar "/public" antes das 2 operações por enquanto, até porque são 2 operações que serão publicas sem necessitar Oauth2/mTLS, então elas ficaram assim: GET public/{pixUrlAcessToken} [Pensando agora, talvez GET public/cob/{pixUrlAcessToken} faça mais sentido] GET public/cobv/{pixUrlAcessToken}

Mas é só uma sugestão, poderia ser qualquer outra coisa como por exemplo: GET jws/cob/{pixUrlAcessToken} GET jws/cobv/{pixUrlAcessToken}

O que vocês recomendam nessa caso?

2º Correção [Bem mais simples] Corrigir o PathParam de "pixUrlAcessToken" para "pixUrlAccessToken"

ninrod commented 3 years ago

1º Conflito [Relacionado ao CobPayload] GET /{pixUrlAcessToken} [O problema está aqui, como essa operação recebe um pathParam, conflita com todas as rotas abaixo

bom dia @filipehcds.

Qual é exatamente o conflito que você está vendo aqui? Veja que o endpoint /pixUrlAcessToken pode ser servido inclusive separadamente, em um servidor apartado do servidor que apresenta a API autenticada/autorizada.

filipehcds commented 3 years ago

bom dia @filipehcds.

Qual é exatamente o conflito que você está vendo aqui? Veja que o endpoint /pixUrlAcessToken pode ser servido inclusive separadamente, em um servidor apartado do servidor que apresenta a API autenticada/autorizada.

Bom dia @ninrod ,

Imagine o seguinte cenário: GET https://pix.example.com/api/v2/{pixUrlAcessToken} -> URL para recuperar o JWS GET https://pix.example.com/api/v2/cob -> URL para consultar lista de cobranças imediatas

Não é possível tecnicamente falando essas 2 URLs coexistirem no mesmo dominio, uma sobrepõe a outra, por esse motivo gostaria de sugerir a adição de algum recurso antes do pathParam "/{pixUrlAcessToken}", como por exemplo, "/jws/{pixUrlAcessToken}" ou algo do tipo, o mesmo acontece com o endpoint "/cobv/{pixUrlAcessToken}", entra no mesmo conflito de rota com o endpoint "GET /cobv/{txid}".

Faz sentido?

rubenskuhl commented 3 years ago

O que a documentação requer é que cada um deles tenham um v2, mas não que comecem do mesmo lugar. Poderia ser pix.example.com/jws/v2/{pixUrlAcessToken} e pix.example.com/api/v2/cob

ou mesmo jws-pix.example.com/v2/{pixUrlAcessToken} e api-pix.example.com/v2/cob

ninrod commented 3 years ago

@filipehcds , exatamente o que o @rubenskuhl pontuou.

filipehcds commented 3 years ago

O que a documentação requer é que cada um deles tenham um v2, mas não que comecem do mesmo lugar. Poderia ser pix.example.com/jws/v2/{pixUrlAcessToken} e pix.example.com/api/v2/cob

ou mesmo jws-pix.example.com/v2/{pixUrlAcessToken} e api-pix.example.com/v2/cob

Acho que não @rubenskuhl, tanto que não tive esse entendimento analisando a spec, analisando as 2 opções que você mencionou:

1 Opção: Acho que seria ruim porque teriamos que acrescentar 2 servidores diferentes na lista de servidores no OpenAPI, o primeiro para "pix.example.com/jws/v2/" e o segundo para "pix.example.com/api/v2", tanto para HML como PRD, o que ao meu só contribui pra prejudicar o entendimento do consumidor final 2 Opção: Acho que seria ruim porque o PSP precisaria comprar 2 certificados, até porque o certificado recomendado pelo Bacen não aceita wildcard e menciona que o ideal é possuir 1 unico host no CNAME, mesmo se fosse de graça, também existe todo um processo de configuração que em tese é desnecessário

"Acredito" (Opinião minha, posso estar errado) que o ideal era alterar o nome da operação e adicionar um /jws na Spec, ficando dessa forma:

GET /jws/cob/{pixUrlAcessToken} GET /jws/cobv/{pixUrlAcessToken}

Eu não gostaria de quebrar em 2 spescs exclusivamente por conta do nome do server e também não gostaria de deixar 4 endereços de server na lista, ficaria estranho e fora do usual visto no mercado:

servers:

Meio estranho isso.. o consumidor vai ter que adivinhar quais operações ele precisa chamar no /jws e quais no /api

Faz sentido? @rubenskuhl @ninrod

Caso não, tudo bem rsrs, podem encerrar a issue e eu me viro aqui de alguma forma, obrigado

rubenskuhl commented 3 years ago

Comunicação é um fenômeno onde tanto o que é escrito/falado quanto o que é entendido é importante, então pode ser que alguma reescrita da documentação possa deixar isso mais claro... imagino que o @ninrod e o @dmkamers acolheriam idéias de como deixar isso mais claro.

Porém, os consumidores dessas 2 famílias de endpoints são muito diferentes... na da API, são os correntistas do PSP recebedor. Há exigência de mTLS e OAuth para identificação mútua, há métodos para criar e gerir cobranças e Pixes.

No do JWS, os consumidores são os apps ou back-ends dos PSPs pagadores, que baixam o JWS para obter instruções adicionais no QR-Code dinâmico. Não há autenticação, nem pode ser exigida.

A única característica em comum dessas 2, que as distinguem das outras APIs do Pix como ICOM, ARQ e DICT, é que ambas são providas via Internet e não via RSFN. Minto: a outra característica é que são descritas pelo mesmo documento no GitHub... mas são funções distintas com públicos distintos.

rubenskuhl commented 3 years ago

Seguem alguns exemplos práticos de quem implementou no mesmo SNI e quem usou SNI diferentes:

Iugu: (aparentemente outro server name) qr.iugu.com/public/payload/v2/Psh1Md2trCYpJ3Z5204000053039865802BR5921

Gerencianet: (outro servername) qrcodes-pix.gerencianet.com.br/v2/232023aab07f40ec9a383e47792f73455204000053039865802BR5914

Santander: (mesmo server, URI path diferente) pix.santander.com.br/qr/v2/b29bd384-c7cc-4156-8cae-4935c

BB: (mesmo server, URI path diferente) (alerta: em inconformidade com a especificação) pix.bb.com.br/pix/1972fe07-9466-4d4f-a70d-73ae9cb

Inter: (server diferente) (alerta: em inconformidade com a especificação) spi-qrcode.bancointer.com.br/spi/1bbe1187c39a441481ba1de0f

BS2: (mesmo server, URI path diferente) (alerta: URL certa, mas o JSON tem outras inconformidades) api-pix.bancobs2.com.br/spi/v2/5776eff2-6ac3-40d1-9476-cd4e3bd

ninrod commented 3 years ago

@filipehcds

para o seu "consumidor final", o cliente que vai programar contra a sua API, não interessa o /pixUrlAccessToken e nem o /cobv/pixUrlAcessToken. Ninguém faz chamadas contra estes endpoints no contexto de programação contra a sua API.

Para o PSP pagador é que interessa.

Tudo que você tem que fazer é saber que os endpoints /pixUrlAcessToken e /cobv/pixUrlAcessToken serão expostos para o mundo e que, em tese, qualquer dispositivo poderá acessar essas URLs.

Nesse sentido, não há o menor problema em você definir dois servidores diferentes, um para cada caso. Isso é uma questão interna que você, como implementador, tem que avaliar: se deixa tudo em um mesmo servidor e separa por path ou se separa por domínio.

filipehcds commented 3 years ago

Entendi pessoal, agora ficou 100% claro, muito obrigado pelas informações @ninrod @rubenskuhl