# Transação Recupere até 12 meses de dados de transações. Os dados das transações das contas fornecem insights sobre o comportamento financeiro do usuário. Essas transações são recuperadas para o produto **Account** ao sincronizar o **item** pela primeira vez e podem ser listadas para todos os tipos de conta `CREDIT` (cartões de crédito e empréstimos) ou `BANK` (conta corrente e poupança). Você pode revisar mais sobre como recuperar as transações no [Transactions endpoint](/reference/transactions-list-by-cursor). As transações são sempre recuperadas em páginas de 500, usando um mecanismo de paginação baseado em cursor. Para transações que estão disponíveis em faturas "Abertas" ou são parcelas futuras, o `status` as retornará como `PENDING`, uma vez que a transação ainda não impactou o saldo devedor. | Propriedade | Tipo | Descrição | Obrigatório | |-------------|------|-----------|-------------| | date | date | Data de postagem da transação, formatada em ISO8601 (horário UTC). Se for necessário interpretá-la como horário brasileiro, você precisará convertê-la para GMT-3. | Sim | | description | string | Descrição da transação, texto recuperado da instituição financeira. | Sim | | descriptionRaw | string | Se disponível, descrição bruta fornecida pela instituição financeira. | | | amount | number | Valor da transação. *Nota*: Para cartões de crédito, será positivo (débito) quando for uma despesa (acrescenta ao saldo), enquanto será negativo (crédito) quando a pessoa pagar a fatura. | Sim | | amountInAccountCurrency | number | Valor da transação na moeda da conta, se a transação for uma transação internacional. | | | balance | number | Saldo após a transação ser realizada. *Somente retornado para instituições financeiras suportadas.* | | | currencyCode | string | Código ISO da moeda da transação, ou seja, BRL, USD. | Sim | | category | string | null | Categoria das transações, fornecida pelo nosso Enrichment Categorizer. *Nota*: requer nível de assinatura **Pro**. | | | providerCode | string | Se disponível, código da transação do provedor. | | | status | string | Status da transação. *PENDING* ou **POSTED**. | Sim | | type | string | Tipo da transação. *DEBIT* (saída) ou **CREDIT** (entrada) | Sim | | paymentData | object | Dados relacionados ao pagamento/transferência. | | | creditCardMetadata | object | Dados relacionados a uma transação de cartão de crédito. | | | merchant | object | null | Dados relacionados ao comerciante associado à transação. *Nota*: requer recurso habilitado e nível de assinatura **Pro**. | | | operationType | string | null | Tipo de operação classificada pela instituição. Em Open Finance, o valor pode ser um dos seguintes: `TED` `DOC` `PIX` `TRANSFERENCIA_MESMA_INSTITUICAO` `BOLETO` `CONVENIO_ARRECADACAO` `PACOTE_TARIFA_SERVIÇOS` `TARIFA_SERVIÇOS_AVULSOS` `FOLHA_PAGAMENTO` `DEPOSITO` `SAQUE` `CARTAO` `ENCARGOS_JUROS_CHEQUE_ESPECIAL` `RENDIMENTO_APLIC_FINANCEIRA` `PORTABILIDADE_SALARIO` `RESGATE_APLIC_FINANCEIRA` `OPERACAO_CREDITO` `OUTROS` | | | providerId | string | null | Identificador do provedor para a transação. **Somente retornado para conectores Open Finance.** | | ```json { "total": 1, "totalPages": 1, "page": 1, "results": [ { "id": "6ec156fe-e8ac-4d9a-a4b3-7770529ab01c", "description": "Exemplo TED", "descriptionRaw": null, "currencyCode": "BRL", "amount": 1500, "date": "2021-04-12T00:00:00.000Z", "balance": 3500, "category": "Transferência", "categoryId": "05000000", "accountId": "03cc0eff-4ec5-495c-adb3-1ef9611624fc", "providerCode": "123456", "type": "CREDIT", "status": "POSTED", "paymentData": null, "creditCardMetadata": { "installmentNumber": 1, "totalInstallments": 6, "totalAmount": 9000 }, "merchant": null, "providerId": null } ] } ``` ### Convenção de Sinal para Transações de Cartão de Crédito Transações de cartão de crédito usam a seguinte convenção de sinal para refletir mudanças no saldo do cartão: - Valores positivos (+X) indicam débitos -- ou seja, novas cobranças que aumentam o saldo devedor (você deve mais). - Valores negativos (-X) indicam créditos/pagamentos -- ou seja, fundos que reduzem o saldo devedor. ```json // GET /transactions?from=2025-06-01&to=2025-06-30 [ { "id": "txn_001", "date": "2025-06-05", "description": "Supermercado", "amount": 75.00 }, { "id": "txn_002", "date": "2025-06-10", "description": "Pagamento de Fatura", "amount": -150.00 } ] ``` ## Esquema de Dados de Pagamento de Transação Algumas transações que são *Pagamentos* ou *Transferências* podem conter dados relacionados para entender de quem e para quem a operação foi feita, números de referência como Identificador PIX, a razão definida pelo usuário ou o método usado para realizar o movimento. | Propriedade | Descrição | |-------------|-----------| | payer | A identidade do remetente da transferência. | | receiver | A identidade do destinatário da transferência. | | referenceNumber | O identificador da transação que é fornecido pela instituição. | | receiverReferenceId | O identificador fornecido pelo destinatário para rastrear o pagamento. | | paymentMethod | O tipo de transferência utilizada "PIX", "TED", "DOC". | | reason | A descrição/motivo do pagamento do remetente. | | boletoMetadata | Informações do boleto associado ao pagamento. | ```json { "payer": { "name": "Tiago Rodrigues Santos", "branchNumber": "090", "accountNumber": "1234-5", "routingNumber": "001", "routingNumberISPB": "00000000", "documentNumber": { "type": "CPF", "value": "123.456.789-00" } }, "reason": "Taxa de serviço", "receiver": { "name": "Pluggy", "branchNumber": "999", "accountNumber": "9876-1", "routingNumber": "002", "routingNumberISPB": "27652684", "documentNumber": { "type": "CNPJ", "value": "08.050.608/0001-32" } }, "paymentMethod": "TED", "referenceNumber": "123456789", "receiverReferenceId": "company-reference-id" } ``` Cada participante do "PaymentData" terá referências à conta na qual a transferência foi originada ou recebida. | Propriedade | Descrição | |-------------|-----------| | name | Nome do participante (Pagador ou Recebedor) | | branchNumber | Número da agência | | accountNumber | Número da conta, com dígito verificador. | | routingNumber | Número de identificação do banco COMPE. A lista completa pode ser encontrada [aqui](https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf). | | routingNumberISPB | Número de identificação do banco ISPB. A lista completa pode ser encontrada [aqui](https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf). | | documentNumber | CPF ou CNPJ formatado do participante. | ## Metadados do Boleto Se a transação estiver relacionada a um Boleto, as seguintes informações serão retornadas no objeto `boletoMetadata` (veja [instituições suportadas](/docs/paymentdata-coverage)). | Propriedade | Descrição | |-------------|-----------| | digitableLine | Identificador do Boleto | | barcode | Número do código de barras do Boleto | | baseAmount | Valor original do Boleto sem considerar penalidades / juros / descontos | | interestAmount | Valor de juros do Boleto | | penaltyAmount | Valor de penalidade do Boleto | | discountAmount | Valor de desconto do Boleto | ```json { "payer": { "name": "Francisco Souza", "branchNumber": "1111", "accountNumber": "11111-7", "routingNumber": "341", "documentNumber": { "type": "CPF", "value": "111.111.111-11" }, "routingNumberISPB": "60701190" }, "receiver": { "name": "Pluggy Brasil Instituição de Pagamento LTDA", "documentNumber": { "type": "CNPJ", "value": "37.943.755/0001-30" } }, "paymentMethod": "BOLETO", "boletoMetadata": { "baseAmount": 1520, "digitableLine": "11190000111001113911100000021110600000000111000", "discountAmount": 0, "interestAmount": 10 }, "referenceNumber": "173631925" } ``` > **Dados de Pagamento & Dados de Pagamento de Boleto** estão disponíveis para nossos conectores diretos, consulte a [Página de Cobertura](/docs/paymentdata-coverage) para mais informações. ## Esquema de Metadados de Cartão de Crédito de Transação Transações associadas a cartões de crédito podem conter dados adicionais, como o total de parcelas, o número da parcela e o valor total (a soma de todas as parcelas). ```json { "installmentNumber": 1, "totalInstallments": 6, "totalAmount": 9000, "payeeMCC": 1234, "cardNumber": "1234", "billId": "03cc0eff-4ec5-495c-adb3-1ef9611624fc" } ``` | Propriedade | Descrição | |-------------|-----------| | installmentNumber | O número da parcela associada à transação. | | totalInstallments | O total de parcelas associadas à transação. | | totalAmount | O valor total (soma de todas as parcelas). *Somente disponível quando a compra foi feita em parcelas.* | | payeeMCC | Código de categoria do comerciante do recebedor | | purchaseDate | Data original da compra, para transações feitas com parcelas. | | cardNumber | O número do Cartão de Crédito associado à transação pode ser diferente da conta se for feito por um cartão adicional ou virtual. | | billId | Id da fatura associada à transação. *Somente disponível em conectores Open Finance* | ## Esquema de Comerciante de Transação Transações recuperadas podem conter informações extras sobre o comerciante/empresa associada à transação. Essas informações são o nome legal da empresa, número do CNPJ e a categoria associada aos comerciantes. ```json { "name": "Netflix", "businessName": "NETFLIX ENTRETENIMENTO BRASIL LTDA.", "cnpj": "00.000.000/0000-00", "cnae": "5911100", "category": "Streaming de Vídeo" } ``` | Propriedade | Descrição | |-------------|-----------| | name | Nome simples do comerciante. | | businessName | Nome legal registrado do comerciante. | | cnpj | Número do CNPJ associado ao comerciante. | | cnae | Número do CNAE associado ao comerciante. | | category | Categoria do comerciante. Fornecida pelo nosso Enrichment Categorizer. | > Veja [Transaction](/reference/transaction) em nossa referência de API para mais informações. ## Como sincronizar e mesclar transações *Pré-requisitos*: - Configure webhooks para `transactions/updated`, `transactions/deleted` e `transactions/created`. **Há algumas coisas a fazer:** - Receba o evento de webhook `transactions/created`, e usando a página `createdTransactionsLink`, recupere todas as transações disponíveis e insira-as em sua fonte de dados. ```json { "itemId": "de7bbf5a-abf2-47e4-94b1-586b36758423", "event": "transactions/created", "id": "de7bbf5a-abf2-47e4-94b1-586b36758423", "eventId": "4e69d62d-b7c8-4f01-b591-a1d8a94710b9", "accountId": "0d5a0de2-9c82-4ea2-af50-31643a632a33", "transactionsCreatedAtFrom": "2025-02-13T17:21:53.719Z", "createdTransactionsLink": "https://api.pluggy.ai/transactions?accountId=0d5a0de2-9c82-4ea2-af50-31643a632a33&createdAtFrom=2025-02-13T17:21:53.719Z" } ``` - Receba o evento de webhook `transactions/updated`, e usando a lista de IDs recebidos, você deve paginar o endpoint [/transactions](/reference/transaction/transactions-list) por uma lista de `ids`, atualizando seus dados com isso. ```json { "event": "transactions/updated", "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29", "itemId": "a5c763cb-0952-457b-9936-630f79c5b016", "accountId": "8a6e2c17-2817-40bb-b03d-546febc6a60a", "transactionIds": [ "5a14feae-eaa7-423a-820c-6b83837c35b7", "786c7d98-6085-4879-9c7f-2255260e2436" ] } ``` - Receba o webhook `transactions/deleted` e então exclua todas as transações que correspondem aos IDs especificados. O payload carrega **apenas os IDs das transações** (não o valor, data ou descrição excluídos). Trate as exclusões de forma idempotente: uma transação pode ocasionalmente desaparecer de uma sincronização e **reaparecer** em uma posterior, então um evento `deleted` não é necessariamente permanente. ```json { "event": "transactions/deleted", "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29", "itemId": "a5c763cb-0952-457b-9936-630f79c5b016", "accountId": "8a6e2c17-2817-40bb-b03d-546febc6a60a", "transactionIds": [ "5a14feae-eaa7-423a-820c-6b83837c35b7", "786c7d98-6085-4879-9c7f-2255260e2436" ] } ``` > **O Id da transação pode mudar — como reconciliar** > > Quando a Pluggy sincroniza transações com a instituição financeira, calculamos um hash que nos permite **manter o mesmo `id` da transação em sincronizações**. A maioria das mudanças — incluindo a transição de `PENDING` → `POSTED` — chega como uma **atualização** no local (`transactions/updated`) que **preserva o `id`**. > > Somente quando os dados mudam demais para confirmar que é a mesma transação — tipicamente `date`, `description` ou `amount` — é que excluímos a transação existente e criamos uma nova com um novo `id`. O payload **não** inclui um campo vinculando a transação excluída à sua substituição. > > Para reconciliar em uma exclusão/recriação, ancore em um identificador do lado do provedor: **`providerId`** (o id da transação do provedor, **somente retornado para conectores Open Finance**) ou **`providerCode`** (um código da instituição como um NSU; o formato varia por instituição). Para conectores diretos (não Open Finance), não há um identificador estável garantido, então combine com atributos (`date` + `amount` + `description`). > > **Reconectar uma conta** cria um **novo item**, cujas transações recebem **novos `id`s**; a Pluggy não desduplicará automaticamente transações entre itens. Reconciliar do seu lado usando `providerId` (Open Finance) mais atributos da transação. > **Recomendações** > > - Use um tamanho de página de 500 transações. (Desde 01/12/2025, este será o tamanho de página padrão ao recuperar transações). > - **500 é um máximo rígido, não um limite que é aplicado silenciosamente.** Um `pageSize` acima de 500 falha na validação e a API responde `400 Bad Request` -- não é *limitado* a 500. Para recuperar mais de 500 transações, mantenha `pageSize` em 500 ou abaixo e itere o parâmetro `page` até ter coberto `totalPages`. > - O mesmo teto se aplica ao filtrar pelo parâmetro `ids`: uma única resposta nunca retorna mais de 500 registros, então enviar mais de 500 ids em uma única solicitação não trará os extras de volta. Agrupe-os em grupos de 500. ## Saldo de Fim de Dia Às vezes, para casos de conciliação, você deseja obter o saldo de uma conta no final de um determinado dia (normalmente é o dia anterior). O campo usual de **saldo** da conta não resolverá essa necessidade, pois pode já ter sido afetado pelas transações de hoje. Nesses casos, você pode obter um saldo de fim de dia olhando para o **`balance` da última transação** dentro daquele dia. Em nosso endpoint de Transações, é a **primeira** mostrada para aquele dia: ```json { "total": 1, "totalPages": 1, "page": 1, "results": [ { "description": "Transação exemplo 4", "amount": -100, "date": "2024-10-04T18:00:00.000Z", "balance": 800 }, { "description": "Transação exemplo 3", "amount": -100, "date": "2024-10-04T10:00:00.000Z", "balance": 900 }, { "description": "Transação exemplo 2", "amount": -100, "date": "2024-10-03T18:00:00.000Z", "balance": 1000 }, { "description": "Transação exemplo 1", "amount": -100, "date": "2024-10-03T10:00:00.000Z", "balance": 1100 } ] } ``` Isso é suportado apenas pelos conectores Diretos da Pluggy (Itau PJ, Sicredi PF & PJ, Bradesco PJ). ### Caso Santander PJ Para esta instituição, sempre que possível, devemos confiar nos tipos de transação fornecidos pela Contamax para identificar e interpretar os movimentos da conta. Essas transações não aparecem todos os dias no extrato. Em geral, são registradas apenas em dias úteis. Mesmo assim, pode haver dias úteis em que nenhuma transação é mostrada, por exemplo, se não houver atividade durante o dia. No final de cada dia, apenas uma das duas operações pode ocorrer, dependendo do saldo da conta antes do fechamento diário: - Saldo final positivo (acima de zero): Uma aplicação automática de investimento é executada com o saldo disponível. - Saldo final negativo (abaixo de zero): Uma resgate automático é executado para cobrir o saldo negativo. Ambas as operações nunca aparecerão no mesmo dia -- apenas uma aplicação ou um resgate, de acordo com o saldo final da conta no final do dia. Nos casos em que essas transações aparecem no extrato, podem ser interpretadas como o resultado do saldo de fim de dia: - Uma aplicação indica que o saldo final do dia foi positivo. - Um resgate indica que o saldo final do dia foi negativo. ## Transações agregáveis do Itau PJ Dentro da instituição Itau PJ, existem certas transações *agregáveis* (tipos `SISPAG` e `PIX TRANSF`). Essas transações agregáveis podem vir em uma de duas formas: - Forma consolidada: muitas operações do mesmo tipo dentro do mesmo dia são representadas como uma única Transação - Forma detalhada: cada operação é representada como uma Transação separada Para nosso conector regulado do Itau PJ, elas sempre virão em forma detalhada. Para nosso conector direto do Itau PJ, dependerá da configuração da empresa conectada do Item. Para forçar a visualização detalhada, o usuário precisa acessar o Internet Banking e ir para `Contas a pagar > Manutenção > Alteração de serviço` e mudar todos os extratos para Detalhado. Isso requer um token de acesso para mudar, e um usuário com permissões suficientes. Se o Item tiver o produto Dados de Pagamento habilitado, nosso Conector Direto tentará desagregar transações SISPAG e PIX o máximo possível, mesmo que a empresa não tenha transações detalhadas habilitadas. No entanto, se você precisar de desagregação garantida, é recomendável usar o conector Regulamentado. # Itau PJ SISPAG Suportado Ao recuperar dados de pagamento para transferências SISPAG, existem certos subtipos específicos que nossa API manipula. Esses casos são: - SISPAG FORNECEDORES (Fornecedores) - SISPAG PIX - SISPAG CONCESSIONARIA (Companhia de Utilidade) - SISPAG MISMA TITULARIDADE (Mesma Titularidade) # Limitação de cobertura do Santander PJ Em contas empresariais do Santander, quando a conta é conectada através de um operador de conta, o histórico de transações disponível é limitado aos últimos 3 meses. Além disso, se um único dia contiver mais de 400 transações, apenas as primeiras 400 serão recuperadas -- quaisquer transações além desse limite não serão retornadas. Nesses casos, nossa recomendação geral é usar o conector regulamentado da instituição para evitar essa limitação.