Contas bancárias (bank-accounts)

O recurso bank-accounts expõe as contas bancárias cadastradas no financeiro da sua conta: nome, banco, agência, número, tipo, moeda, saldo inicial e saldo atual calculado. Carteiras têm um recurso próprio: Carteiras.

Acesso


Módulo	`contas_bancarias`
Escopos	`bank-accounts:read` e `bank-accounts:write`; escrita inclui leitura
Operações	consulta, cadastro, alteração, arquivamento, restauração e abertura operacional

Endpoints

Método	Endpoint	Descrição
`GET`	`/v1/bank-accounts`	Lista contas bancárias, com paginação por cursor
`GET`	`/v1/bank-accounts/{id}`	Retorna uma conta bancária pelo `id`
`GET`	`/v1/banks` e `/v1/banks/{id}`	Consulta o cadastro de bancos
`GET`	`/v1/bank-accounts/{bank_account_id}/pix-keys`	Lista chaves PIX da conta
`GET`	`/v1/bank-accounts/{bank_account_id}/pix-keys/{id}`	Consulta uma chave PIX
`POST`	`/v1/bank-accounts`	Cadastra conta em BRL; saldo inicial somente na criação
`PATCH`	`/v1/bank-accounts/{id}`	Altera campos de cadastro permitidos
`DELETE`	`/v1/bank-accounts/{id}`	Arquiva preservando o histórico
`POST`	`/v1/bank-accounts/{id}/restore`	Restaura o cadastro
`POST`	`/v1/bank-accounts/{id}/cash-opening`	Declara saldo reconciliado e data de corte
`GET`	`/v1/bank-accounts/{id}/cash-projection`	Consulta saldo operacional com base explícita
`GET`	`/v1/bank-accounts/{id}/cash-statement`	Lista movimentos após a abertura

As chaves PIX também aceitam POST na coleção, PATCH/DELETE no registro e POST /{id}/restore. is_active=false indica uma chave arquivada; para novas cobranças, filtre filter[is_active][eq]=true. O histórico continua consultável.

current_balance conserva a base publicada initial_balance_plus_paid_sales. A projeção operacional é separada: antes de declarar a abertura, retorna opened=false e balance_cents=null. Depois, considera movimentos registrados após a abertura. Valores das operações usam centavos inteiros. Consulte operações financeiras para transferências, baixas e estornos.

Campos

Campo	Tipo	Descrição
`id`	`uuid`	Identificador da conta bancária
`account_name`	`string`	Nome da conta, como aparece no aplicativo
`bank_name`	`string \| null`	Nome do banco
`agency_number`	`string \| null`	Número da agência
`account_number`	`string \| null`	Número da conta
`account_type`	`string \| null`	Tipo da conta, por exemplo `checking`, `savings` ou `cash`
`currency`	`string \| null`	Moeda da conta, por exemplo `BRL`
`initial_balance`	`number \| null`	Saldo inicial cadastrado
`current_balance`	`number`	Saldo inicial mais parcelas pagas de vendas ativas e finalizadas
`balance_basis`	`string`	Base do cálculo: `initial_balance_plus_paid_sales`
`balance_calculated_at`	`string`	Momento do cálculo
`is_active`	`boolean \| null`	Se a conta está ativa
`archived`	`boolean`	Se a conta foi arquivada
`notes`	`string \| null`	Observações livres
`created_at`	`string (ISO 8601) \| null`	Data de criação
`updated_at`	`string (ISO 8601) \| null`	Data da última atualização

Use fields para receber só um subconjunto das colunas: ?fields=id,account_name,current_balance.

Filtros e ordenação

A sintaxe do filtro é filter[campo][operador]=valor. Os campos filtráveis de bank-accounts são:

Campo	Exemplo
`account_name`	`filter[account_name][ilike]=Nubank%`
`is_active`	`filter[is_active][eq]=true`
`archived`	`filter[archived][eq]=false`

Os operadores aceitos são eq, neq, gt, gte, lt, lte, in, ilike e is_null. Um campo fora da lista acima responde 422 validation.

A ordenação usa sort=campo para crescente e sort=-campo para decrescente. Os campos ordenáveis estão descritos na Referência. O padrão é id.

A listagem também aceita limit (de 1 a 100, padrão 20) e cursor. Veja Paginação, filtros e ordenação.

Exemplos

Listar

Contas não arquivadas, da mais recente para a mais antiga:

curl -G "$LIGGA_BASE/v1/bank-accounts" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  --data-urlencode "limit=2" \
  --data-urlencode "sort=-id" \
  --data-urlencode "filter[archived][eq]=false"

{
  "data": [
    {
      "id": "0d4f2c9a-1b7e-4c3d-9a52-8e6f1b2c3d4e",
      "account_name": "Conta PJ Principal",
      "bank_name": "Nu Pagamentos S.A.",
      "agency_number": "0001",
      "account_number": "1234567-8",
      "account_type": "checking",
      "currency": "BRL",
      "initial_balance": 5000,
      "current_balance": 18432.75,
      "is_active": true,
      "archived": false,
      "notes": "Conta usada para recebimentos de vendas.",
      "created_at": "2026-03-12T14:22:05.000Z",
      "updated_at": "2026-07-01T09:10:44.000Z"
    },
    {
      "id": "7a1e5d3b-9c2f-4e8a-b6d1-2f3a4b5c6d7e",
      "account_name": "Caixinha da loja",
      "bank_name": null,
      "agency_number": null,
      "account_number": null,
      "account_type": "cash",
      "currency": "BRL",
      "initial_balance": 300,
      "current_balance": 512.4,
      "is_active": true,
      "archived": false,
      "notes": null,
      "created_at": "2026-01-05T11:00:00.000Z",
      "updated_at": "2026-06-28T17:45:12.000Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjdhMWU1ZDNiLi4uIiwidiI6IjIwMjYtMDEtMDVUMTE6MDA6MDBaIn0",
    "has_more": true,
    "limit": 2
  },
  "meta": { "request_id": "req_01JZXQ8V2K5M7N9P0R1S2T3U4V" }
}

Enquanto pagination.has_more for true, repita a chamada passando cursor=<pagination.next_cursor>.

Para um painel de saldos, peça só as contas em uso e em ordem alfabética:

curl -G "$LIGGA_BASE/v1/bank-accounts" \
  -H "Authorization: Bearer $LIGGA_API_KEY" \
  --data-urlencode "fields=id,account_name,current_balance,currency" \
  --data-urlencode "filter[is_active][eq]=true" \
  --data-urlencode "filter[archived][eq]=false" \
  --data-urlencode "sort=account_name"

Buscar por id

curl "$LIGGA_BASE/v1/bank-accounts/0d4f2c9a-1b7e-4c3d-9a52-8e6f1b2c3d4e" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": {
    "id": "0d4f2c9a-1b7e-4c3d-9a52-8e6f1b2c3d4e",
    "account_name": "Conta PJ Principal",
    "bank_name": "Nu Pagamentos S.A.",
    "agency_number": "0001",
    "account_number": "1234567-8",
    "account_type": "checking",
    "currency": "BRL",
    "initial_balance": 5000,
    "current_balance": 18432.75,
    "is_active": true,
    "archived": false,
    "notes": "Conta usada para recebimentos de vendas.",
    "created_at": "2026-03-12T14:22:05.000Z",
    "updated_at": "2026-07-01T09:10:44.000Z"
  },
  "meta": { "request_id": "req_01JZXQ8V2K5M7N9P0R1S2T3U4V" }
}

Erros comuns

HTTP	`type`	Quando acontece
401	`invalid_token`	Cabeçalho `Authorization` ausente ou chave inexistente
403	`api_disabled`	A conta ainda não tem a API habilitada
403	`module_not_enabled`	Módulo `contas_bancarias` fora do contrato
403	`insufficient_scope`	Chave sem `bank-accounts:read`
404	`not_found`	`id` inexistente ou pertencente a outra conta
422	`validation`	Campo de filtro, operador, `sort` ou `cursor` não aceito
429	`rate-limit-exceeded`	Limite de requisições do plano excedido

Veja também

Despesas (expenses) — as saídas que movimentam estas contas
Vendas (sales) — as entradas do financeiro
Paginação, filtros e ordenação — cursor, sort e fields
Módulos e escopos — por que um 403 acontece