API de integração — v1 (somente leitura)
API REST para sistemas externos (ERP, BI, integradores) consumirem os dados da Buildor. Somente leitura — nenhum endpoint altera ou grava dados.
Base URL: https://buildor.com.br/api/v1
1. Autenticação
Toda requisição deve enviar sua chave no header Authorization.
Chaves de homologação têm prefixo bk_sbx_ e acessam somente o ambiente de testes.
Chaves de produção (prefixo bk_) são geradas pela empresa cliente após o vínculo.
Authorization: Bearer bk_sbx_your_40_character_key_here
| HTTP | Código | Motivo |
|---|---|---|
| 401 | missing_key | Header Authorization ausente |
| 401 | invalid_key | Chave inexistente |
| 401 | revoked | Chave revogada |
| 401 | expired | Chave expirada |
| 403 | plan_inactive | Conta sem plano ativo |
| 403 | scope_not_allowed | Chave sem o escopo do módulo |
| 403 | feature_not_included | Módulo não incluso no plano |
| 404 | not_found | Registro não encontrado no escopo |
| 429 | too_many_requests | Limite de requisições excedido |
2. Escopos
Cada chave é criada com um ou mais escopos. Chamar um módulo sem o escopo retorna 403 scope_not_allowed.
| Escopo | Módulo | Endpoints |
|---|---|---|
| obras | Obras | /api/v1/obras, /api/v1/obras/{uuid}, /api/v1/obras/{uuid}/diarios, /api/v1/diarios, /api/v1/obras/{uuid}/etapas, /api/v1/obras/{uuid}/materiais, /api/v1/obras/{uuid}/ocorrencias, /api/v1/obras/{uuid}/tarefas |
| projetos | Projetos | /api/v1/projetos, /api/v1/projetos/{uuid} |
| financiamentos | Financiamentos | /api/v1/financiamentos, /api/v1/financiamentos/{uuid} |
| financeiro | Financeiro | /api/v1/financeiro/custos, /api/v1/financeiro/resumo |
| agenda | Agenda | /api/v1/agenda/eventos |
3. Rate limit
- • 300 requisições/minuto por chave
- • 600 requisições/minuto por IP
- • Homologação (sandbox): 60 req/min por chave
4. Formato de resposta
Sucessos em data; listas paginadas trazem meta.
Datas usam YYYY-MM-DD e carimbos ISO-8601.
{
"data": [ ... ],
"meta": { "page": 1, "per_page": 25, "total": 137, "last_page": 6 }
}
/api/v1
qualquer escopo
Metadados da API (versão e listagem de endpoints).
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1
/api/v1/empresa
qualquer escopo
Dados gerais da empresa matriz, plano ativo e empresas do grupo (inclui filiais).
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/empresa
/api/v1/obras
escopo: obras
Lista as obras do grupo com totais financeiros calculados.
Ordenação: Mais recentemente atualizadas primeiro.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/obras
Parâmetros de consulta
| Parâmetro | Descrição | Valores aceitos |
|---|---|---|
status |
Filtra pelo status da obra. Aceita vários valores separados por vírgula. |
Em andamento
Planejamento
Pausada
Concluída
Cancelada
|
q |
Busca parcial (texto) no nome da obra. | valor livre |
cliente |
Busca parcial (texto) no nome do cliente. | valor livre |
tipo |
Filtra pelo tipo exato da obra (valor livre, ex.: Residencial, Comercial). | valor livre |
empresa_id |
Restringe aos dados de uma empresa do grupo (matriz ou filial). IDs fora do grupo da chave são ignorados. | valor livre |
since |
Sincronização incremental: retorna apenas obras alteradas após este instante (data YYYY-MM-DD ou ISO-8601). Compara com updated_at > since. | valor livre |
page |
Número da página (padrão 1). | valor livre |
per_page |
Itens por página (máx. 100, padrão 25). | valor livre |
/api/v1/obras/{uuid}
escopo: obras
Detalhe completo de uma obra (endereço, descrição, contadores).
Substitua {uuid} pelo identificador do registro.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/obras/{uuid}
/api/v1/obras/{uuid}/diarios
escopo: obras
Diários de obra com fotos (url pública), descrição e clima.
Ordenação: Do registro mais recente para o mais antigo.
Substitua {uuid} pelo identificador do registro.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/obras/{uuid}/diarios
Parâmetros de consulta
| Parâmetro | Descrição | Valores aceitos |
|---|---|---|
since |
Sincronização incremental: retorna apenas diários alterados após este instante (data YYYY-MM-DD ou ISO-8601). Compara com updated_at > since. | valor livre |
page |
Número da página (padrão 1). | valor livre |
per_page |
Itens por página (máx. 100, padrão 25). | valor livre |
/api/v1/diarios
escopo: obras
Diários de todo o grupo, filtráveis por obra.
Ordenação: Do registro mais recente para o mais antigo.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/diarios
Parâmetros de consulta
| Parâmetro | Descrição | Valores aceitos |
|---|---|---|
obra_uuid |
UUID de uma obra do grupo. Retorna apenas os diários dessa obra. | valor livre |
since |
Sincronização incremental: retorna apenas diários alterados após este instante (data YYYY-MM-DD ou ISO-8601). Compara com updated_at > since. | valor livre |
page |
Número da página (padrão 1). | valor livre |
per_page |
Itens por página (máx. 100, padrão 25). | valor livre |
/api/v1/obras/{uuid}/etapas
escopo: obras
Cronograma da obra: etapas com datas previstas e realizadas.
Ordenação: Pela ordem do cronograma.
Substitua {uuid} pelo identificador do registro.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/obras/{uuid}/etapas
Parâmetros de consulta
| Parâmetro | Descrição | Valores aceitos |
|---|---|---|
since |
Sincronização incremental: retorna apenas etapas alteradas após este instante (data YYYY-MM-DD ou ISO-8601). Compara com updated_at > since. | valor livre |
/api/v1/obras/{uuid}/materiais
escopo: obras
Materiais da obra com estoque atual e movimentações.
Ordenação: Por nome (crescente).
Substitua {uuid} pelo identificador do registro.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/obras/{uuid}/materiais
Parâmetros de consulta
| Parâmetro | Descrição | Valores aceitos |
|---|---|---|
since |
Sincronização incremental: retorna apenas materiais alterados após este instante (data YYYY-MM-DD ou ISO-8601). Compara com updated_at > since. | valor livre |
page |
Número da página (padrão 1). | valor livre |
per_page |
Itens por página (máx. 100, padrão 25). | valor livre |
/api/v1/obras/{uuid}/ocorrencias
escopo: obras
Ocorrências da obra, com status de resolução e foto.
Ordenação: Da ocorrência mais recente para a mais antiga.
Substitua {uuid} pelo identificador do registro.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/obras/{uuid}/ocorrencias
Parâmetros de consulta
| Parâmetro | Descrição | Valores aceitos |
|---|---|---|
resolvida |
Filtra pela situação: true (resolvidas) ou false (pendentes). |
true
false
|
since |
Sincronização incremental: retorna apenas ocorrências alteradas após este instante (data YYYY-MM-DD ou ISO-8601). Compara com updated_at > since. | valor livre |
page |
Número da página (padrão 1). | valor livre |
per_page |
Itens por página (máx. 100, padrão 25). | valor livre |
/api/v1/obras/{uuid}/tarefas
escopo: obras
Tarefas da obra, com status, prioridade e prazo.
Ordenação: Pelo prazo (decrescente).
Substitua {uuid} pelo identificador do registro.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/obras/{uuid}/tarefas
Parâmetros de consulta
| Parâmetro | Descrição | Valores aceitos |
|---|---|---|
status |
Filtra pelo status exato da tarefa. | valor livre |
prioridade |
Filtra pela prioridade. Aceita vários valores separados por vírgula. |
alta
media
baixa
|
since |
Sincronização incremental: retorna apenas tarefas alteradas após este instante (data YYYY-MM-DD ou ISO-8601). Compara com updated_at > since. | valor livre |
page |
Número da página (padrão 1). | valor livre |
per_page |
Itens por página (máx. 100, padrão 25). | valor livre |
/api/v1/projetos
escopo: projetos
Lista os projetos do grupo com custos calculados e margem.
Ordenação: Mais recentemente atualizados primeiro.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/projetos
Parâmetros de consulta
| Parâmetro | Descrição | Valores aceitos |
|---|---|---|
status |
Filtra pelo status do projeto. Aceita vários valores separados por vírgula. |
Em andamento
Concluído
Pausado
Cancelado
|
q |
Busca parcial (texto) no nome do projeto. | valor livre |
since |
Sincronização incremental: retorna apenas projetos alterados após este instante (data YYYY-MM-DD ou ISO-8601). Compara com updated_at > since. | valor livre |
page |
Número da página (padrão 1). | valor livre |
per_page |
Itens por página (máx. 100, padrão 25). | valor livre |
/api/v1/projetos/{uuid}
escopo: projetos
Projeto completo, incluindo disciplinas e documentos.
Substitua {uuid} pelo identificador do registro.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/projetos/{uuid}
/api/v1/financiamentos
escopo: financiamentos
Lista os financiamentos vinculados às obras do grupo.
Ordenação: Mais recentemente atualizados primeiro.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/financiamentos
Parâmetros de consulta
| Parâmetro | Descrição | Valores aceitos |
|---|---|---|
status |
Filtra pelo status do financiamento. Aceita vários valores separados por vírgula. |
ativo
pendente
suspenso
liquidado
cancelado
|
tipo_financiamento |
Filtra pelo tipo exato (valor livre, ex.: SBPE, BNDES, Carteira Hipotecária). | valor livre |
obra_uuid |
UUID de uma obra do grupo. Retorna apenas os financiamentos dessa obra. | valor livre |
since |
Sincronização incremental: retorna apenas financiamentos alterados após este instante (data YYYY-MM-DD ou ISO-8601). Compara com updated_at > since. | valor livre |
page |
Número da página (padrão 1). | valor livre |
per_page |
Itens por página (máx. 100, padrão 25). | valor livre |
/api/v1/financiamentos/{uuid}
escopo: financiamentos
Financiamento completo com liberações, medições, documentos, marcos e conformidades.
Substitua {uuid} pelo identificador do registro.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/financiamentos/{uuid}
/api/v1/financeiro/custos
escopo: financeiro
Lançamentos financeiros do grupo, filtráveis por tipo e período.
Ordenação: Do lançamento mais recente para o mais antigo.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/financeiro/custos
Parâmetros de consulta
| Parâmetro | Descrição | Valores aceitos |
|---|---|---|
tipo |
Filtra pelo tipo do lançamento. Aceita ambos, separados por vírgula. |
receita
despesa
|
categoria |
Filtra pela categoria exata (valor livre, ex.: Material, Mão de obra, Aluguel, Equipamento). | valor livre |
data_de |
Data inicial no formato YYYY-MM-DD. Retorna lançamentos com data a partir deste dia. | valor livre |
data_ate |
Data final no formato YYYY-MM-DD. Retorna lançamentos com data até este dia. | valor livre |
obra_uuid |
UUID de uma obra do grupo. Retorna apenas os lançamentos dessa obra. | valor livre |
since |
Sincronização incremental: retorna apenas lançamentos alterados após este instante (data YYYY-MM-DD ou ISO-8601). Compara com updated_at > since. | valor livre |
page |
Número da página (padrão 1). | valor livre |
per_page |
Itens por página (máx. 100, padrão 25). | valor livre |
/api/v1/financeiro/resumo
escopo: financeiro
Resumo agregado por obra (receitas, despesas, saldo) com totais globais.
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/financeiro/resumo
Parâmetros de consulta
| Parâmetro | Descrição | Valores aceitos |
|---|---|---|
obra_uuid |
UUID de uma obra do grupo. Retorna o resumo apenas dessa obra. | valor livre |
/api/v1/agenda/eventos
escopo: agenda
Eventos da agenda no período informado.
Ordenação: Pela data de início (crescente).
curl -H 'Authorization: Bearer bk_sbx_...' https://buildor.com.br/api/v1/agenda/eventos
Parâmetros de consulta
| Parâmetro | Descrição | Valores aceitos |
|---|---|---|
de |
Data inicial no formato YYYY-MM-DD. Retorna eventos que começam neste dia ou depois. | valor livre |
ate |
Data final no formato YYYY-MM-DD. Retorna eventos que começam neste dia ou antes. | valor livre |
tipo |
Filtra pelo tipo do evento. Aceita vários valores separados por vírgula. |
reuniao
visita
ligacao
entrega
vencimento
prazo_obra
prazo_proj
prazo_disc
|
obra_uuid |
UUID de uma obra do grupo. Retorna apenas os eventos dessa obra. | valor livre |
since |
Sincronização incremental: retorna apenas eventos alterados após este instante (data YYYY-MM-DD ou ISO-8601). Compara com updated_at > since. | valor livre |
page |
Número da página (padrão 1). | valor livre |
per_page |
Itens por página (máx. 100, padrão 25). | valor livre |
Todas as chamadas são registradas e auditadas. Precisando de ajuda? Acesse o portal do desenvolvedor para cadastro e homologação.