Categorias financeiras

Categorias financeiras classificam o dinheiro que entra e sai da conta. É a mesma categoria usada em quatro lugares do Sacador: cobranças, contas a receber, contas a pagar e lançamentos do caixa.

Elas existem em dois níveis:

grupo — categoria de primeiro nível, com bill_category_id: null;
subcategoria — aponta para o grupo em bill_category_id.

Tanto o grupo quanto a subcategoria podem ser usados como categoria de um lançamento.

Cada categoria tem um category_type:

`category_type`	Classifica
`receivable`	O que entra: cobranças, contas a receber, entradas do caixa
`payable`	O que sai: contas a pagar, saídas do caixa

Cobrança é sempre a receber. O campo bill_category_id de uma cobrança só aceita categoria com category_type=receivable; qualquer outra retorna 422. Ver cobranças.

Ao emitir uma cobrança com categoria, ela é herdada pela conta a receber gerada no financeiro e, quando a cobrança é baixada, pelo lançamento do caixa — sem que você precise informá-la de novo.

Modelo

Campo	Tipo	Regras
`id`	integer
`description`	string	Nome da categoria
`category_type`	string	`receivable` ou `payable`
`bill_category_id`	integer \| null	Grupo da subcategoria. `null` quando a própria categoria é um grupo
`position`	decimal	Ordem de exibição usada na tela
`group`	objeto \| null	`{id, description}` do grupo, ou `null`
`created_at`, `updated_at`	ISO-8601

Endpoints

Categorias são somente leitura pela API: são criadas, editadas e excluídas na tela (Financeiro → Categorias).

GET`/v1/bill_categories`

Lista as categorias da conta, grupos e subcategorias juntos. Ordem: position ASC, a mesma da tela.

Query param	Valores	Efeito
`category_type`	`receivable`, `payable`	Filtra pelo tipo. Use `receivable` para achar as categorias que uma cobrança aceita
`bill_category_id`	int	Traz apenas as subcategorias deste grupo
`s`	string	Busca pelo id exato ou pelo início da descrição
`page`, `per_page`	int	Padrão de paginação (ver convenções)

curl -H "Authorization: Bearer sct_seu_token" \
  'https://api.sacador.com.br/v1/bill_categories?category_type=receivable'

{
  "bill_categories": [
    {
      "id": 15,
      "description": "Mensalidades",
      "category_type": "receivable",
      "bill_category_id": null,
      "position": "1.0",
      "group": null,
      "created_at": "2026-08-09T10:12:33.000-03:00",
      "updated_at": "2026-08-09T10:12:33.000-03:00"
    },
    {
      "id": 16,
      "description": "Matrículas",
      "category_type": "receivable",
      "bill_category_id": 15,
      "position": "1.001",
      "group": { "id": 15, "description": "Mensalidades" },
      "created_at": "2026-08-09T10:12:33.000-03:00",
      "updated_at": "2026-08-09T10:12:33.000-03:00"
    }
  ]
}

GET`/v1/bill_categories/:id`

Retorna uma categoria. 404 se o id não existir ou pertencer a outra conta.

Categorias financeiras

Modelo

Endpoints

GET/v1/bill_categories

GET/v1/bill_categories/:id

GET`/v1/bill_categories`

GET`/v1/bill_categories/:id`