API

Unidades

Gerenciar unidades autonomas de um empreendimento via API.

Unidades

Gerencie as unidades autonomas (apartamentos, salas, lojas, etc.) de um empreendimento. Cada unidade pertence a um empreendimento e pode estar associada a uma tipologia e a um bloco.

Todos os endpoints de unidades sao aninhados sob um empreendimento. Voce precisa do development_id (ID do empreendimento) em todas as chamadas.

GET /v1/developments/:id/units

Lista todas as unidades de um empreendimento com paginacao e filtros.

Path Parameters

ParametroTipoDescricao
idstringID do empreendimento

Query Parameters

ParametroTipoPadraoDescricao
pagenumber1Pagina atual
limitnumber20Itens por pagina (max: 100)
statusstring-Filtrar por status da unidade
block_idstring-Filtrar por bloco
typology_idstring-Filtrar por tipologia

Request

curl -X GET "https://api.octabuild.com.br/v1/developments/dev_abc123/units?status=disponivel&block_id=blk_001&page=1&limit=20" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "unt_a1b2c3d4",
      "development_id": "dev_abc123",
      "designation": "Apto 101",
      "typology_id": "typ_xyz789",
      "block_id": "blk_001",
      "floor": 1,
      "private_area_real": 65.40,
      "private_area_equiv": 68.20,
      "common_area_real": 12.50,
      "common_area_equiv": 14.00,
      "total_area_real": 77.90,
      "total_area_equiv": 82.20,
      "proportionality_coefficient": 0.0125,
      "parking_spot": "V-12",
      "status": "disponivel",
      "boundary_front": "Corredor de circulacao",
      "boundary_back": "Unidade 102",
      "boundary_right": "Fachada norte",
      "boundary_left": "Fachada sul",
      "boundary_floor": "Laje do terreo",
      "typology": {
        "id": "typ_xyz789",
        "name": "2 Quartos com Suite"
      },
      "block": {
        "id": "blk_001",
        "name": "Torre A"
      },
      "created_at": "2026-02-10T14:00:00Z",
      "updated_at": "2026-02-10T14:00:00Z"
    },
    {
      "id": "unt_e5f6g7h8",
      "development_id": "dev_abc123",
      "designation": "Apto 102",
      "typology_id": "typ_xyz789",
      "block_id": "blk_001",
      "floor": 1,
      "private_area_real": 65.40,
      "private_area_equiv": 68.20,
      "common_area_real": 12.50,
      "common_area_equiv": 14.00,
      "total_area_real": 77.90,
      "total_area_equiv": 82.20,
      "proportionality_coefficient": 0.0125,
      "parking_spot": "V-13",
      "status": "disponivel",
      "boundary_front": "Corredor de circulacao",
      "boundary_back": "Unidade 101",
      "boundary_right": "Fachada norte",
      "boundary_left": "Fachada sul",
      "boundary_floor": "Laje do terreo",
      "typology": {
        "id": "typ_xyz789",
        "name": "2 Quartos com Suite"
      },
      "block": {
        "id": "blk_001",
        "name": "Torre A"
      },
      "created_at": "2026-02-10T14:00:00Z",
      "updated_at": "2026-02-10T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 48,
    "pages": 3
  }
}

POST /v1/developments/:id/units

Cria uma nova unidade no empreendimento.

Path Parameters

ParametroTipoDescricao
idstringID do empreendimento

Request Body

CampoTipoObrigatorioDescricao
designationstringSimDesignacao da unidade (ex: "Apto 101", "Sala 02")
typology_idstringNaoID da tipologia
block_idstringNaoID do bloco
floornumberNaoPavimento/andar
private_area_realnumberNaoArea privativa real (m2)
private_area_equivnumberNaoArea privativa equivalente (m2)
common_area_realnumberNaoArea comum real (m2)
common_area_equivnumberNaoArea comum equivalente (m2)
total_area_realnumberNaoArea total real (m2)
total_area_equivnumberNaoArea total equivalente (m2)
proportionality_coefficientnumberNaoCoeficiente de proporcionalidade (fracao ideal)
parking_spotstringNaoIdentificacao da vaga de garagem
statusstringNaoStatus da unidade
boundary_frontstringNaoConfrontacao pela frente
boundary_backstringNaoConfrontacao pelos fundos
boundary_rightstringNaoConfrontacao pela direita
boundary_leftstringNaoConfrontacao pela esquerda
boundary_floorstringNaoConfrontacao pelo piso

Request

curl -X POST https://api.octabuild.com.br/v1/developments/dev_abc123/units \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "designation": "Apto 201",
    "typology_id": "typ_xyz789",
    "block_id": "blk_001",
    "floor": 2,
    "private_area_real": 65.40,
    "private_area_equiv": 68.20,
    "common_area_real": 12.50,
    "common_area_equiv": 14.00,
    "total_area_real": 77.90,
    "total_area_equiv": 82.20,
    "proportionality_coefficient": 0.0125,
    "parking_spot": "V-21",
    "status": "disponivel",
    "boundary_front": "Corredor de circulacao",
    "boundary_back": "Unidade 202",
    "boundary_right": "Fachada norte",
    "boundary_left": "Fachada sul",
    "boundary_floor": "Laje do 1o pavimento"
  }'

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "unt_new123abc",
    "development_id": "dev_abc123",
    "designation": "Apto 201",
    "typology_id": "typ_xyz789",
    "block_id": "blk_001",
    "floor": 2,
    "private_area_real": 65.40,
    "private_area_equiv": 68.20,
    "common_area_real": 12.50,
    "common_area_equiv": 14.00,
    "total_area_real": 77.90,
    "total_area_equiv": 82.20,
    "proportionality_coefficient": 0.0125,
    "parking_spot": "V-21",
    "status": "disponivel",
    "boundary_front": "Corredor de circulacao",
    "boundary_back": "Unidade 202",
    "boundary_right": "Fachada norte",
    "boundary_left": "Fachada sul",
    "boundary_floor": "Laje do 1o pavimento",
    "typology": {
      "id": "typ_xyz789",
      "name": "2 Quartos com Suite"
    },
    "block": {
      "id": "blk_001",
      "name": "Torre A"
    },
    "created_at": "2026-02-25T10:30:00Z",
    "updated_at": "2026-02-25T10:30:00Z"
  }
}

GET /v1/developments/:id/units/:unitId

Busca uma unidade especifica do empreendimento.

Path Parameters

ParametroTipoDescricao
idstringID do empreendimento
unitIdstringID da unidade

Request

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

Response

{
  "success": true,
  "data": {
    "id": "unt_a1b2c3d4",
    "development_id": "dev_abc123",
    "designation": "Apto 101",
    "typology_id": "typ_xyz789",
    "block_id": "blk_001",
    "floor": 1,
    "private_area_real": 65.40,
    "private_area_equiv": 68.20,
    "common_area_real": 12.50,
    "common_area_equiv": 14.00,
    "total_area_real": 77.90,
    "total_area_equiv": 82.20,
    "proportionality_coefficient": 0.0125,
    "parking_spot": "V-12",
    "status": "disponivel",
    "boundary_front": "Corredor de circulacao",
    "boundary_back": "Unidade 102",
    "boundary_right": "Fachada norte",
    "boundary_left": "Fachada sul",
    "boundary_floor": "Laje do terreo",
    "typology": {
      "id": "typ_xyz789",
      "name": "2 Quartos com Suite"
    },
    "block": {
      "id": "blk_001",
      "name": "Torre A"
    },
    "created_at": "2026-02-10T14:00:00Z",
    "updated_at": "2026-02-10T14:00:00Z"
  }
}

PUT /v1/developments/:id/units/:unitId

Atualiza uma unidade existente. Envie apenas os campos que deseja alterar.

Path Parameters

ParametroTipoDescricao
idstringID do empreendimento
unitIdstringID da unidade

Request Body

Aceita os mesmos campos do POST, todos opcionais. Campos nao enviados permanecem inalterados.

Request

curl -X PUT https://api.octabuild.com.br/v1/developments/dev_abc123/units/unt_a1b2c3d4 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "vendida",
    "parking_spot": "V-12A"
  }'

Response

{
  "success": true,
  "data": {
    "id": "unt_a1b2c3d4",
    "development_id": "dev_abc123",
    "designation": "Apto 101",
    "typology_id": "typ_xyz789",
    "block_id": "blk_001",
    "floor": 1,
    "private_area_real": 65.40,
    "private_area_equiv": 68.20,
    "common_area_real": 12.50,
    "common_area_equiv": 14.00,
    "total_area_real": 77.90,
    "total_area_equiv": 82.20,
    "proportionality_coefficient": 0.0125,
    "parking_spot": "V-12A",
    "status": "vendida",
    "boundary_front": "Corredor de circulacao",
    "boundary_back": "Unidade 102",
    "boundary_right": "Fachada norte",
    "boundary_left": "Fachada sul",
    "boundary_floor": "Laje do terreo",
    "typology": {
      "id": "typ_xyz789",
      "name": "2 Quartos com Suite"
    },
    "block": {
      "id": "blk_001",
      "name": "Torre A"
    },
    "created_at": "2026-02-10T14:00:00Z",
    "updated_at": "2026-02-25T11:00:00Z"
  }
}

DELETE /v1/developments/:id/units/:unitId

Exclui permanentemente uma unidade do empreendimento.

Esta operacao e irreversivel. Unidades com vendas ou reservas vinculadas nao podem ser excluidas. Atualize o status para cancelada se precisar inativa-la.

Path Parameters

ParametroTipoDescricao
idstringID do empreendimento
unitIdstringID da unidade

Request

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

Response

{
  "success": true,
  "data": {
    "id": "unt_a1b2c3d4",
    "deleted": true
  }
}

POST /v1/developments/:id/units/bulk

Cria multiplas unidades em lote. Ideal para cadastro inicial de empreendimentos com muitas unidades.

Maximo de 500 unidades por requisicao. Para empreendimentos maiores, divida em multiplas chamadas.

Path Parameters

ParametroTipoDescricao
idstringID do empreendimento

Request Body

CampoTipoObrigatorioDescricao
unitsarraySimArray de objetos de unidade (max: 500)

Cada objeto dentro do array units aceita os mesmos campos do POST /v1/developments/:id/units. O campo designation e obrigatorio em cada item.

Request

curl -X POST https://api.octabuild.com.br/v1/developments/dev_abc123/units/bulk \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "units": [
      {
        "designation": "Apto 101",
        "typology_id": "typ_xyz789",
        "block_id": "blk_001",
        "floor": 1,
        "private_area_real": 65.40,
        "total_area_real": 77.90,
        "proportionality_coefficient": 0.0125,
        "parking_spot": "V-01",
        "status": "disponivel"
      },
      {
        "designation": "Apto 102",
        "typology_id": "typ_xyz789",
        "block_id": "blk_001",
        "floor": 1,
        "private_area_real": 72.10,
        "total_area_real": 85.30,
        "proportionality_coefficient": 0.0138,
        "parking_spot": "V-02",
        "status": "disponivel"
      },
      {
        "designation": "Apto 201",
        "typology_id": "typ_abc456",
        "block_id": "blk_001",
        "floor": 2,
        "private_area_real": 65.40,
        "total_area_real": 77.90,
        "proportionality_coefficient": 0.0125,
        "parking_spot": "V-03",
        "status": "disponivel"
      }
    ]
  }'

Response (201 Created)

{
  "success": true,
  "data": {
    "created": 3,
    "units": [
      {
        "id": "unt_bulk001",
        "development_id": "dev_abc123",
        "designation": "Apto 101",
        "typology_id": "typ_xyz789",
        "block_id": "blk_001",
        "floor": 1,
        "private_area_real": 65.40,
        "private_area_equiv": null,
        "common_area_real": null,
        "common_area_equiv": null,
        "total_area_real": 77.90,
        "total_area_equiv": null,
        "proportionality_coefficient": 0.0125,
        "parking_spot": "V-01",
        "status": "disponivel",
        "boundary_front": null,
        "boundary_back": null,
        "boundary_right": null,
        "boundary_left": null,
        "boundary_floor": null,
        "typology": {
          "id": "typ_xyz789",
          "name": "2 Quartos com Suite"
        },
        "block": {
          "id": "blk_001",
          "name": "Torre A"
        },
        "created_at": "2026-02-25T12:00:00Z",
        "updated_at": "2026-02-25T12:00:00Z"
      },
      {
        "id": "unt_bulk002",
        "development_id": "dev_abc123",
        "designation": "Apto 102",
        "typology_id": "typ_xyz789",
        "block_id": "blk_001",
        "floor": 1,
        "private_area_real": 72.10,
        "private_area_equiv": null,
        "common_area_real": null,
        "common_area_equiv": null,
        "total_area_real": 85.30,
        "total_area_equiv": null,
        "proportionality_coefficient": 0.0138,
        "parking_spot": "V-02",
        "status": "disponivel",
        "boundary_front": null,
        "boundary_back": null,
        "boundary_right": null,
        "boundary_left": null,
        "boundary_floor": null,
        "typology": {
          "id": "typ_xyz789",
          "name": "2 Quartos com Suite"
        },
        "block": {
          "id": "blk_001",
          "name": "Torre A"
        },
        "created_at": "2026-02-25T12:00:00Z",
        "updated_at": "2026-02-25T12:00:00Z"
      },
      {
        "id": "unt_bulk003",
        "development_id": "dev_abc123",
        "designation": "Apto 201",
        "typology_id": "typ_abc456",
        "block_id": "blk_001",
        "floor": 2,
        "private_area_real": 65.40,
        "private_area_equiv": null,
        "common_area_real": null,
        "common_area_equiv": null,
        "total_area_real": 77.90,
        "total_area_equiv": null,
        "proportionality_coefficient": 0.0125,
        "parking_spot": "V-03",
        "status": "disponivel",
        "boundary_front": null,
        "boundary_back": null,
        "boundary_right": null,
        "boundary_left": null,
        "boundary_floor": null,
        "typology": {
          "id": "typ_abc456",
          "name": "3 Quartos com 2 Suites"
        },
        "block": {
          "id": "blk_001",
          "name": "Torre A"
        },
        "created_at": "2026-02-25T12:00:00Z",
        "updated_at": "2026-02-25T12:00:00Z"
      }
    ]
  }
}

Campos da Unidade

Referencia completa dos campos retornados na resposta.

CampoTipoDescricao
idstringIdentificador unico da unidade
development_idstringID do empreendimento
designationstringDesignacao/nome da unidade (ex: "Apto 101")
typology_idstring | nullID da tipologia associada
block_idstring | nullID do bloco associado
floornumber | nullNumero do pavimento/andar
private_area_realnumber | nullArea privativa real em m2
private_area_equivnumber | nullArea privativa equivalente em m2
common_area_realnumber | nullArea comum real em m2
common_area_equivnumber | nullArea comum equivalente em m2
total_area_realnumber | nullArea total real em m2
total_area_equivnumber | nullArea total equivalente em m2
proportionality_coefficientnumber | nullCoeficiente de proporcionalidade (fracao ideal)
parking_spotstring | nullIdentificacao da vaga de garagem
statusstring | nullStatus atual da unidade
boundary_frontstring | nullConfrontacao pela frente
boundary_backstring | nullConfrontacao pelos fundos
boundary_rightstring | nullConfrontacao pela direita
boundary_leftstring | nullConfrontacao pela esquerda
boundary_floorstring | nullConfrontacao pelo piso
typologyobject | nullTipologia aninhada: { id, name }
blockobject | nullBloco aninhado: { id, name }
created_atstringData de criacao (ISO 8601)
updated_atstringData da ultima atualizacao (ISO 8601)

Erros Comuns

CodigoErroSolucao
400Field 'designation' is requiredInforme o campo designation no body
400Field 'units' must be a non-empty arrayO endpoint bulk espera { "units": [...] }
400Maximum 500 units per batchReduza o array para no maximo 500 itens
400Invalid JSON bodyVerifique a formatacao do JSON enviado
404Development not foundVerifique o ID do empreendimento e se pertence a sua organizacao
404Unit not foundVerifique o ID da unidade e se pertence ao empreendimento informado
500INSERT_ERRORErro ao inserir. Verifique se typology_id e block_id existem

Empreendimentos

Criar e gerenciar empreendimentos imobiliarios, blocos e tipologias via API.

Clientes

Gerenciar clientes Pessoa Física (PF) e Jurídica (PJ) via API.

On this page

UnidadesGET /v1/developments/:id/unitsPath ParametersQuery ParametersRequestResponsePOST /v1/developments/:id/unitsPath ParametersRequest BodyRequestResponse (201 Created)GET /v1/developments/:id/units/:unitIdPath ParametersRequestResponsePUT /v1/developments/:id/units/:unitIdPath ParametersRequest BodyRequestResponseDELETE /v1/developments/:id/units/:unitIdPath ParametersRequestResponsePOST /v1/developments/:id/units/bulkPath ParametersRequest BodyRequestResponse (201 Created)Campos da UnidadeErros Comuns