Referência da API

Documentação completa de todos os endpoints disponíveis na API OctaBuild.

Base URL

https://api.octabuild.ai/v1

Endpoints Disponíveis

Terrenos (Land Plots)

Gerenciar banco de terrenos, due diligence e certidões.

GET /v1/land-plots - Listar terrenos
POST /v1/land-plots - Cadastrar terreno
GET /v1/land-plots/:id - Buscar terreno
PUT /v1/land-plots/:id - Atualizar terreno
DELETE /v1/land-plots/:id - Remover terreno

Empreendimentos (Developments)

Criar e gerenciar empreendimentos imobiliários.

GET /v1/developments - Listar empreendimentos
POST /v1/developments - Criar empreendimento
GET /v1/developments/:id - Buscar empreendimento
PUT /v1/developments/:id - Atualizar empreendimento

Unidades (Units)

Gerenciar unidades autônomas de empreendimentos.

GET /v1/developments/:id/units - Listar unidades
POST /v1/developments/:id/units - Criar unidade
POST /v1/developments/:id/units/bulk - Criar em lote

Clientes

Gerenciar clientes Pessoa Física e Jurídica.

GET /v1/clients - Listar clientes
POST /v1/clients - Criar cliente
GET /v1/clients/:id - Buscar cliente
PUT /v1/clients/:id - Atualizar cliente

Financeiro

Controlar contas a pagar, receber e fornecedores.

GET /v1/financial/payables - Contas a pagar
GET /v1/financial/receivables - Contas a receber
GET /v1/financial/categories - Categorias
GET /v1/financial/suppliers - Fornecedores
GET /v1/financial/dashboard - Resumo financeiro

Webhooks

Receber notificações de eventos em tempo real.

land_plot.* - Eventos de terrenos
development.* - Eventos de empreendimentos
unit.* - Eventos de unidades
financial.* - Eventos financeiros

Formato das Respostas

Sucesso

{
  "success": true,
  "data": {
    // Dados da resposta
  }
}

Sucesso com Paginação

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Erro

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Campo 'name' é obrigatório"
  }
}

Códigos HTTP

Código	Descrição	Quando Usar
`200`	OK	Requisição bem-sucedida
`201`	Created	Recurso criado com sucesso
`400`	Bad Request	Parâmetros inválidos
`401`	Unauthorized	Falha na autenticação
`403`	Forbidden	Sem permissão para o recurso
`404`	Not Found	Recurso não encontrado
`409`	Conflict	Registro duplicado
`422`	Unprocessable Entity	Validação de negócio falhou
`429`	Too Many Requests	Limite de requisições excedido
`500`	Internal Server Error	Erro interno

Paginação

Endpoints que retornam listas suportam paginação via query parameters:

Parâmetro	Padrão	Máximo	Descrição
`page`	1	-	Número da página
`limit`	20	100	Itens por página

GET /v1/land-plots?page=2&limit=50

Filtros

# Filtrar terrenos por status
GET /v1/land-plots?status=prospeccao

# Filtrar por múltiplos status
GET /v1/land-plots?statuses=prospeccao,analise_preliminar

# Buscar por texto
GET /v1/land-plots?search=alphaville

# Filtrar contas a pagar por período
GET /v1/financial/payables?due_date_from=2026-01-01&due_date_to=2026-01-31

Ordenação

Use o parâmetro sort para ordenar resultados:

# Ordenar por data de criação (mais recente primeiro)
GET /v1/land-plots?sort=-created_at

# Ordenar por valor (menor para maior)
GET /v1/land-plots?sort=asking_price

Prefixo	Direção
(nenhum)	Ascendente (A-Z, 0-9)
`-`	Descendente (Z-A, 9-0)

Datas e Horários

Todas as datas usam formato ISO 8601: YYYY-MM-DD
Timestamps incluem timezone: 2026-02-25T10:30:00Z
Sempre retornamos em UTC

Versionamento

A API usa versionamento na URL (/v1). Mudanças breaking serão lançadas em novas versões, garantindo compatibilidade com integrações existentes.

Suporte

Email: suporte@octabuild.ai
Documentação: Você está aqui!