Financeiro

Gerencie o módulo financeiro da sua incorporadora. Controle contas a pagar, contas a receber, categorias financeiras e fornecedores.

Contas a Pagar

GET /v1/financial/payables

Lista contas a pagar da organização.

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
`page`	number	1	Página atual
`limit`	number	20	Itens por página (máx: 100)
`status`	string	-	Filtrar: `pendente`, `paga`, `vencida`, `cancelada`
`category_id`	string	-	Filtrar por categoria
`supplier_id`	string	-	Filtrar por fornecedor
`search`	string	-	Buscar na descrição
`due_date_from`	string	-	Vencimento a partir de (YYYY-MM-DD)
`due_date_to`	string	-	Vencimento até (YYYY-MM-DD)
`sort`	string	`-due_date`	Ordenação

Request

curl -X GET "https://api.octabuild.com.br/v1/financial/payables?status=pendente" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "description": "Material de construção - Bloco A",
      "amount": 45000.00,
      "due_date": "2026-03-15",
      "issue_date": "2026-02-25",
      "status": "pendente",
      "payment_method": "boleto",
      "category": {
        "id": "cat-001",
        "name": "Material de Construção",
        "code": "MC-001"
      },
      "supplier": {
        "id": "sup-001",
        "name": "Construmix Ltda"
      },
      "created_at": "2026-02-25T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 23,
    "pages": 2
  }
}

POST /v1/financial/payables

Cria uma nova conta a pagar.

Request Body

Campo	Tipo	Obrigatório	Descrição
`description`	string	Sim	Descrição da despesa
`amount`	number	Sim	Valor (deve ser > 0)
`due_date`	string	Sim	Data de vencimento (YYYY-MM-DD)
`issue_date`	string	Não	Data de emissão (padrão: hoje)
`document_number`	string	Não	Número do documento/NF
`status`	string	Não	Status (padrão: `pendente`)
`category_id`	string	Não	ID da categoria
`supplier_id`	string	Não	ID do fornecedor
`payment_method`	string	Não	Método de pagamento
`recurrence`	string	Não	Recorrência: `nenhuma`, `mensal`, `semanal`
`tags`	array	Não	Tags
`internal_notes`	string	Não	Notas internas

Request

curl -X POST https://api.octabuild.com.br/v1/financial/payables \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Mão de obra - Fundação Bloco B",
    "amount": 85000.00,
    "due_date": "2026-04-01",
    "category_id": "cat-002",
    "supplier_id": "sup-003",
    "payment_method": "transferencia"
  }'

GET/PUT/DELETE /v1/financial/payables/:id

Buscar, atualizar ou remover (soft delete) uma conta a pagar específica.

Contas a Receber

GET /v1/financial/receivables

Lista contas a receber. Mesmos parâmetros de paginação e filtros similares a contas a pagar, com filtros adicionais:

Parâmetro	Tipo	Descrição
`client_id`	string	Filtrar por cliente

POST /v1/financial/receivables

Campo	Tipo	Obrigatório	Descrição
`description`	string	Sim	Descrição da receita
`amount`	number	Sim	Valor (deve ser > 0)
`due_date`	string	Sim	Data de vencimento (YYYY-MM-DD)
`category_id`	string	Não	ID da categoria
`client_id`	string	Não	ID do cliente
`client_name`	string	Não	Nome do cliente (se não tiver client_id)
`payment_method`	string	Não	Método de pagamento
`tags`	array	Não	Tags

Request

curl -X POST https://api.octabuild.com.br/v1/financial/receivables \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Sinal - Unidade 101 Bloco A",
    "amount": 50000.00,
    "due_date": "2026-03-01",
    "client_name": "Maria Santos"
  }'

GET/PUT/DELETE /v1/financial/receivables/:id

Buscar, atualizar ou remover (soft delete) uma conta a receber específica.

Categorias Financeiras

GET /v1/financial/categories

Lista categorias financeiras.

Parâmetro	Tipo	Descrição
`direction`	string	Filtrar: `receita` ou `despesa`
`is_active`	string	Filtrar: `true` ou `false`
`search`	string	Buscar por nome

Request

curl -X GET "https://api.octabuild.com.br/v1/financial/categories?direction=despesa" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

POST /v1/financial/categories

Campo	Tipo	Obrigatório	Descrição
`code`	string	Sim	Código único da categoria
`name`	string	Sim	Nome da categoria
`direction`	string	Sim	Direção: `receita` ou `despesa`
`description`	string	Não	Descrição
`dre_group`	string	Não	Grupo no DRE
`parent_id`	string	Não	ID da categoria pai
`display_order`	number	Não	Ordem de exibição (padrão: 0)

GET/PUT/DELETE /v1/financial/categories/:id

CRUD de categoria individual.

Fornecedores

GET /v1/financial/suppliers

Lista fornecedores com paginação.

Parâmetro	Tipo	Descrição
`search`	string	Buscar por nome ou nome fantasia
`is_active`	string	Filtrar: `true` ou `false`

POST /v1/financial/suppliers

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Razão social
`trading_name`	string	Não	Nome fantasia
`document`	string	Não	CPF ou CNPJ
`document_type`	string	Não	Tipo: `cpf` ou `cnpj`
`email`	string	Não	Email
`phone`	string	Não	Telefone
`contact_name`	string	Não	Nome do contato
`address_street`	string	Não	Logradouro
`address_city`	string	Não	Cidade
`address_state`	string	Não	Estado
`address_zip_code`	string	Não	CEP
`bank_name`	string	Não	Banco
`bank_agency`	string	Não	Agência
`bank_account`	string	Não	Conta
`pix_key`	string	Não	Chave PIX
`default_category_id`	string	Não	Categoria padrão
`notes`	string	Não	Observações

GET/PUT/DELETE /v1/financial/suppliers/:id

CRUD de fornecedor individual.

Dashboard Financeiro

GET /v1/financial/dashboard

Retorna um resumo financeiro consolidado.

Request

curl -X GET https://api.octabuild.com.br/v1/financial/dashboard \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": {
    "period": {
      "start": "2026-02-01",
      "end": "2026-02-28"
    },
    "payables": {
      "total": 450000.00,
      "pending": 280000.00,
      "paid": 150000.00,
      "overdue": 20000.00,
      "count": 23
    },
    "receivables": {
      "total": 680000.00,
      "pending": 400000.00,
      "confirmed": 250000.00,
      "overdue": 30000.00,
      "count": 15
    },
    "balance": 230000.00
  }
}

Status Financeiros

Status	Descrição
`pendente`	Aguardando pagamento/recebimento
`paga`	Conta paga
`confirmado`	Recebimento confirmado
`vencida`	Passou do vencimento sem pagamento
`cancelada`	Conta cancelada

Erros Comuns

Código	Erro	Solução
`400`	`Field 'description' is required`	Informe a descrição
`400`	`Field 'amount' must be greater than 0`	Valor deve ser positivo
`400`	`Field 'due_date' is required`	Informe a data de vencimento
`404`	`Payable not found`	Verifique o ID da conta
`409`	`Category code already exists`	Código de categoria já em uso

Financeiro

On this page