Contas
Contas são os lugares onde o dinheiro fica: conta bancária, dinheiro em caixa, administradora de cartão ou carteira de investimentos. Corresponde à tela Contas do menu Financeiro. Cada conta tem duas abas: Movimentação bancária (extrato) e Lançamentos em aberto, cobertas pelos endpoints cash-flow e open-financial-transactions.
Os endereços a seguir são relativos a https://api.pedagogo.app.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
| GET | /financial/accounts | Lista as contas |
| POST | /financial/accounts | Cadastra uma conta |
| GET | /financial/accounts/{uuid} | Consulta uma conta |
| PUT | /financial/accounts/{uuid} | Altera uma conta |
| DELETE | /financial/accounts/{uuid} | Apaga uma conta |
| GET | /financial/accounts/{account_uuid}/cash-flow | Movimentação bancária (extrato) da conta |
| GET | /financial/accounts/{account_uuid}/open-financial-transactions | Lançamentos em aberto da conta |
| GET | /financial/accounts/types | Tipos de conta (lista de apoio) |
| GET | /financial/accounts/companies | Empresas disponíveis para o campo Empresa (lista de apoio) |
Cadastrar, consultar, alterar e apagar
POST /financial/accounts
Cadastra uma conta na empresa cliente do usuário. O uuid da conta e o cliente são preenchidos pelo servidor.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
account_type_id | Sim | Número | Tipo de conta. Use um id de /financial/accounts/types |
account | Sim | Texto | Nome da conta |
balance | Sim | Número | Saldo da conta |
company_id | Não | Número | Empresa. Use um id de /financial/accounts/companies |
agency | Não | Texto | Agência bancária |
account_number | Não | Texto | Número da conta bancária |
open_balance_date | Não | Data | Data do saldo em aberto |
open_balance | Não | Número | Saldo em aberto |
Resposta (200): a conta criada, com o uuid.
curl -X POST https://api.pedagogo.app/financial/accounts \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token-de-sessao>" \
-d '{"account_type_id": 1, "account": "Conta exemplo", "balance": 0}'
GET /financial/accounts
Lista as contas da empresa cliente.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
search | Texto livre. Busca no tipo de conta, nome da conta, agência, número da conta e saldo |
account_type_id | Filtra pelo tipo de conta |
company_id | Filtra pela empresa |
column e order | Ordena pela coluna informada e pelo sentido (asc ou desc). Sem eles, a lista vem em ordem alfabética pelo nome da conta |
per_page e page | Paginação, conforme Convenções |
Resposta (200): lista de contas, com id, uuid, account, agency, account_number, balance, account_type_id, account_type, company_id, company_name, open_balance_date, open_balance e os nomes de quem criou e alterou o registro.
GET /financial/accounts/{uuid}
Devolve a conta com o uuid informado. Retorna 404 se a conta não existir na empresa cliente do usuário.
PUT /financial/accounts/{uuid}
Altera uma conta. Envie somente os campos que mudam.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
account_type_id | Não | Número | Tipo de conta |
company_id | Não | Número | Empresa |
account | Não | Texto | Nome da conta |
balance | Não | Número | Saldo da conta |
agency | Não | Texto | Agência bancária |
account_number | Não | Texto | Número da conta bancária |
open_balance_date | Não | Data | Data do saldo em aberto |
open_balance | Não | Número | Saldo em aberto |
Resposta (200): a conta alterada.
DELETE /financial/accounts/{uuid}
Remove a conta. Resposta 200, sem corpo.
Movimentação bancária e lançamentos em aberto
GET /financial/accounts/{account_uuid}/cash-flow
Extrato da conta (aba Movimentação bancária). Mostra somente lançamentos com situação Pago ou Conciliado, com o saldo após cada um.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
start_date | Data inicial do período (AAAA-MM-DD) |
end_date | Data final do período (AAAA-MM-DD) |
Informe os dois parâmetros juntos. Sem eles, o período considerado é o último mês, até a data atual.
Resposta (200): lista sem paginação, com até 10.000 lançamentos. O primeiro item é o Saldo Inicial do período (id e uuid nulos, description igual a "Saldo Inicial", payday com a data inicial e balance com o saldo antes do período). Os demais itens são os lançamentos do período, em ordem de data de pagamento, cada um com o campo balance acumulado.
GET /financial/accounts/{account_uuid}/open-financial-transactions
Lançamentos da conta que ainda estão em aberto (aba Lançamentos em aberto). Ordenados pela data de vencimento.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
search | Texto livre, buscando na descrição, no tipo de lançamento, no tipo de conta e no nome do cliente ou fornecedor |
start_date e end_date | Período de vencimento. Informe os dois juntos. Sem eles, o período é o último mês, até a data atual |
per_page e page | Paginação, conforme Convenções |
Resposta (200): lista de lançamentos em aberto, com uuid, due_date, description, amount, days_late, status_id, release_type, customer_vendor_name e payment_method.
Listas de apoio
GET /financial/accounts/types
Tipos de conta usados no campo Tipo de conta: Conta bancária, Dinheiro, Administrador de cartão e Carteira de investimentos. Resposta com id e account_type.
GET /financial/accounts/companies
Empresas que o usuário pode escolher no campo Empresa. Resposta em lista, com o id e o nome de cada empresa.
Listas de apoio em outras telas
As telas de contas a pagar, contas a receber e Movimentação financeira usam /financial/accounts, com os mesmos parâmetros, sob os caminhos /financial/accounts-payable/accounts, /financial/accounts-payable/bank-accounts, /financial/accounts-receivable/accounts, /financial/accounts-receivable/bank-accounts, /financial/reports/accounts e /financial/settings/accounts. Veja Contas a pagar e Contas a receber, e a página de Relatórios do módulo Financeiro.