Especificação de devoluções

[mvallim]

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,

[ninrod]

Olá @mvallim

Como um documento está relacionado a uma devolução, quando temos multiplas devoluções?

No momento, na versão 1.2.0, um documento documento de cobrança está associado a um array de devoluções. O array pode ter 0..N devoluções. Ressalto que, no pix, você pode executar devoluções parciais.

Como funciona uma devolução para um documento com multiplos pagamentos? Isso pode ocorrer com QR Code Dinâmico Reutilizavel.

Excelente pergunta. Ficará mais claro na versão 2.0.0. Cada recebimento atrelado a um documento de cobrança possui um endToEndId distinto. Você comanda as devoluções, parciais ou não, em cima desses recebimentos. Então você teria um array de recebimentos e dentro de cada recebimento você teria um array de devoluções. Estou fechando isso ainda com a equipe, mas parece que não há como fugir muito desse design.

Porque o verbo PUT está sendo usado como criação de uma devolução?

Idempotência. Costuma ser polêmica essa questão:

Para realizar uma devolução, um identificador de devolução deve ser gerado. Se quem gerar o id for o PSP recebedor, não há idempotência e temos que usar POST. Se quem gerar o id for o usuário recebedor, então há idempotência e podemos usar o PUT.

Você poderia argumentar (e eu concordaria com você) que é uma "entortada" do conceito de PUT para poder "criar" um objeto do tipo /documento/{txid}/devolucao/{devolucaoId} passando diretamente o parâmetro devolucaoId criado pelo usuário recebedor na URL.

Por outro lado, existe um POST, na versão 1.2.0 da api, para a criação de QR Codes. Existe uma conversa no sentido de tornar essa funcionalidade idempotente e converter em um PUT no mesmos moldes do caso mencionado por você.

O argumento todo em volta da tal "idempotência" reside em você sempre poder saber qual foi o txid utilizado na "criação" de um recurso. Se você fizer a mesma chamada n vezes, com os mesmo argumentos, o resultado será sempre o mesmo e não há alteração de estado no servidor.

Por outro lado, ao se utilizar POST, no caso de um erro no servidor, pode-se chegar a um estado em que não se tem a certeza de que a chamada foi um sucesso. Foi ou não foi criado o documento de cobrança? Se foi, então qual foi o ID? Tem-se aí, uma complicação.

Enfim, como eu disse, é meio polêmica a questão.

Em tempo, sinta-se a vontade, por favor, para externar sua opinião @mvallim.

[felipecamargo]

@ninrod Boa tarde,

Ficará mais claro na versão 2.0.0. Cada recebimento atrelado a um documento de cobrança possui um endToEndId distinto. Você comanda as devoluções, parciais ou não, em cima desses recebimentos. Então você teria um array de recebimentos e dentro de cada recebimento você teria um array de devoluções. Estou fechando isso ainda com a equipe, mas parece que não há como fugir muito desse design.

Considerando este design, então futuramente uma devolução será feita em cima de um id de recebimento. exemplo: PUT /documento/{txid}/recebimento/{id_recebimento}/devolucao/{id_devolucao} Está prevendo também consulta em cima dos recebimentos? exemplos: GET /documento/{txid}/recebimento GET /documento/{txid}/recebimento/{id_recebimento}

Por outro lado, existe um POST, na versão 1.2.0 da api, para a criação de QR Codes. Existe uma conversa no sentido de tornar essa funcionalidade idempotente e converter em um PUT no mesmos moldes do caso mencionado por você.

com "criação de QR CODES" o que exatamente você quis dizer, seria o POST /documento sendo alterado para o PUT /documento/{txid}. A entidade documento pode ser utilizada para criação de QR Codes do tipo estático?

[ninrod]

Considerando este design, então futuramente uma devolução será feita em cima de um id de recebimento. exemplo: PUT /documento/{txid}/recebimento/{id_recebimento}/devolucao/{id_devolucao} Está prevendo também consulta em cima dos recebimentos? exemplos: GET /documento/{txid}/recebimento GET /documento/{txid}/recebimento/{id_recebimento}

Sim. está prevista a consulta em cima dos recebimentos. Ficará mais claro o design com a liberação da 2.0.0.

com "criação de QR CODES" o que exatamente você quis dizer, seria o POST /documento sendo alterado para o PUT /documento/{txid}.

Sim, o POST sai e entra o PUT /documento/{txid}.

A entidade documento pode ser utilizada para criação de QR Codes do tipo estático?

Não. O QR Estático pode ser criado diretamente (por exemplo, via notepad). Não depende da API. Pode ser conciliado via API porque consegue-se associar um txid a um QR Code estático.