bacen / pix-api-recebimentos Goto Github PK

Prezados,
As dúvidas abaixo se referem às seguintes versões das documentações:
API de Recebimentos: 1.2.0
https://github.com/bacen/pix-api-recebimentos

Manual de padrões para iniciação do Pix: 1.0
https://www.bcb.gov.br/content/estabilidadefinanceira/pix/Regulamento_Pix/II_ManualdePadroesparaIniciacaodoPix-versao1.pdf

Manual de segurança do Pix: 3.0
https://www.bcb.gov.br/content/estabilidadefinanceira/cedsfn/Manual%20de%20Seguranca%20do%20PIX%20v3.0.pdf

Dúvidas
Considerando o manual de iniciação do Pix, Pág. 12

e o endpoint POST /documento, como exemplo, da API de recebimentos

Pertunta-se:
1) Porque o campo versão não está presente na resposta às chamadas dos endpoints?

Considerando o manual de iniciação do Pix, Pág. 14

Pergunta-se:

2) Qual método da API preenche o campo calendario.apresentacao? Em que momento ele é obrigatório e é preenchido?

Considerando o manual de iniciação do Pix, Pág. 19

Pergunta-se:
3) A que método da API essa parte da documentação acredita estar chamando no HTTPS Request? Parece ser o método GET /documento/{txid}, mas esse método espera receber txid como parâmetro, e o que é passado acima parece ser o spiUrlToken 8b3da2f3-9a41-40d1-a91a-bd93113bd441. O formato da URL para Request, no exemplo, seria https://bx.com.br/pix/spiUrlToken/documento/{parâmetro}? Ou o spiUrlToken é que seria o identificador único do documento?

Considerando o método POST da API recebimentos:

Pergunta-se:

4) Do que se trata realmente o payloadURL retornado pelo POST /documento? Ele é o link de pagamento ou a URL do payload? “123” seria o spiUrlToken? O formato https://pix.example.com/qr/ do retorno da API, diferente do formato https://bx.com.br/pix/ do Manual de iniciação do Pix, me gerou essa dúvida da real intenção nesse retorno da API.

Também referente à API de recebimentos:
5) Quais endpoints devem ser expostos para outros PSPs?

6) As devoluções se referem apenas às devoluções de recebimentos feitos por QR code dinâmico. Certo?

7) Quando será lançada a nova versão da API de recebimentos?

8) Haverá algum marco homologatório para QR code dinâmico? A funcionalidade de QR code dinâmico ainda continua obrigatória para novembro? Há algum cronograma?

Conforme Manual de segurança, Pág 28:

Pergunta-se:
9) Qual o formato e layout desse arquivo? Minha dúvida é se será necessário ler todos os campos CN ou SAN dos certificados de todos os PSPs a cada leitura de QR code, a fim de validar a URL do site/domínio de QR Code dinâmico.

Segundo a documentação :

em 1.6.11. O campo 6: txid:

Em se tratando de pacs.008, o transactionID pode ser preenchido em razão de diversos fluxos. A seguir,
são listados os possíveis cenários de utilização do transactionID no Pix:
• QR Code dinâmico ou estático, via aplicativo: do ponto de vista do usuário recebedor, deve ser
provida pelo PSP do recebedor uma forma de se conciliar pagamentos de maneira manual, via
aplicativo. Nesse contexto, o transactionId pode ser escolhido pelo PSP do recebedor.
• QR Code estático ou URL criada pelo usuário recebedor: o QR Code estático, dotado de uma
estrutura simplificada, pode ser criado diretamente pelo usuário recebedor. Nesse contexto,
o recebedor escolherá, se for o caso, o seu próprio transactionId, o qual trafegará pelo SPI via
pacs.008.
• Inserção manual dos dados pelo usuário pagador: a transferência manual é iniciada pelo PSP
do pagador. O txid, portanto, nesse caso, é escolhido pelo usuário pagador.
• Chave Pix: a transferência com uso de chave é iniciada pelo PSP do pagador. O txid, portanto,
nesse caso, é escolhido pelo usuário pagador.
• QR Code dinâmico ou link, via API de recebimentos: no contexto da API de recebimentos, o
usuário recebedor, ao configurar o QR Code dinâmico ou o link, receberá um txid criado pelo
PSP do recebedor

Dado um cenário:

Loja X, que opera pelo PSP Y.

1. A Loja X cria um qr code dinâmico ou link, o PSP Y cria um txid, vamos chamar de "tx_id_created"
2. É completado todo fluxo de pagamento daquele qr code do passo #1
3. a Loja X quer receber um pagamento via chave PIX ou insersão manual de dados, e o usuário pagador decide inserir o mesmo txid, "tx_id_created"
4. Colisão PSP Y recebedor recebe esse segundo pagamento e como o txid da inserção manual é o mesmo criado com o qr code dinâmico ou link, há uma consiliação incorreta, associando o pagamento manual(3) com o pagamento/produto do criado com o qr code dinâmico ou link

Outras dúvidas:

1. O txid Irá mudar a cada mudança de dados/revisão do payload do qr_code??
2. Quais campos do payload são sensiveis a mudança de revisão?

A representação atual de campos numéricos reais / ponto flutuante, seja para valores financeiros ou para outras finalidades (como o campo juros), está no padrão \d{10}.\d{2} ou [0-9]{10}.[0-9]{2}.

Isso segue alguma normativa do BC, ou alguma outra regulamentação, ou foi acordado entre os PSPs, ou ainda está em aberto?

Digo isso porque acredito que a representação em centavos, diretamente como numérico inteiro e sem o digito separador ., é mais simples de ser convertida e manipulada durante todo o fluxo de troca, cálculo e armazenamento de informações.

Olá,

• Como um documento está relacionado a uma devolução, quando temos multiplas devoluções? spec
• Como funciona uma devolução para um documento com multiplos pagamentos? Isso pode ocorrer com QR Code Dinâmico Reutilizavel.
• Porque o verbo PUT está sendo usado como criação de uma devolução?

Obrigado,

Olá,

Se a consulta de um documento é pelo txId, como isso seria tratado quando os participantes indiretos e os clientes informam o mesmo txId.

Exemplo:

• joão cadastra txId = 1234
• maria cadastra txId = 1234

Quando os dois fazem a busca pelo documento usando o txId como é identidicado o txId de um ou do outro?

Olhando a spec não tem nenhuma outra informação que identifica unicamente um ou outro.

Tenho uma duvida referente a APIREC versus o TxID trafegado na PACS008.
No manual é citado que: "Inserção manual dos dados pelo usuário pagador: a transferência manual é iniciada pelo PSP do pagador. O txid, portanto, nesse caso, é escolhido pelo usuário pagador. "
Dado a informação acima, gostaria de apresentar o seguinte cenário.
O recebedor João emite um QR Code dinâmico com o txid - XPTO no banco X e o pagador Maria envia uma inserção manual através do banco Y para o Joao também com o txid XPTO.
No envio dessas informações entre os bancos os dados trafegados serão agencia, conta, valor e txid em ambas as situações. Ou seja, nessa situação como será validado que se trata de um QR Code ou de uma inserção manual?

Gostaria de saber quando serão utilizados os status "a_devolver", "completamente_devolvido", "parcialmente_devolvido". Pois eu imaginava que seriam utilizados da forma abaixo:

"a_devolver" => alguma devolução em andamento
"parcialmente_devolvido" => alguma devolução aprovada
"completamente_devolvido" => todas as devoluções aprovadas

Porém ao olhar os exemplos, existe um retorno de consulta onde haviam devoluções pendente e aprovada, porém o status continuava como "pago".

Gostaria de saber também se não teremos o status "negado" para uma devolução.

Segundo a documentação:

Respeitadas as regras de formação de URL, a URL terá esse layout:
fqdnPspRecebedor/spiEndpoint/spiUrlAccessToken/
O também é requisito UUID v4() no caso do uso de UUID.

No documento não está claro se o spiUrlAccessToken será único por revisão ou por documento, ou seja, terá uma URL única para para cada revisão.
Também não está claro se pode/deve ser usado o ID do documento/qr_code_payload no campo spiUrlAccessToken

Dúvidas:

1. A URL será a representação de um único documento, sempre retornando a versão mais recente do documento/payload_qr_code ou terá uma URL para cada revisão?(se sim deveriamos invalidar as URLs de revisões antigas certo?)

2. No caso da URL ser única por documento, teria algum problema em usar o ID do documento/qr_code_payload no campo spiUrlAccessToken ? Isso é indiferente e fica a cargo do PSP decidir?

3. Dado um request de link / qr code dinâmico:

HTTPS Request:
https://bx.com.br/pix/8b3da2f3-9a41-40d1-a91a-bd93113bd441
HTTPS Response:
JWSHeader.JWSPayload.JWSSignature

Qual será o mine type usado na resposta contendo o JWS? text/plain ou outro?

Ao importar o spec.yaml, percebi que a classe(ConfigApi) gerada apresentou problema quando tenta fazer um import
e referencias nos métodos. A versão usada foi a 1.2.0

import XXX.pix.qrcode.api.model.UNKNOWN_BASE_TYPE;

/**
 * Criar documento.
 *
 * Cria um novo payload JSON representando um QR/Link dinâmico.
 *
 */
@POST
@Path("/documento/")
@Consumes({ "application/json" })
@Produces({ "application/json" })
@ApiOperation(value = "Criar documento.", tags={  })
@ApiResponses(value = { 
    @ApiResponse(code = 201, message = "Documento gerado.", response = DocumentoGerado.class) })
public Response documentoPost(**UNKNOWN_BASE_TYPE** UNKNOWN_BASE_TYPE);

/**
* Alterar documento.
*
* Altera um payload JSON que representa um QR/Link dinâmico.
*
*/
@put
@path("/documento/{txid}")
@consumes({ "application/json" })
@produces({ "application/json" })
@ApiOperation(value = "Alterar documento.", tags={ })
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Documento alterado. O campo payloadURL é igual ao de criação. A revisão deve ser incrementada.", response = DocumentoGerado.class) })
public Response documentoTxidPut(@PathParam("txid") String txid, UNKNOWN_BASE_TYPE UNKNOWN_BASE_TYPE);

A API GET documentos, pelo que entendemos, retorna vários tipo de documentos (pagamentos, devoluções, QR-Codes). Acreditamos que essa consulta, principalmente para clientes com grandes movimentações (principalmente PJ), poderá ser bem dispendiosa para o PSP. Sugerimos uma consulta específica para cada tipo de documento. Concordamos também com consultas com paginação por cursor como outro colega sugeriu.

Não seria adequado utilizarmos para a API de Recuperar Lista de documentos, um modelo de paginação já bastante testado e robusto?

Conforme descrito no blog de engenharia do Twitter, eles apresentam problemas para montar timeline dos usuários e resolveram criando um modelo de listagem baseando em cursor ou em parâmetros (since_id e max_id).

https://developer.twitter.com/en/docs/tweets/timelines/guides/working-with-timelines
https://developer.twitter.com/en/docs/basics/cursoring

O modelo de cursor também é utilizado pelo Facebook.

https://developers.facebook.com/docs/graph-api/using-graph-api/#cursors

Cursor-based pagination is the most efficient method of paging and should always be used when possible. A cursor refers to a random string of characters which marks a specific item in a list of data. The cursor will always point to the item, however it will be invalidated if the item is deleted or removed. Therefore, your app shouldn't store cursors or assume that they will be valid in the future.

Esse artigo sumariza algumas das abordagens que considero comprovadamente efetivas de paginação

https://www.sitepoint.com/paginating-real-time-data-cursor-based-pagination/

Olá,

Lendo o Swagger com a definição da API de Recebimento, ficamos com uma dúvida:

• O campo pagador na rota "POST /document/" é mandatório ou não? A definição indica que caso o campo seja preenchido, os campos dos objetos PessoaFisica ou PessoaJuridica devem estar presentes. Porém não fica explícito se a presença em si desses objetos é obrigatória.

Obrigado.

Observando o Response do POST inicial, entendi que temos apenas um LINK "payloadURL" e não o QRCode TEXT padrão BRCode em sí. Como o lojista irá receber o QRCode e renderizá-lo para apresentação ao cliente pagador? Eles vão precisar montá-lo de acordo com o PAYLOAD da URL?

Outra pergunta, neste modelo, como faremos para iniciar vários pagamentos com um mesmo QRcode dinâmico conforme permitido na documentação abaixo?

https://www.bcb.gov.br/content/estabilidadefinanceira/pix/Regulamento_Pix/II_ManualdePadroesparaIniciacaodoPix-versao1.pdf
"Admite-se, a critério do recebedor, que uma mesma URL seja reutilizada para vários pagamentos. A
parte efetivamente dinâmica é o conteúdo acessado através da URL (o payload complementar, em
formato JSON). Dessa forma, um mesmo QR Code dinâmico poderia ser utilizado para iniciar vários
pagamentos com detalhes específicos diferentes, obtidos em diferentes acessos à mesma URL,
variando de acordo com determinada lógica de negócio"