Pular para o conteúdo

SINAPI Vivo · referência da API

SINAPI Vivo · API

OpenAPI 3.1 · versão 1.0.0 · 7 operações

API de leitura da referência oficial de custos da construção (SINAPI/CAIXA): insumos, composições, árvore analítica e estatísticas. Toda resposta carrega a versão do dado (campo `versao` e header `X-SINAPI-Versao`). Proposta da Levver para a CAIXA (CPSI 0071/2026).

contrato em JSONportal do desenvolvedordisponibilidade

Servidor

https://sinapi.levver.ai/api/v1
Demonstração (perfil proto)

Acesso

O contrato aceita chamada sem credencial, e é assim que a demonstração responde.

ApiKeyAuth · apiKey X-API-Key no header

Chave de leitura. NA DEMONSTRAÇÃO ELA NÃO É VERIFICADA: nenhuma rota lê este header hoje, e a API responde sem credencial nenhuma. O teto de requisições é contado por sessão, e por IP quando não há sessão, e NÃO por esta chave: um balde escolhido pelo cliente seria um teto que o cliente controla, bastando mandar um valor novo a cada chamada. Em produção ela passa a ser obrigatória e verificada, com cota por chave e trilha por chamada. Está declarada aqui para o cliente já nascer com o campo, e porque enviá-la não quebra nada.

Catálogo

Insumos e composições do SINAPI

GET/insumos

Lista insumos

Parâmetros

uf query · string
Sigla da praça (ex.: AC, SP). Ausente, responde na praça default. Sigla que não existe na base também cai na default, e a resposta diz qual foi usada no campo `versao` e no header X-SINAPI-Versao.
regime query · "sem_deson" ou "com_deson", padrão sem_deson
Regime de desoneração da folha. Muda o custo da mão de obra, e com ele o custo da composição.
q query · string
Busca por descrição ou código
classificacao query · string
Filtra por classificação
page query · integer, padrão 1
size query · integer, padrão 25, máximo 100

Respostas

200 Página de insumos
objeto { versao: Versao, total: integer, page: integer, size: integer, items: lista de Insumo }
GET/insumos/{codigo}

Detalhe de um insumo

Parâmetros

codigo path · integerobrigatório
uf query · string
Sigla da praça (ex.: AC, SP). Ausente, responde na praça default. Sigla que não existe na base também cai na default, e a resposta diz qual foi usada no campo `versao` e no header X-SINAPI-Versao.
regime query · "sem_deson" ou "com_deson", padrão sem_deson
Regime de desoneração da folha. Muda o custo da mão de obra, e com ele o custo da composição.

Respostas

200 Insumo
objeto { versao: Versao, insumo: Insumo }
404 Não encontrado nesta base
Erro
GET/composicoes

Lista composições

Parâmetros

uf query · string
Sigla da praça (ex.: AC, SP). Ausente, responde na praça default. Sigla que não existe na base também cai na default, e a resposta diz qual foi usada no campo `versao` e no header X-SINAPI-Versao.
regime query · "sem_deson" ou "com_deson", padrão sem_deson
Regime de desoneração da folha. Muda o custo da mão de obra, e com ele o custo da composição.
q query · string
Busca por descrição ou código
grupo query · string
Filtra por grupo
page query · integer, padrão 1
size query · integer, padrão 25, máximo 100

Respostas

200 Página de composições
objeto { versao: Versao, total: integer, page: integer, size: integer, items: lista de Composicao }
GET/composicoes/{codigo}

Detalhe de uma composição, com a árvore analítica

Parâmetros

codigo path · integerobrigatório
uf query · string
Sigla da praça (ex.: AC, SP). Ausente, responde na praça default. Sigla que não existe na base também cai na default, e a resposta diz qual foi usada no campo `versao` e no header X-SINAPI-Versao.
regime query · "sem_deson" ou "com_deson", padrão sem_deson
Regime de desoneração da folha. Muda o custo da mão de obra, e com ele o custo da composição.

Respostas

200 Composição com árvore
Composicao + objeto { versao: Versao, arvore: lista de ItemArvore }
404 Não encontrada nesta base
Erro

Análise

Cobertura e qualidade do dado

GET/estatisticas

Cobertura e qualidade do catálogo

Parâmetros

uf query · string
Sigla da praça (ex.: AC, SP). Ausente, responde na praça default. Sigla que não existe na base também cai na default, e a resposta diz qual foi usada no campo `versao` e no header X-SINAPI-Versao.
regime query · "sem_deson" ou "com_deson", padrão sem_deson
Regime de desoneração da folha. Muda o custo da mão de obra, e com ele o custo da composição.

Respostas

200 Agregados de cobertura e qualidade
object

Conferência

Malha fina: confere orçamento contra a referência

POST/conferencia

Confere um orçamento em lote contra a referência do SINAPI

Malha fina como serviço: envie um orçamento (array `itens` de {codigo, quantidade, custo}, ou `texto` com linhas `codigo;quantidade;custo`) e receba cada item conferido contra a referência, com o risco e a exposição de glosa por item e no agregado. Até 1000 itens por lote.

Parâmetros

uf query · string
Sigla da praça (ex.: AC, SP). Ausente, responde na praça default. Sigla que não existe na base também cai na default, e a resposta diz qual foi usada no campo `versao` e no header X-SINAPI-Versao.
regime query · "sem_deson" ou "com_deson", padrão sem_deson
Regime de desoneração da folha. Muda o custo da mão de obra, e com ele o custo da composição.

Corpo (obrigatório)

objeto { itens: lista de ItemConferencia, texto: string }

{
  "itens": [
    {
      "codigo": 104658,
      "quantidade": 120,
      "custo": 245
    }
  ]
}

Respostas

200 Conferência do lote
RespostaConferencia
400 Corpo inválido ou lote vazio
Erro
413 Lote acima de 1000 itens
Erro
429 Limite de requisições (30/min)
Erro

Meta

Versão da base

GET/versao

Versão vigente da base

Ponto de partida da integração: além da praça servida, devolve em `disponiveis` TODAS as praças e regimes que a base tem. É essa lista que alimenta o `uf` das outras rotas, e por isso ela não é congelada no contrato.

Parâmetros

uf query · string
Sigla da praça (ex.: AC, SP). Ausente, responde na praça default. Sigla que não existe na base também cai na default, e a resposta diz qual foi usada no campo `versao` e no header X-SINAPI-Versao.
regime query · "sem_deson" ou "com_deson", padrão sem_deson
Regime de desoneração da folha. Muda o custo da mão de obra, e com ele o custo da composição.

Respostas

200 Praça servida e a lista completa das disponíveis
objeto { versao: Versao, disponiveis: lista de VersaoDisponivel }

Esquemas

Os objetos que as respostas carregam. Campo anulável vem marcado, porque ausência de preço no SINAPI é informação, não zero.

Versao
uf stringex. SP
mes stringex. 05/2026
regime stringex. sem desoneração
VersaoDisponivel
uf stringex. AC
mes stringex. 05/2026
regime stringex. sem desoneração
regimeSlug "sem_deson" ou "com_deson"
rotulo stringex. AC · 05/2026 · sem desoneração
Rótulo pronto para exibir
Insumo
codigo integerex. 88309
classificacao string
descricao string
unidade stringex. H
origem string ou nulo
C (coletado) ou CR (composição representativa)
preco number ou nulo
Preço publicado; null se sem preço na vigência
Composicao
codigo integerex. 104658
grupo string
unidade stringex. M2
descricao string
custo number ou nulo
Custo unitário publicado; null se sem custo
pct_as number
Percentual do custo desta composição que a CAIXA obteve com preços de São Paulo por indisponibilidade de coleta na praça. Não é encargo social nem auxílio: é um indicador de procedência do preço, e quanto maior, menos o custo reflete a praça consultada.
sem_custo boolean
ItemArvore
tipo "INSUMO" ou "COMPOSICAO"
codigo integer
descricao string
unidade string
coeficiente number
custoUnitario number ou nulo
custoTotal number ou nulo
situacao string
Erro
erro string
versao Versao
ItemConferencia
codigo integerobrigatórioex. 104658
quantidade numberobrigatórioex. 120
custo numberobrigatórioex. 245
Custo unitário adotado no orçamento conferido
RespostaConferencia
versao Versao
resumo objeto { total: integer, naoEncontrados: integer, acimaReferencia: integer, totalAdotado: number, totalReferencia: number, exposicaoGlosa: number }
itens lista de object
rejeitadas lista de objeto { indice: integer, motivo: string }

Esta página é gerada do contrato a cada requisição, no servidor. Nada aqui depende de recurso externo, então ela abre em rede que bloqueia CDN. Para executar as chamadas, use os exemplos prontos do portal do desenvolvedor ou importe o contrato em JSON no seu cliente.