Os dados do cartão de crédito se movem mais do que os dados da conta corrente: as linhas são reavaliadas à medida que a fatura se fecha, as parcelas são re-datadas para o ciclo ao qual pertencem e as compras pendentes são confirmadas. Esta página explica o que isso faz com os ids das transações e como reconciliar através disso.
O que identifica uma transação entre sincronizações#
Em cada sincronização, o Pluggy combina as transações que acabou de coletar com as que já armazenou, usando uma única chave:
- O próprio id da transação da instituição, quando a conexão fornece um.
- Caso contrário, um valor derivado da
description,amount,dateda transação e sua posição entre transações idênticas no mesmo dia.
A consequência é a parte importante:
| Resultado | O que você recebe | O id sobrevive? |
|---|---|---|
| A chave corresponde | transactions/updated | Sim — a transação armazenada é atualizada no local. |
| A chave não corresponde | transactions/deleted para a linha antiga, transactions/created para a nova | Não — a transação retorna com um novo id. |
Portanto, uma mudança na descrição, valor ou data de uma transação já armazenada é, por construção, uma transação diferente. É por isso que uma reavaliação em torno do fechamento de uma fatura pode chegar como uma exclusão seguida de uma criação, em vez de uma atualização.
Os ids não podem ser preservados, e nada vincula o id antigo ao novo
Não há opção de manter o id original em uma exclusão e recriação, e a carga útil de transactions/deleted carrega apenas os ids que foram removidos — nenhum campo aponta de uma transação excluída para sua substituição. Qualquer integração que trate o id do Pluggy como uma chave primária permanente para uma transação de cartão de crédito irá se desviar.
No que se ancorar em vez disso#
providerId — o próprio id da transação da instituição — é o único identificador estável do lado do provedor que o Pluggy expõe, e é retornado apenas para conectores de Open Finance. Em um conector direto, ele é sempre null, independentemente de qual seja a instituição.
Isso é importante quando a mesma instituição é acessível de ambas as maneiras. O Itaú, por exemplo, possui tanto conectores diretos quanto de Open Finance: um cartão conectado através do conector direto nunca carrega providerId, o mesmo cartão conectado através do Open Finance o faz.
Se você não tiver providerId, reconciliar com os atributos da transação — date + amount + description — conforme descrito em Transactions, e mantenha seu próprio mapeamento desses atributos para seu registro interno em vez de do id do Pluggy.
Veja Open Finance vs Direct: field differences para a lista completa de campos que apenas um tipo de conexão preenche.
Manipulação prática#
- Processar
transactions/deletedde forma idempotente. Uma transação pode desaparecer em uma sincronização e voltar em uma posterior, então uma exclusão não é necessariamente final. - Rebusque em vez de inferir. Após qualquer evento de transação, leia o estado atual com
GET /transactionsAPI para a conta afetada em vez de reconstruí-lo a partir do fluxo de eventos. - Espere que a janela da fatura seja ampla. Algumas instituições atribuem uma parcela a uma fatura meses antes da compra, então uma transação de cartão de crédito datada no futuro não é necessariamente um erro.
Se as transações desaparecerem e não voltarem
Se uma linha parou de ser retornada pela instituição ou foi descartada durante a sincronização não é algo que você pode distinguir apenas pela resposta da API. Abra um ticket de suporte com o itemId, a conta e as datas envolvidas, e podemos verificar a execução — veja Reporting issues.