# Obter saldos e transações do ledger Neste tutorial, você usará duas operações da API de ledger para monitorar o saldo da sua conta e obter um registro detalhado da atividade na sua conta pré-financiada: 1. **Get available balances** — recupera os saldos disponível e reservado atuais da sua conta. 2. **Get ledger transactions** — recupera uma lista paginada de transações do ledger dentro de um intervalo de data e hora para conciliação. Você também aprenderá a: - Paginar grandes conjuntos de resultados usando paginação por offset. - Filtrar por ID de pagamento para localizar todos os lançamentos de ledger associados a um pagamento específico. - Exportar resultados em CSV para usar em fluxos de conciliação. Para entender como as operações de ledger (RESERVE, DEBIT, CREDIT, RELEASE) afetam o seu saldo, consulte [Transações do ledger](/pt-br/products/payments-direct-2/introduction/concepts/ledger-transactions). ## Antes de começar Para seguir este tutorial, você precisa de: - Acesso ao ambiente UAT da API do Payments Direct. - Um token de acesso OAuth2 válido. Consulte [Solicitar um token de acesso](/pt-br/products/payments-direct-2/api-docs/developer-guides/request-an-access-token). - Pelo menos um pagamento concluído ou em andamento (para observar lançamentos de ledger relevantes). ## Etapa 1: Obter os saldos disponíveis Use a operação **Get available balances** para ver quanto está disponível no momento na sua conta pré-financiada e quanto está reservado para pagamentos em andamento. ### Endpoint `GET /v2/balances` ### Parâmetro de consulta opcional | Parâmetro | Tipo | Descrição | | --- | --- | --- | | `currency` | string | Filtra os resultados por uma única moeda (por exemplo, `USD`). Se omitido, todas as moedas são retornadas. | ### Exemplo de requisição — todas as moedas ```bash curl -X GET "https://api.test.ripple.com/v2/balances" \ -H "Authorization: Bearer " ``` ### Exemplo de requisição — apenas USD ```bash curl -X GET "https://api.test.ripple.com/v2/balances?currency=USD" \ -H "Authorization: Bearer " ``` ### Exemplo de resposta ```json { "timestamp": "2025-03-15T10:30:00.000000Z", "balances": [ { "fundingType": "FUNDED", "currency": "USD", "availableBalance": "50000.00", "reservedBalance": "2500.00" } ] } ``` ### Entendendo os campos de saldo | Campo | Descrição | | --- | --- | | `availableBalance` | Recursos que podem ser usados no momento. Este é o saldo que você pode usar para iniciar novos pagamentos. | | `reservedBalance` | Recursos atualmente separados para pagamentos em andamento. Você não pode usar este saldo para iniciar novos pagamentos até que a reserva seja liberada ou consumida. | | `timestamp` | O momento em que o instantâneo do saldo foi capturado. | Saldo e criação de pagamentos Se uma requisição de criação de pagamento falhar com o erro `USR_067` (Insufficient balance), compare `availableBalance` com o valor do pagamento. O saldo reservado não está disponível para novos pagamentos. ## Etapa 2: Obter as transações do ledger Use a operação **Get ledger transactions** para recuperar uma lista paginada de lançamentos de ledger dentro de um intervalo de data e hora. Cada lançamento mostra a operação realizada, o efeito dela sobre o seu saldo disponível e a origem que a criou. ### Endpoint `GET /v2/ledger-transactions` ### Parâmetros de consulta obrigatórios | Parâmetro | Descrição | Exemplo | | --- | --- | --- | | `currency` | Código de moeda ISO 4217. | `USD` | | `start-dttm` | Início do intervalo de data e hora (inclusivo, UTC). | `2025-03-15T00:00:00Z` | | `end-dttm` | Fim do intervalo de data e hora (exclusivo, UTC). | `2025-03-16T00:00:00Z` | | `page-size` | Número de registros por página. Mínimo: 1, máximo: 50. | `25` | ### Parâmetros de consulta opcionais | Parâmetro | Descrição | Exemplo | | --- | --- | --- | | `status` | Filtra os resultados pelo status da transação de ledger. `SUCCESS` retorna as transações de ledger concluídas. `PENDING` está reservado para uso futuro e no momento não retorna resultados. | `SUCCESS` | Outros parâmetros opcionais são abordados mais adiante neste tutorial: `offset` na Etapa 3, `txnReference` na Etapa 4, e `sort-key` e `sort-direction` em Ordenação dos resultados. ### Exemplo de requisição ```bash curl -X GET "https://api.test.ripple.com/v2/ledger-transactions?\ currency=USD\ &start-dttm=2025-03-15T00:00:00Z\ &end-dttm=2025-03-16T00:00:00Z\ &page-size=25" \ -H "Authorization: Bearer " \ -H "Accept: application/json" ``` ### Exemplo de resposta ```json { "offset": "0", "pageSize": "25", "pageElements": "4", "total": "4", "statementTransactions": [ { "tenant": "acme-corp", "amount": "14.00", "currency": "USD", "txnReference": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d", "operation": "DEBIT", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-03-15T10:25:12.000000Z", "updatedDttm": "2025-03-15T10:25:12.000000Z", "availableBalanceBefore": "49986.00", "availableBalanceAfter": "49986.00" }, { "tenant": "acme-corp", "amount": "14.00", "currency": "USD", "txnReference": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d", "operation": "RESERVE", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-03-15T10:25:11.000000Z", "updatedDttm": "2025-03-15T10:25:11.000000Z", "availableBalanceBefore": "50000.00", "availableBalanceAfter": "49986.00" }, { "tenant": "acme-corp", "amount": "10014.00", "currency": "USD", "txnReference": "aa74f2f4-5996-4f0c-9d8a-7a5e1d51c502", "operation": "DEBIT", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-03-15T10:25:10.000000Z", "updatedDttm": "2025-03-15T10:25:10.000000Z", "availableBalanceBefore": "50000.00", "availableBalanceAfter": "50000.00" }, { "tenant": "acme-corp", "amount": "10014.00", "currency": "USD", "txnReference": "aa74f2f4-5996-4f0c-9d8a-7a5e1d51c502", "operation": "RESERVE", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-03-15T10:23:45.000000Z", "updatedDttm": "2025-03-15T10:23:45.000000Z", "availableBalanceBefore": "60014.00", "availableBalanceAfter": "50000.00" } ] } ``` ### Entendendo as operações de ledger O campo `operation` informa qual ação foi aplicada à sua conta. A sequência RESERVE → DEBIT é o padrão típico de um pagamento concluído. | Operação | Efeito sobre `availableBalance` | Quando ocorre | | --- | --- | --- | | `CREDIT` | Aumenta | Recursos são adicionados à sua conta (por exemplo, uma recarga). | | `RESERVE` | Diminui | Recursos são separados quando um pagamento entra no estado de validação ou de transferência. | | `DEBIT` | Sem alteração (normalmente) | Os recursos reservados são consumidos quando um pagamento é concluído. O saldo disponível já havia diminuído no momento do RESERVE. | | `RELEASE` | Aumenta | Os recursos reservados são devolvidos quando um pagamento falha ou é cancelado. | | `VOID_BALANCE` | Depende da implementação | Correção administrativa. Entre em contato com o suporte técnico da Ripple para mais detalhes. | | `OVERRIDE_BALANCE` | Depende da implementação | Correção administrativa. Entre em contato com o suporte técnico da Ripple para mais detalhes. | Por que o DEBIT não altera o saldo disponível Quando um pagamento começa, a operação `RESERVE` tira recursos do saldo disponível e os coloca em estado reservado. Quando o pagamento é concluído, o `DEBIT` finaliza a saída a partir do valor reservado. Mas, como o saldo disponível já havia diminuído no momento do `RESERVE`, `availableBalanceBefore` e `availableBalanceAfter` normalmente são iguais em um lançamento de `DEBIT`. Se um pagamento falhar, um lançamento de `RELEASE` devolve os recursos reservados ao saldo disponível. ## Etapa 3: Paginar os resultados Se o valor de `total` na resposta for maior que `pageElements`, há mais registros a recuperar. Use o parâmetro `offset` para buscar as páginas seguintes. **Padrão:** defina `offset` como um múltiplo de `page-size` para avançar pelas páginas. ### Exemplo: buscar a segunda página ```bash curl -X GET "https://api.test.ripple.com/v2/ledger-transactions?\ currency=USD\ &start-dttm=2025-03-15T00:00:00Z\ &end-dttm=2025-03-16T00:00:00Z\ &page-size=25\ &offset=25" \ -H "Authorization: Bearer " ``` Continue somando `page-size` ao `offset` até que `pageElements` na resposta seja menor que `page-size`, o que indica que você chegou à última página. Fixe o intervalo de tempo antes de paginar Não altere `start-dttm` nem `end-dttm` entre páginas da mesma consulta. Alterar o intervalo de tempo no meio da paginação pode fazer você perder ou duplicar registros. ## Etapa 4: Filtrar por ID de pagamento Para localizar todos os lançamentos de ledger associados a um pagamento específico, use o parâmetro `txnReference`. Para pagamentos, o valor de `txnReference` é o `paymentId` retornado quando o pagamento foi criado. Isso é útil para auditar o impacto de um pagamento específico no saldo (os lançamentos de RESERVE, DEBIT e eventuais RELEASE daquele pagamento). ### Exemplo: consultar os lançamentos de ledger de um pagamento específico ```bash curl -X GET "https://api.test.ripple.com/v2/ledger-transactions?\ currency=USD\ &start-dttm=2025-03-15T00:00:00Z\ &end-dttm=2025-03-16T00:00:00Z\ &page-size=25\ &txnReference=aa74f2f4-5996-4f0c-9d8a-7a5e1d51c502" \ -H "Authorization: Bearer " ``` ### Exemplo de resposta ```json { "offset": "0", "pageSize": "25", "pageElements": "2", "total": "2", "statementTransactions": [ { "tenant": "acme-corp", "amount": "10014.00", "currency": "USD", "txnReference": "aa74f2f4-5996-4f0c-9d8a-7a5e1d51c502", "operation": "DEBIT", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-03-15T10:25:10.000000Z", "updatedDttm": "2025-03-15T10:25:10.000000Z", "availableBalanceBefore": "50000.00", "availableBalanceAfter": "50000.00" }, { "tenant": "acme-corp", "amount": "10014.00", "currency": "USD", "txnReference": "aa74f2f4-5996-4f0c-9d8a-7a5e1d51c502", "operation": "RESERVE", "txnSource": "PAYMENTS", "status": "SUCCESS", "createdDttm": "2025-03-15T10:23:45.000000Z", "updatedDttm": "2025-03-15T10:23:45.000000Z", "availableBalanceBefore": "60014.00", "availableBalanceAfter": "50000.00" } ] } ``` Isso mostra o impacto completo do pagamento no ledger: os recursos foram reservados quando o pagamento foi criado e debitados quando ele foi concluído. ## Etapa 5: Exportar em CSV Em fluxos de conciliação, você pode solicitar a resposta como arquivo CSV definindo o cabeçalho `Accept: text/csv`. Se esse cabeçalho for omitido, a API retorna JSON por padrão. ### Exemplo: baixar um extrato em CSV ```bash curl -X GET "https://api.test.ripple.com/v2/ledger-transactions?\ currency=USD\ &start-dttm=2025-03-01T00:00:00Z\ &end-dttm=2025-04-01T00:00:00Z\ &page-size=50" \ -H "Authorization: Bearer " \ -H "Accept: text/csv" \ -o ledger-march-2025.csv ``` ### Formato CSV A resposta em CSV inclui os mesmos campos da resposta em JSON, como cabeçalhos de coluna: ```csv tenant,amount,currency,txnReference,operation,txnSource,status,createdDttm,updatedDttm,availableBalanceBefore,availableBalanceAfter acme-corp,10014.00,USD,aa74f2f4-5996-4f0c-9d8a-7a5e1d51c502,DEBIT,PAYMENTS,SUCCESS,2025-03-15T10:25:10Z,2025-03-15T10:25:10Z,50000.00,50000.00 acme-corp,10014.00,USD,aa74f2f4-5996-4f0c-9d8a-7a5e1d51c502,RESERVE,PAYMENTS,SUCCESS,2025-03-15T10:23:45Z,2025-03-15T10:23:45Z,60014.00,50000.00 ``` A paginação também vale para o CSV As respostas em CSV também são paginadas. Em intervalos de datas grandes, use o parâmetro `offset` para recuperar as páginas seguintes e concatenar os resultados, omitindo a linha de cabeçalho em todas as páginas depois da primeira. ## Ordenação dos resultados Use `sort-key` e `sort-direction` para controlar a ordem dos resultados. Se esses parâmetros forem omitidos, a ordenação padrão é determinada pela API. ```bash curl -X GET "https://api.test.ripple.com/v2/ledger-transactions?\ currency=USD\ &start-dttm=2025-03-15T00:00:00Z\ &end-dttm=2025-03-16T00:00:00Z\ &page-size=25\ &sort-key=CREATED_AT\ &sort-direction=DESC" \ -H "Authorization: Bearer " ``` Valores de `sort-key` compatíveis: | Valor | Ordena por | | --- | --- | | `CREATED_AT` | Timestamp de criação da transação | | `STATEMENT_OPERATION` | Tipo de operação (CREDIT, DEBIT etc.) | | `STATEMENT_SOURCE` | Origem da transação (PAYMENTS, BANK etc.) | | `STATEMENT_STATUS` | Status da transação de ledger | | `STATEMENT_TXN_REFERENCE` | Referência da transação | | `STATEMENT_UPDATED_AT` | Timestamp da última atualização | ## Tratamento de erros | Código de erro | Status | Descrição | Ação | | --- | --- | --- | --- | | `USR_251` | 400 | Parâmetro de requisição ausente. | Falta um parâmetro obrigatório (`currency`, `start-dttm`, `end-dttm` ou `page-size`). Adicione o parâmetro ausente e tente novamente. | | `SYS_301` | 500 | Erro interno do servidor. | Tente novamente com espera exponencial. Entre em contato com o suporte técnico da Ripple se o problema persistir. | | `CFG_201` | 500 | Configuração inválida. | Não foi possível recuperar os saldos por um problema de configuração. Entre em contato com o suporte técnico da Ripple. | | `AUTH_001` | 401 | Não autorizado. | O seu token é inválido ou expirou. Gere um novo token de acesso e tente novamente. | ## Resumo e próximos passos Neste tutorial, você: 1. Recuperou os seus saldos disponível e reservado atuais usando `GET /v2/balances`. 2. Buscou uma lista paginada de transações de ledger em um intervalo de datas usando `GET /v2/ledger-transactions`. 3. Filtrou as transações por ID de pagamento usando o parâmetro `txnReference`. 4. Exportou os resultados em CSV para conciliação. **Próximos passos:** - Para entender como as operações de ledger se relacionam com os eventos do ciclo de vida do pagamento, consulte [Transações do ledger](/pt-br/products/payments-direct-2/introduction/concepts/ledger-transactions). - Para criar pagamentos que aparecerão como lançamentos de ledger, consulte [Criar um pagamento](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-a-payment). - Para ver os códigos de erro relacionados a saldo, consulte [Erros da API](/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors). - Para monitorar as mudanças de estado do pagamento que geram atividade no ledger, consulte [Polling](/pt-br/products/payments-direct-2/api-docs/payment-monitoring/polling) ou [Webhooks de notificação](/pt-br/products/payments-direct-2/api-docs/payment-monitoring/notification-webhooks).