[BUG] SDK functions `check` and `simulatePayment` require full Pix object instead of Pix ID

[Gustavonobregab]

Descrição do prblema

Ao utilizar as funções check e simulatePayment do SDK, ambas esperam receber o objeto Pix completo que foi retornado no momento da criação do Pix.

No entanto, ao usar a API HTTP diretamente, é possível consultar o status de um Pix apenas utilizando o seu ID (por exemplo: "pix_char_mbf45GExdwPnEFsazR4sfPru").

Comportamento esperado:
Deveria ser possível chamar check(pixId) e simulatePayment(pixId) passando somente o ID do Pix, já que a API já oferece suporte a esse comportamento.

Passos para reproduzir

Crie um Pix normalmente usando o SDK ou a API.

Tente utilizar a função check do SDK passando apenas o ID do Pix:
check("pix_char_mbf45GExdwPnEFsazR4sfPru");

Observe que o SDK lança um erro de tipo (TypeError) ou exige que o objeto completo do Pix seja passado.

Compare com a requisição via API REST, onde o status pode ser consultado apenas com o ID.

Comportamento esperado

As funções check e simulatePayment do SDK deveriam aceitar apenas o ID do Pix como parâmetro, assim como acontece na API HTTP.

Ou seja, seria esperado que o seguinte código funcionasse corretamente:
check("pix_char_mbf45GExdwPnEFsazR4sfPru");
simulatePayment("pix_char_mbf45GExdwPnEFsazR4sfPru");

Sem a necessidade de passar o objeto Pix completo.

Ambiente

No response

Logs relevantes

[rafaelcoelhox]

Note: I kindly request that all communication on this repository be in English to ensure that the discussions can be followed by our international community and contributors. Thank you for your understanding.

Thank you for reporting this issue. After analyzing the code and API documentation, I confirm that there is an inconsistency between the HTTP API and the SDK.

Problem

The check and simulatePayment functions in the SDK require the full Pix object, while the HTTP API allows operations with just the ID. This contradicts the SDK's own documentation and examples which show calls like simulatePayment('pix_char_abc12345678').

Solution

Implements the following improvements in the next version:

1. Modify the check and simulatePayment functions to accept either the ID or the complete object:

function check(idOrObject) {
  const pixId = typeof idOrObject === 'string' ? idOrObject : idOrObject.id;
  return api.get(`/pixQrCode/check/${pixId}`);
}

function simulatePayment(idOrObject) {
  const pixId = typeof idOrObject === 'string' ? idOrObject : idOrObject.id;
  return api.post(`/pixQrCode/simulate-payment`, { pixId });
}

2. Update the type definitions:

check(idOrObject: string | IPixQrCode): Promise<CreatePixQrCodeResponse>;
simulatePayment(idOrObject: string | IPixQrCode): Promise<CreatePixQrCodeResponse>;

3. Fix the IAbacatePay interface so that pixQrCode is defined as a service interface with methods, not as a data model.

These changes will maintain compatibility with existing code while introducing the simplified functionality you requested.

The fix will be included in the next release. Thank you for your contribution to improving the SDK user experience.

Seeking Approval

@ChristoPy I'd like to get your approval on this approach before proceeding with the implementation.

If anyone else from the team has input on this solution, especially regarding TypeScript typing or maintaining backward compatibility, please share your thoughts.

[ChristoPy]

@rafaelcoelhox I think passing the whole object is nice but a bit confusing?

If I was integrating I would think it needs the whole payment object which I may not have since we tend to store some kind of reference to the object (like its id) and not the whole object.

We could be more clearer by specifying which fields we want, in this case the id:

type OperationWithId = {
  id: string
}

function check(filter: OperationWithId) {
  return api.get(`/pixQrCode/check/${filter.id}`);
}

function simulatePayment(filter: OperationWithId) {
  return api.post(`/pixQrCode/simulate-payment`, { id });
}

With this approach, we can extend the SDK functionality to support operations with other kinds of parameters in the future, like:

type OperationWithId = {
  id?: string
  externalId?: string
}

function check(filter: OperationWithId) {
  return api.get(`/pixQrCode/check/${filter.id || filter.externalId}`);
}

function simulatePayment(filter: OperationWithId) {
  return api.post(`/pixQrCode/simulate-payment`, filter);
}

Since the API aims for forwards and backwards compatibility we can make this possible in the SDK as well and this can be done with the approach I mentioned