Rate limiting
As consultas de saldos e extratos estão sujeitas às nossas políticas de rate limiting. Para mais detalhes, consulte Rate Limit.
A API de Extratos da Grafeno permite consultar, de forma simples e programática, as contas, os saldos e as movimentações vinculadas à sua conta Grafeno, facilitando a gestão financeira e a integração com o seu ERP ou plataforma.
Recomendado: Webhook de Extratos
Para acompanhar as movimentações de uma conta, a alternativa ideal é utilizar o nosso Webhook de Extratos. Em vez de consultar o extrato periodicamente (polling), sua aplicação recebe cada nova movimentação assim que ela acontece, o que garante dados mais atualizados, reduz o volume de requisições e evita que sua integração seja impactada pelos limites de rate limiting.
Recomendamos reservar o endpoint de movimentações para consultas pontuais, como conciliações retroativas ou reprocessamento de períodos específicos.
Recursos disponíveis
A API de Extratos é composta por três recursos:
| Recurso | O que faz |
|---|---|
| Contas | Lista todas as contas bancárias das quais você é participante. |
| Saldos | Retorna o saldo atual e o saldo disponível de uma conta. |
| Movimentações | Retorna o extrato de uma conta, com todas as entradas e saídas do período. |
Listar contas bancárias
- Lista todas as contas bancárias vinculadas à sua conta Grafeno, incluindo Conta Empresa, Conta Vinculada (Escrow) e Conta Escrow Flex.
- Retorna informações como agência, número da conta, titularidade, movimentador, aprovador e os papéis que você exerce em cada conta.
Obter saldo da conta
- Consulta o saldo da sua conta Grafeno em tempo real.
- Retorna o saldo atual, o saldo disponível para uso imediato e os saldos inicial e final do período consultado.
Listar movimentações da conta
- Lista as movimentações das contas associadas.
- Permite filtrar por data, tipo de transação e valor.
- Retorna os detalhes de cada movimentação, como data, tipo, valor, contraparte e saldo após a transação.
Movimentações em tempo real
Se o objetivo é receber cada nova movimentação assim que ela ocorre, utilize o Webhook de Extratos em vez de consultar este endpoint repetidamente.
Estrutura dos retornos
Listagem de contas bancárias
| Parâmetro | Descrição | Tipo |
|---|---|---|
| id | Identificador único da conta bancária. | String |
| type | Tipo do recurso. Sempre ipBankAccount neste endpoint. | String |
| attributes.agency | Número da agência. | String |
| attributes.account | Número da conta. | String |
| attributes.bank | Código do banco. | String |
| attributes.companyName | Razão social da empresa titular da conta. | String |
| attributes.documentNumber | CNPJ da empresa titular da conta. | String |
| attributes.mover.moverDocumentNumber | Documento do movimentador da conta. | String |
| attributes.mover.moverCompanyName | Nome do movimentador da conta. | String |
| attributes.approver.approverDocumentNumber | Documento do aprovador da conta. | String |
| attributes.approver.approverCompanyName | Nome do aprovador da conta. | String |
| attributes.associatedFund | Fundo associado à conta, quando aplicável. | String |
| attributes.viewers | Visualizadores autorizados da conta, quando aplicável. | String |
| attributes.roles | Papéis que você exerce na conta: owner, mover e/ou approver. | Array |
Consulta de saldo
| Parâmetro | Descrição | Tipo |
|---|---|---|
| id | Identificador único do registro de saldo. | String |
| type | Tipo do recurso. Sempre balance neste endpoint. | String |
| attributes.currentBalance | Saldo atual da conta. | String |
| attributes.availableBalance | Saldo disponível para uso imediato. | String |
| attributes.initialBalance | Saldo no início do período consultado. | String |
| attributes.finalBalance | Saldo no fim do período consultado. | String |
| meta.search.entryAtGteq | Data de início do período consultado. | String |
| meta.search.entryAtLteq | Data de término do período consultado. | String |
Extrato da conta
| Parâmetro | Descrição | Tipo |
|---|---|---|
| id | Identificador único da movimentação no extrato. | String |
| type | Tipo do recurso. Sempre statementEntry neste endpoint. | String |
| attributes.entryAt | Data e hora da movimentação. | String |
| attributes.kind | Tipo da movimentação (ex.: pix_withdrawal). Veja a tabela abaixo. | String |
| attributes.bankAccount.name | Nome do titular da conta bancária da contraparte. | String |
| attributes.bankAccount.documentNumber | Documento do titular da conta bancária da contraparte. | String |
| attributes.value | Valor da movimentação. | String |
| attributes.apiPartnerTransactionUuid | UUID da transação informado pelo parceiro de API. | String |
| attributes.balance | Saldo da conta após a movimentação. | String |
| meta.search.entryAtGteq | Data inicial do filtro aplicado. | String |
| meta.search.entryAtLteq | Data final do filtro aplicado. | String |
Tipos de movimentação
O campo attributes.kind identifica a natureza de cada movimentação. Para facilitar a consulta, os tipos estão agrupados por categoria.
Entradas
| Movimentação | kind |
|---|---|
| TED Recebida | entry |
| TEF Recebida | tef_entry |
| PIX Recebido | pix_entry |
| Pix Cobrança Recebido | pix_charge_received |
| Recebimento de Boleto via Pix | pix_boleto_received |
| Recebimento de Boletos | repayment |
| Recebimento de Protestos | protest_repayment |
| Recebimento Cartão | card_received |
| Transferência Recebida | transfer_received |
| Transferência Judicial Recebida | judicial_transfer_received |
| Entrada de Split de Cobrança | charge_apportionment_entry |
| — | boleto_payment_transitory_credit |
| — | selic_repo_received |
| — | cetip_received |
Saídas
| Movimentação | kind |
|---|---|
| TED Enviada | withdrawal |
| TEF Enviada | tef_withdrawal |
| PIX Enviado | pix_withdrawal |
| Transferência Enviada | transfer_sent |
| Pagamento | barcode_payment |
| Pagamento de Boleto (Tributos e Convênios) | tribute_payment |
| Pagamento de Boleto (Tributos e Convênios) | fiducia_barcode_payment_withdrawal |
| Pagamento em Lote de Boleto (Tributos e Convênios) | fiducia_batch_transfer_withdrawal |
| Saída de Split de Cobrança | charge_apportionment_withdrawal |
| Débito de Transferência de Titularidade | charge_concession_withdrawal |
| Movimentação Genérica de Saída | generic_movement_out |
| — | selic_repo_sent |
| — | cetip_sent |
Tarifas e custos
| Movimentação | kind |
|---|---|
| Custos | costs |
| Tarifas de Conta | invoice |
| Tarifa TED | ted_cost |
| Tarifa PIX | pix_cost |
| Custas Cartorárias | notary_costs |
| — | account_maintenance_fee |
| — | iof_charge |
| — | selic_cost |
Estornos
| Movimentação | kind |
|---|---|
| Estorno de TED | chargeback |
| Estorno de Envio de TED | ted_sent_chargeback |
| Estorno de Tarifa de TED | ted_cost_chargeback |
| Estorno de TEF Recebida | tef_entry_chargeback |
| Estorno de TEF Enviada | tef_withdrawal_chargeback |
| Estorno de PIX Recebido | pix_entry_chargeback |
| Estorno de Envio PIX | pix_sent_chargeback |
| Estorno de Tarifa PIX | pix_cost_chargeback |
| Estorno de Pagamento | payment_chargeback |
| Estorno de Pagamento | barcode_payment_chargeback |
| Estorno de Pagamento | fiducia_barcode_payment_chargeback |
| — | selic_repo_sent_chargeback |
| — | selic_repo_received_chargeback |
| — | cetip_sent_chargeback |
| — | iof_charge_chargeback |
Outros
| Movimentação | kind |
|---|---|
| Transferência | internal_transfer |
| Movimentação | generic_movement |
| Reconciliação | reconciliation |
Benefícios
- Automação e eficiência: reduz processos manuais ao automatizar a coleta de dados financeiros.
- Transparência e controle: oferece uma visão clara e detalhada das finanças da sua empresa.
- Segurança: permite monitorar as movimentações de perto, reduzindo riscos de fraudes e erros.
- Integração: facilita a conexão com o seu ERP ou plataforma, centralizando a gestão dos recursos.
Exemplos de uso
- Gestão centralizada de contas: um administrador financeiro lista todas as contas da empresa em um só lugar e identifica rapidamente quais precisam de atenção.
- Verificação de saldo antes de pagamentos: antes de uma transferência de valor alto, o sistema consulta o saldo disponível e evita falhas por saldo insuficiente.
- Conciliação automática em tempo real: com o Webhook de Extratos, cada movimentação é recebida assim que ocorre e conciliada automaticamente com os registros contábeis.
- Auditoria de períodos específicos: a equipe de auditoria consulta o endpoint de movimentações para revisar todas as transações de um intervalo de datas.
- Análise de fluxo de caixa: a equipe financeira analisa o histórico de movimentações para identificar períodos de maior e menor liquidez e planejar ações estratégicas.
- Redução de riscos com contas vinculadas: com contas Escrow, os recursos só são movimentados após verificação e aprovação do credor, trazendo mais segurança às transações comerciais.