Empreendimentos

Gerencie empreendimentos imobiliarios da sua incorporadora: cadastro, blocos, tipologias, areas comuns e vinculo com terrenos. Cada empreendimento representa um projeto de incorporacao completo, desde a fase de estudo ate a entrega das unidades.

Para criar um empreendimento, voce precisa da permissao land_bank:write ou superior. Leitura requer land_bank:read.

GET /v1/developments

Lista todos os empreendimentos da organizacao com paginacao e filtros.

Query Parameters

Parametro	Tipo	Padrao	Descricao
`page`	number	1	Pagina atual
`limit`	number	20	Itens por pagina (max: 100)
`phase`	string	-	Filtrar por fase: `study`, `approval`, `pre_launch`, `launch`, `construction`, `delivery`, `completed`
`type`	string	-	Filtrar por tipo: `residential`, `commercial`, `mixed`, `lots`
`archived`	boolean	`false`	Incluir empreendimentos arquivados
`search`	string	-	Buscar por nome, endereco ou APF
`land_plot_id`	string	-	Filtrar por terreno vinculado
`sort`	string	`-created_at`	Ordenacao (ex: `name`, `-total_units`, `-created_at`)

Request

curl -X GET "https://api.octabuild.com.br/v1/developments?phase=construction&type=residential&limit=10" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "dev_abc123def456",
      "name": "Residencial Parque das Flores",
      "land_plot_id": "lp_xyz789ghi012",
      "apf": "APF-2026-001",
      "address": "Rua das Palmeiras, 500",
      "city": "Goiania",
      "state": "GO",
      "zip_code": "74000-000",
      "type": "residential",
      "phase": "construction",
      "total_units": 120,
      "total_blocks": 4,
      "total_floors": 8,
      "total_parking_spots": 180,
      "finish_standard": "medio",
      "total_gvs": 45000000.00,
      "estimated_total_cost": 32000000.00,
      "gross_margin_pct": 28.89,
      "expected_construction_start": "2026-06-01",
      "archived_at": null,
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-02-20T14:00:00Z"
    },
    {
      "id": "dev_def456ghi789",
      "name": "Edifício Horizonte",
      "land_plot_id": "lp_abc123xyz456",
      "apf": "APF-2026-002",
      "address": "Av. T-63, 1200",
      "city": "Goiania",
      "state": "GO",
      "zip_code": "74230-100",
      "type": "residential",
      "phase": "construction",
      "total_units": 64,
      "total_blocks": 2,
      "total_floors": 12,
      "total_parking_spots": 96,
      "finish_standard": "alto",
      "total_gvs": 38000000.00,
      "estimated_total_cost": 26000000.00,
      "gross_margin_pct": 31.58,
      "expected_construction_start": "2026-03-15",
      "archived_at": null,
      "created_at": "2026-01-08T09:00:00Z",
      "updated_at": "2026-02-18T11:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "pages": 1
  }
}

POST /v1/developments

Cria um novo empreendimento.

Request Body

Campo	Tipo	Obrigatorio	Descricao
`name`	string	Sim	Nome do empreendimento
`land_plot_id`	string	Nao	ID do terreno vinculado
`apf`	string	Nao	Numero do APF (Alvara de Permissao para Funcionamento)
`address`	string	Nao	Endereco completo
`city`	string	Nao	Cidade
`state`	string	Nao	Estado (UF, 2 caracteres)
`zip_code`	string	Nao	CEP
`type`	string	Nao	Tipo: `residential`, `commercial`, `mixed`, `lots`
`total_units`	number	Nao	Numero total de unidades
`total_blocks`	number	Nao	Numero total de blocos/torres
`total_floors`	number	Nao	Numero total de pavimentos
`total_parking_spots`	number	Nao	Numero total de vagas de garagem
`finish_standard`	string	Nao	Padrao de acabamento: `economico`, `medio`, `alto`, `luxo`
`spe_company_name`	string	Nao	Razao social da SPE
`spe_document`	string	Nao	CNPJ da SPE
`spe_representative_name`	string	Nao	Nome do representante legal da SPE
`spe_representative_document`	string	Nao	CPF do representante legal da SPE
`technical_lead_name`	string	Nao	Nome do responsavel tecnico
`technical_lead_crea_cau`	string	Nao	Numero do CREA/CAU do responsavel tecnico
`total_gvs`	number	Nao	Valor Geral de Vendas (VGV) total em R$
`estimated_total_cost`	number	Nao	Custo total estimado em R$
`gross_margin_pct`	number	Nao	Margem bruta percentual
`land_purchase_date`	string	Nao	Data de aquisicao do terreno (YYYY-MM-DD)
`expected_construction_start`	string	Nao	Previsao de inicio da obra (YYYY-MM-DD)
`phase`	string	Nao	Fase atual (padrao: `study`)
`nbr_standard`	string	Nao	Norma NBR aplicavel
`notes`	string	Nao	Observacoes gerais

Fases do Empreendimento

Fase	Descricao
`study`	Estudo de viabilidade
`approval`	Em aprovacao nos orgaos competentes
`pre_launch`	Pre-lancamento comercial
`launch`	Lancamento
`construction`	Em obra
`delivery`	Em fase de entrega
`completed`	Concluido

Tipos de Empreendimento

Tipo	Descricao
`residential`	Residencial
`commercial`	Comercial
`mixed`	Uso misto (residencial + comercial)
`lots`	Loteamento

Request

curl -X POST https://api.octabuild.com.br/v1/developments \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Residencial Parque das Flores",
    "land_plot_id": "lp_xyz789ghi012",
    "apf": "APF-2026-001",
    "address": "Rua das Palmeiras, 500",
    "city": "Goiania",
    "state": "GO",
    "zip_code": "74000-000",
    "type": "residential",
    "total_units": 120,
    "total_blocks": 4,
    "total_floors": 8,
    "total_parking_spots": 180,
    "finish_standard": "medio",
    "spe_company_name": "Parque das Flores SPE Ltda",
    "spe_document": "12.345.678/0001-90",
    "spe_representative_name": "Carlos Eduardo Santos",
    "spe_representative_document": "123.456.789-00",
    "technical_lead_name": "Eng. Ana Paula Ribeiro",
    "technical_lead_crea_cau": "CREA-GO 12345/D",
    "total_gvs": 45000000.00,
    "estimated_total_cost": 32000000.00,
    "gross_margin_pct": 28.89,
    "land_purchase_date": "2025-11-10",
    "expected_construction_start": "2026-06-01",
    "phase": "approval",
    "nbr_standard": "NBR 15575",
    "notes": "Empreendimento proximo ao Parque Flamboyant"
  }'

Response

{
  "success": true,
  "data": {
    "id": "dev_abc123def456",
    "name": "Residencial Parque das Flores",
    "land_plot_id": "lp_xyz789ghi012",
    "apf": "APF-2026-001",
    "address": "Rua das Palmeiras, 500",
    "city": "Goiania",
    "state": "GO",
    "zip_code": "74000-000",
    "type": "residential",
    "phase": "approval",
    "total_units": 120,
    "total_blocks": 4,
    "total_floors": 8,
    "total_parking_spots": 180,
    "finish_standard": "medio",
    "spe_company_name": "Parque das Flores SPE Ltda",
    "spe_document": "12.345.678/0001-90",
    "spe_representative_name": "Carlos Eduardo Santos",
    "spe_representative_document": "123.456.789-00",
    "technical_lead_name": "Eng. Ana Paula Ribeiro",
    "technical_lead_crea_cau": "CREA-GO 12345/D",
    "total_gvs": 45000000.00,
    "estimated_total_cost": 32000000.00,
    "gross_margin_pct": 28.89,
    "land_purchase_date": "2025-11-10",
    "expected_construction_start": "2026-06-01",
    "nbr_standard": "NBR 15575",
    "notes": "Empreendimento proximo ao Parque Flamboyant",
    "archived_at": null,
    "created_at": "2026-02-25T10:30:00Z",
    "updated_at": "2026-02-25T10:30:00Z"
  }
}

GET /v1/developments/:id

Busca um empreendimento especifico com todos os dados relacionados: blocos, tipologias, unidades e areas comuns.

Request

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

Response

{
  "success": true,
  "data": {
    "id": "dev_abc123def456",
    "name": "Residencial Parque das Flores",
    "land_plot_id": "lp_xyz789ghi012",
    "apf": "APF-2026-001",
    "address": "Rua das Palmeiras, 500",
    "city": "Goiania",
    "state": "GO",
    "zip_code": "74000-000",
    "type": "residential",
    "phase": "construction",
    "total_units": 120,
    "total_blocks": 4,
    "total_floors": 8,
    "total_parking_spots": 180,
    "finish_standard": "medio",
    "spe_company_name": "Parque das Flores SPE Ltda",
    "spe_document": "12.345.678/0001-90",
    "spe_representative_name": "Carlos Eduardo Santos",
    "spe_representative_document": "123.456.789-00",
    "technical_lead_name": "Eng. Ana Paula Ribeiro",
    "technical_lead_crea_cau": "CREA-GO 12345/D",
    "total_gvs": 45000000.00,
    "estimated_total_cost": 32000000.00,
    "gross_margin_pct": 28.89,
    "land_purchase_date": "2025-11-10",
    "expected_construction_start": "2026-06-01",
    "nbr_standard": "NBR 15575",
    "notes": "Empreendimento proximo ao Parque Flamboyant",
    "archived_at": null,
    "land_plot": {
      "id": "lp_xyz789ghi012",
      "name": "Terreno Palmeiras",
      "address": "Rua das Palmeiras, 500",
      "city": "Goiania",
      "state": "GO",
      "total_area": 5000.00,
      "status": "adquirido"
    },
    "blocks": [
      {
        "id": "blk_001abc",
        "name": "Torre A",
        "floors": 8,
        "units_per_floor": 4,
        "created_at": "2026-01-20T10:00:00Z"
      },
      {
        "id": "blk_002def",
        "name": "Torre B",
        "floors": 8,
        "units_per_floor": 4,
        "created_at": "2026-01-20T10:05:00Z"
      }
    ],
    "typologies": [
      {
        "id": "typ_001abc",
        "name": "Tipo A - 2 Quartos",
        "bedrooms": 2,
        "suites": 1,
        "private_area": 65.50,
        "price": 350000.00,
        "created_at": "2026-01-22T09:00:00Z"
      },
      {
        "id": "typ_002def",
        "name": "Tipo B - 3 Quartos",
        "bedrooms": 3,
        "suites": 1,
        "private_area": 82.00,
        "price": 450000.00,
        "created_at": "2026-01-22T09:10:00Z"
      }
    ],
    "units_summary": {
      "total": 120,
      "available": 85,
      "reserved": 15,
      "sold": 20
    },
    "common_areas": [
      {
        "id": "ca_001abc",
        "name": "Piscina Adulto",
        "area": 120.00
      },
      {
        "id": "ca_002def",
        "name": "Salao de Festas",
        "area": 80.00
      }
    ],
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-20T14:00:00Z"
  }
}

PUT /v1/developments/:id

Atualiza um empreendimento existente. Envie apenas os campos que deseja alterar.

Request

curl -X PUT https://api.octabuild.com.br/v1/developments/dev_abc123def456 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "phase": "construction",
    "total_gvs": 48000000.00,
    "gross_margin_pct": 33.33,
    "notes": "Obra iniciada em marco/2026. Previsao de entrega: dez/2028."
  }'

Response

{
  "success": true,
  "data": {
    "id": "dev_abc123def456",
    "phase": "construction",
    "total_gvs": 48000000.00,
    "gross_margin_pct": 33.33,
    "notes": "Obra iniciada em marco/2026. Previsao de entrega: dez/2028.",
    "updated_at": "2026-02-25T15:00:00Z"
  }
}

DELETE /v1/developments/:id

Arquiva um empreendimento (soft delete). O empreendimento nao sera excluido permanentemente, apenas marcado com archived_at.

Empreendimentos com unidades vendidas nao podem ser arquivados. Cancele as vendas ou transfira as unidades antes de arquivar.

Request

curl -X DELETE https://api.octabuild.com.br/v1/developments/dev_abc123def456 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": {
    "id": "dev_abc123def456",
    "archived_at": "2026-02-25T16:00:00Z"
  }
}

GET /v1/developments/:id/blocks

Lista todos os blocos/torres de um empreendimento.

Request

curl -X GET https://api.octabuild.com.br/v1/developments/dev_abc123def456/blocks \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "blk_001abc",
      "development_id": "dev_abc123def456",
      "name": "Torre A",
      "floors": 8,
      "units_per_floor": 4,
      "created_at": "2026-01-20T10:00:00Z",
      "updated_at": "2026-01-20T10:00:00Z"
    },
    {
      "id": "blk_002def",
      "development_id": "dev_abc123def456",
      "name": "Torre B",
      "floors": 8,
      "units_per_floor": 4,
      "created_at": "2026-01-20T10:05:00Z",
      "updated_at": "2026-01-20T10:05:00Z"
    },
    {
      "id": "blk_003ghi",
      "development_id": "dev_abc123def456",
      "name": "Torre C",
      "floors": 8,
      "units_per_floor": 4,
      "created_at": "2026-01-20T10:10:00Z",
      "updated_at": "2026-01-20T10:10:00Z"
    },
    {
      "id": "blk_004jkl",
      "development_id": "dev_abc123def456",
      "name": "Torre D",
      "floors": 8,
      "units_per_floor": 4,
      "created_at": "2026-01-20T10:15:00Z",
      "updated_at": "2026-01-20T10:15:00Z"
    }
  ]
}

POST /v1/developments/:id/blocks

Cria um novo bloco/torre no empreendimento.

Request Body

Campo	Tipo	Obrigatorio	Descricao
`name`	string	Sim	Nome do bloco ou torre
`floors`	number	Nao	Numero de pavimentos
`units_per_floor`	number	Nao	Unidades por pavimento

Request

curl -X POST https://api.octabuild.com.br/v1/developments/dev_abc123def456/blocks \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Torre E",
    "floors": 10,
    "units_per_floor": 6
  }'

Response

{
  "success": true,
  "data": {
    "id": "blk_005mno",
    "development_id": "dev_abc123def456",
    "name": "Torre E",
    "floors": 10,
    "units_per_floor": 6,
    "created_at": "2026-02-25T11:00:00Z",
    "updated_at": "2026-02-25T11:00:00Z"
  }
}

GET /v1/developments/:id/typologies

Lista todas as tipologias de um empreendimento. Tipologias definem os modelos de unidades disponiveis (ex: 2 quartos, 3 quartos com suite).

Request

curl -X GET https://api.octabuild.com.br/v1/developments/dev_abc123def456/typologies \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "typ_001abc",
      "development_id": "dev_abc123def456",
      "name": "Tipo A - 2 Quartos",
      "bedrooms": 2,
      "suites": 1,
      "private_area": 65.50,
      "price": 350000.00,
      "created_at": "2026-01-22T09:00:00Z",
      "updated_at": "2026-01-22T09:00:00Z"
    },
    {
      "id": "typ_002def",
      "development_id": "dev_abc123def456",
      "name": "Tipo B - 3 Quartos",
      "bedrooms": 3,
      "suites": 1,
      "private_area": 82.00,
      "price": 450000.00,
      "created_at": "2026-01-22T09:10:00Z",
      "updated_at": "2026-01-22T09:10:00Z"
    },
    {
      "id": "typ_003ghi",
      "development_id": "dev_abc123def456",
      "name": "Tipo C - 3 Quartos com 2 Suites",
      "bedrooms": 3,
      "suites": 2,
      "private_area": 95.00,
      "price": 520000.00,
      "created_at": "2026-01-22T09:20:00Z",
      "updated_at": "2026-01-22T09:20:00Z"
    }
  ]
}

POST /v1/developments/:id/typologies

Cria uma nova tipologia no empreendimento.

Request Body

Campo	Tipo	Obrigatorio	Descricao
`name`	string	Sim	Nome da tipologia (ex: "Tipo A - 2 Quartos")
`bedrooms`	number	Nao	Numero de quartos
`suites`	number	Nao	Numero de suites
`private_area`	number	Nao	Area privativa em m²
`price`	number	Nao	Preco base da tipologia em R$

Request

curl -X POST https://api.octabuild.com.br/v1/developments/dev_abc123def456/typologies \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tipo D - Cobertura Duplex",
    "bedrooms": 4,
    "suites": 2,
    "private_area": 150.00,
    "price": 980000.00
  }'

Response

{
  "success": true,
  "data": {
    "id": "typ_004jkl",
    "development_id": "dev_abc123def456",
    "name": "Tipo D - Cobertura Duplex",
    "bedrooms": 4,
    "suites": 2,
    "private_area": 150.00,
    "price": 980000.00,
    "created_at": "2026-02-25T11:30:00Z",
    "updated_at": "2026-02-25T11:30:00Z"
  }
}

Padrao de Acabamento

Padrao	Descricao
`economico`	Padrao economico (MCMV e similares)
`medio`	Padrao medio
`alto`	Alto padrao
`luxo`	Luxo e super luxo

Campos SPE

A SPE (Sociedade de Proposito Especifico) e a pessoa juridica criada exclusivamente para o empreendimento, conforme exigencia da Lei 4.591/64.

Campo	Descricao
`spe_company_name`	Razao social da SPE
`spe_document`	CNPJ da SPE
`spe_representative_name`	Nome do representante legal
`spe_representative_document`	CPF do representante legal

Campos do Responsavel Tecnico

Campo	Descricao
`technical_lead_name`	Nome completo do engenheiro ou arquiteto responsavel
`technical_lead_crea_cau`	Registro no CREA (engenheiro) ou CAU (arquiteto)

Erros Comuns

Codigo	Erro	Solucao
`400`	`Name is required`	O campo `name` e obrigatorio
`400`	`Invalid phase`	Use uma fase valida: `study`, `approval`, `pre_launch`, `launch`, `construction`, `delivery`, `completed`
`400`	`Invalid type`	Use um tipo valido: `residential`, `commercial`, `mixed`, `lots`
`400`	`Invalid state format`	Use a sigla do estado com 2 caracteres (ex: `GO`, `SP`)
`400`	`Invalid date format`	Use formato YYYY-MM-DD
`404`	`Development not found`	Verifique o ID do empreendimento
`404`	`Land plot not found`	O `land_plot_id` informado nao existe
`409`	`Duplicate APF`	Ja existe um empreendimento com esse numero de APF
`422`	`Development has sold units`	Nao e possivel arquivar empreendimento com unidades vendidas
`422`	`Block name already exists`	Ja existe um bloco com esse nome neste empreendimento
`422`	`Typology name already exists`	Ja existe uma tipologia com esse nome neste empreendimento

Empreendimentos

On this page