Pular para o conteúdo
SINAPI API

Fair SourceSelf-hostedAPI hospedada

Dados do SINAPI,
prontos para integrar.

Consulte insumos, composições, custos por UF e encargos sociais através de uma API REST versionada. O código é público: rode na sua própria infraestrutura ou use a versão hospedada quando não quiser manter o pipeline de importação.

Ver no GitHubVer a documentação
  • OpenAPI 3 + Swagger UI
  • PostgreSQL + Docker Compose
  • Webhooks assinados
  • FSL 1.1 → Apache 2.0
GET/v1/composicoes?busca=alvenaria&uf=SP&tamanho=1
Requisição
curl "https://api.sinapiapi.com.br/v1/composicoes?busca=alvenaria&uf=SP&tamanho=1" \
  -H "X-API-Key: $SINAPI_API_KEY"
Respostaapplication/json
{
  "dados": [
    {
      "codigo": 87280,
      "descricao": "ARGAMASSA TRAÇO 1:7 (EM VOLUME DE CIMENTO E AREIA MÉDIA ÚMIDA) COM ADIÇÃO DE PLASTIFICANTE PARA EMBOÇO/MASSA ÚNICA/ASSENTAMENTO DE ALVENARIA DE VEDAÇÃO, PREPARO MECÂNICO COM BETONEIRA ATÉ 600 L. AF_07/2026",
      "unidade": "M3",
      "grupo": "Argamassas",
      "custos": {
        "semDesoneracao": {
          "valor": "476.32",
          "percentualAtribuidoSaoPaulo": "0",
          "ufsConsideradas": null
        },
        "comDesoneracao": {
          "valor": "466.09",
          "percentualAtribuidoSaoPaulo": "0",
          "ufsConsideradas": null
        },
        "semEncargos": {
          "valor": "402.67",
          "percentualAtribuidoSaoPaulo": "0",
          "ufsConsideradas": null
        }
      }
    }
  ],
  "paginacao": {
    "pagina": 1,
    "tamanho": 1,
    "total": 569,
    "totalPaginas": 569
  },
  "competencia": {
    "ano": 2026,
    "mes": 7
  },
  "abrangencia": "UF",
  "uf": "SP"
}
Por que existe

A planilha deixa de ser parte do seu produto

A CAIXA publica o SINAPI como relatórios mensais em XLSX, dentro de um ZIP, mais um PDF separado para os encargos sociais. Todo mês alguém precisa baixar, conferir se mudou, abrir, transformar e carregar. Este projeto faz esse trabalho uma vez e expõe o resultado como API.

Sem a API6 etapas
  1. Portal da CAIXA
  2. Baixar o ZIP do mês
  3. Abrir XLSX e PDF
  4. Transformar à mão
  5. Carregar no seu banco
  6. Sua aplicação
Com a API3 etapas
  1. Portal da CAIXA
  2. SINAPI API
  3. Sua aplicação
O que dá para consultar

Nove capacidades, uma API

Cada cartão abaixo é uma rota que existe no repositório, com os parâmetros que ela aceita de verdade. A referência completa fica no OpenAPI que a própria instância publica.

GET/v1/insumos

Insumos

Lista e pesquisa insumos por descrição, código ou classificação. Cada item vem com os preços da competência nos três regimes, ao lado da unidade.

  • busca
  • codigo
  • classificacao
  • uf
  • ano
  • mes
GET/v1/composicoes

Composições

Mesma pesquisa para composições, filtrando por grupo. Os custos vêm acompanhados do percentual atribuído a São Paulo publicado pela CAIXA.

  • busca
  • codigo
  • grupo
  • uf
  • ano
  • mes
GET/v1/composicoes/{codigo}

Composição analítica

O detalhe de uma composição com todos os seus itens, coeficientes, situação e o percentual de mão de obra publicado para o regime e a UF consultados.

  • uf
  • regime
  • ano
  • mes
GET/v1/composicoes/{codigo}/insumos

Explosão de insumos

Percorre a composição recursivamente, consolida os insumos folha somando coeficientes, precifica item a item e devolve o custo calculado ao lado do publicado.

  • uf
  • regime
  • ano
  • mes
GET/v1/insumos/{codigo}/historico

Histórico por competência

Série de preços ou custos de um item ao longo das competências importadas, com recorte por período e limite configurável.

  • uf
  • regime
  • de
  • ate
  • limite
GET/v1/insumos/{codigo}/comparacoes

Comparação entre UFs

O valor do mesmo item em várias unidades federativas na mesma competência, de duas até as 27, na ordem em que você pedir.

  • ufs
  • regime
  • ano
  • mes
GET/v1/encargos-sociais/{uf}

Encargos sociais

Percentuais sobre a mão de obra por UF, regime e forma de remuneração. O detalhe abre os grupos A, B, C e D rubrica a rubrica.

  • ano
  • mes
GET/v1/competencias

Competências

Quais competências estão disponíveis naquela instância e quando foram publicadas. Útil para decidir se você precisa reprocessar algo.

POST/v1/webhooks

Webhooks

Cadastre um destino HTTPS e receba um POST assinado quando entrar uma nova publicação mensal ou uma nova vigência de encargos.

  • url
  • eventos
  • descricao
Experiência de integração

Feito para quem vai integrar

As rotas /v1 devolvem contratos estáveis, sem identificadores internos do banco, e todo o esquema é publicado como OpenAPI pela própria API.

OpenAPI 3 e Swagger UI

A instância serve a documentação interativa em /documentacao, gerada a partir dos mesmos esquemas que validam as requisições.

Versionamento explícito

Tudo que é dado fica sob o prefixo /v1. Fora dele só existem rotas operacionais: /saude, /prontidao, /metricas e /importacoes.

Paginação com metadados

Toda listagem devolve pagina, tamanho, total e totalPaginas. O tamanho vai até 100 itens por página.

Erros previsíveis

Parâmetro inválido devolve 400 com o campo e a mensagem. Excedeu o limite, 429 com tenteNovamenteEmMs. Ciclo entre composições, 409.

Busca textual indexada

As descrições de insumos e composições têm índice GIN pg_trgm, então busca por trecho não vira varredura de tabela.

Métricas Prometheus

/metricas expõe duração e total de requisições, competência mais recente, última publicação concluída e importações por status.

Erro é contrato, não surpresa

Parâmetro faltando devolve 400 apontando o campo exato e o motivo, no mesmo formato em todas as rotas.

400 Bad Request
{
  "erro": "Parâmetros inválidos",
  "detalhes": [
    { "campo": "regime", "mensagem": "Campo obrigatório" }
  ]
}
400
Parâmetro inválido
409
Ciclo na composição
429
Limite excedido
Arquitetura

O caminho que o dado percorre

O worker consulta diariamente a lista de relatórios mensais no portal da CAIXA. Cada arquivo novo é baixado, identificado por SHA-256 e importado da publicação mais antiga para a mais recente. O par arquivo + hash impede reprocessar o que já entrou, e um bloqueio distribuído no PostgreSQL garante que só um worker execute o pipeline, mesmo com várias réplicas.

  1. Portal da CAIXA

    ZIP mensal em XLSX + PDF de encargos sociais

    segue para

  2. Worker agendado

    pg-boss, verificação diária, SHA-256 por arquivo

    segue para

  3. Importadores

    referência, famílias e coeficientes, mão de obra, encargos

    segue para

  4. PostgreSQL

    competências, preços e custos por UF

    segue para

  5. API REST /v1

    Fastify, OpenAPI, paginação, filtros

    segue para

  6. Sua aplicação

    JSON, ou webhook assinado por evento

    fim do fluxo
Fair Source

Sua infraestrutura. Seus dados. Sua API.

O projeto inteiro é Fair Source sob FSL-1.1-ALv2: a API, o pipeline de importação, as migrations e os testes ficam públicos. Uso interno e self-hosting são permitidos; oferecer um serviço concorrente não é permitido nos dois primeiros anos de cada versão, que depois passa a Apache 2.0.

  • Docker com Docker Compose
  • PostgreSQL 16, já incluso no compose
  • Acesso de saída ao portal da CAIXA para a carga inicial
Ver no GitHubGuia de instalação

Distribuído sob licença FSL-1.1-ALv2

Subir com Docker Compose
git clone https://github.com/brunocopatti/sinapi-api.git
cd sinapi-api
cp .env.exemplo .env
docker compose up --build -d

Na primeira execução, o worker descobre e importa as publicações oficiais da mais antiga para a mais recente. Essa carga pode levar tempo; acompanhe com docker compose logs -f worker.

API hospedada

Não quer manter esse pipeline?

A versão hospedada é exatamente a mesma API deste repositório, operada por nós. Você recebe uma chave e uma URL base, e para de se preocupar com o dia em que a CAIXA mudar o formato da planilha.

Sem deploy

Nenhum container, nenhuma migration, nenhum volume para cuidar.

Sem carga inicial

As competências já estão importadas quando você recebe a chave. Nada de baixar XLSX para começar.

Pipeline mantido

Quando a CAIXA muda o layout do relatório, o conserto é nosso. É esse o trabalho que você está terceirizando.

Chave de API

Autenticação por X-API-Key com limites por plano, em vez de configurar hashes em variável de ambiente.

Self-hosted ou hospedado

A mesma API nos dois casos, sem recurso escondido atrás do plano pago. O que muda é quem opera.

Comparação entre rodar por conta própria e usar a API hospedada
RecursoSelf-hostedHospedado
Todos os endpoints /v1IncluídoIncluído
Código público sob FSL 1.1IncluídoIncluído
Webhooks assinadosIncluídoIncluído
InfraestruturaSuaNossa
Banco de dadosVocê operaIncluso
Carga inicial dos dadosVocê fazJá pronta
Manutenção do importadorVocê acompanhaPor nossa conta
Custo de hospedagemSeuIncluso
Chave de APIOpcional, você configuraIncluída
Limite de requisiçõesVocê definePelo plano
SuporteComunidade no GitHubE-mail
PreçoR$ 0A partir de R$ 0
Preços

Quer controle total? Rode você mesmo. Quer zero manutenção? Use o hospedado.

O self-hosted não é uma versão reduzida: é o mesmo software, com todos os endpoints. O que a versão hospedada vende é não precisar operar o pipeline de importação.

Self-hosted

R$ 0para sempre

Você roda, você controla. Código público sob FSL-1.1-ALv2.

Ver no GitHub
  • Requisições ilimitadas
  • Todos os endpoints /v1
  • Webhooks ilimitados
  • Limites definidos por você
  • Suporte da comunidade no GitHub

Grátis

R$ 0/mês

Para avaliar, prototipar ou tocar um projeto pequeno.

Criar conta grátis
  • 10.000 requisições/mês
  • 60 requisições/minuto
  • Todos os endpoints /v1
  • Chave de API
  • Suporte da comunidade
Recomendado

Pro

R$ 49,90/mês

Para o produto que já tem clientes consultando o tempo todo.

Em breve
  • 500.000 requisições/mês
  • 3.000 requisições/minuto
  • Todos os endpoints /v1
  • Até 3 destinos de webhook
  • Suporte por e-mail

Business

R$ 149,90/mês

Para ERPs consolidados e volumes altos de consulta.

Em breve
  • 2.000.000 requisições/mês
  • 6.000 requisições/minuto
  • Todos os endpoints /v1
  • Webhooks ilimitados
  • Suporte prioritário por e-mail

O Grátis e o self-hosted já estão disponíveis. Pro e Business ainda não abriram para contratação; até lá, criar a conta grátis já dá chave, cota e todos os endpoints.

  • Nenhum endpoint fica atrás de plano: a diferença é cota e limite por minuto, não recurso.
  • Passar da cota devolve 429 com o tempo de espera. Nada é cobrado além do plano contratado.

Volume acima do Business ou necessidade de contrato específico? Fale pelo repositório.

Onde isso entra

Quem integra dados de custo de obra

Cada caso abaixo aponta a rota que resolve o problema, para você conferir se o encaixe é real antes de escrever qualquer linha.

Software de orçamento

Monte a planilha orçamentária consultando composições por código e trazendo o custo já no regime e na UF da obra, sem manter uma cópia do SINAPI.

GET /v1/composicoes/{codigo}

ERP de construtora

Sincronize a base de itens por competência e use os webhooks para saber a hora exata de reprocessar os orçamentos abertos.

POST /v1/webhooks

Análise de custos

Compare o mesmo insumo entre várias UFs na mesma competência, ou acompanhe a série histórica de um item ao longo dos meses importados.

GET /v1/insumos/{codigo}/comparacoes

Auditoria e conferência

A explosão recursiva devolve o custo calculado ao lado do publicado e lista as pendências, o que permite conferir divergência item a item.

GET /v1/composicoes/{codigo}/insumos

Folha e encargos

Traga o percentual de encargos sociais por UF, regime e forma de remuneração, com o detalhamento rubrica a rubrica quando precisar justificar.

GET /v1/encargos-sociais/{uf}

Pesquisa acadêmica

Suba sua própria instância, importe as competências que interessam e consulte o conjunto inteiro sem depender de nenhum serviço externo.

GET /v1/competencias
Documentação

A documentação vem junto com a API

Não existe portal de documentação separado para sair do ar. A própria instância publica o OpenAPI e serve o Swagger UI, gerados dos mesmos esquemas que validam cada requisição. Suba o projeto e a referência completa está em /documentacao.

Exemplo de chamada

GET /v1/composicoes/101094?uf=SP&regime=SEM_DESONERACAO
Perguntas frequentes

O que costumam perguntar antes de integrar

Esta API é oficial da CAIXA?

Não. É um projeto independente, sem vínculo, endosso ou parceria com a CAIXA Econômica Federal. Os dados consultados são os relatórios que a CAIXA publica no portal do SINAPI, e a fonte oficial continua sendo esse portal.

O código é aberto para consulta e self-hosting?

Sim. O projeto é Fair Source sob FSL-1.1-ALv2: o código completo fica público e pode ser usado internamente e em self-hosting, mas não para oferecer um produto ou serviço concorrente durante os primeiros dois anos de cada versão. Depois disso, a versão passa automaticamente a Apache 2.0.

Posso rodar na minha própria infraestrutura?

Pode. O repositório traz Dockerfile e Docker Compose com API, worker e PostgreSQL. As migrations são aplicadas antes da subida, e o worker descobre o histórico disponível diretamente no portal da CAIXA.

Qual a diferença entre self-hosted e hospedado?

O software é o mesmo e nenhum endpoint fica reservado ao plano pago. No self-hosted você opera o banco, a atualização e a infraestrutura. No hospedado nós operamos, e o que você contrata é a manutenção do pipeline de importação mais a cota de uso.

De onde vêm os dados?

Do portal do SINAPI na CAIXA: os relatórios mensais distribuídos em ZIP com planilhas XLSX, e o PDF próprio de encargos sociais, que tem publicação separada e vale por um período em vez de por competência.

Como os dados são atualizados?

Um worker agendado consulta o portal diariamente, no horário definido em configuração. Publicações novas são registradas e processadas da mais antiga para a mais recente. Cada arquivo é identificado por SHA-256, então nada é reprocessado à toa, e uma retificação da mesma competência atualiza os dados existentes.

Preciso de autenticação?

No self-hosted é opcional: você liga a exigência de X-API-Key por variável de ambiente e cadastra os hashes SHA-256 das chaves aceitas. Na versão hospedada a chave é sempre exigida nas rotas /v1.

O que acontece se eu passar do limite de requisições?

A API responde 429 com um corpo JSON informando o erro e em quantos milissegundos você pode tentar de novo. As rotas de saúde, prontidão, métricas e documentação ficam fora do limite.

Posso usar comercialmente?

A FSL permite uso comercial interno e serviços profissionais prestados a um licenciado, mas proíbe oferecer um produto ou serviço concorrente durante os primeiros dois anos de cada versão. Os dados do SINAPI seguem os termos da CAIXA, que devem ser consultados no portal oficial.

Qual competência do SINAPI está disponível?

Depende da instância, porque cada uma importa o que foi carregado nela. A própria API responde isso: GET /v1/competencias lista o que existe, e GET /prontidao informa a competência mais recente e há quantos dias não entra publicação nova.

A API devolve um valor nacional?

Se você omitir a UF, sim, mas com uma ressalva importante que a resposta deixa explícita: a CAIXA publica preços por UF, não um valor nacional. A média é cálculo nosso, aritmética simples entre as UFs que têm valor naquela competência, e o campo ufsConsideradas informa quantas entraram na conta. Para orçamento oficial, consulte sempre com a UF da obra.

Como sou avisado de uma publicação nova?

Cadastrando um webhook. Quando o pipeline conclui uma importação mensal ou entra uma vigência nova de encargos, sua URL recebe um POST assinado com HMAC SHA-256. Falhas são retentadas com espera crescente de 1 até 60 minutos, por até 6 tentativas, e o histórico de entregas fica consultável.

Pare de integrar planilha.
Integre uma API.

O código está público, o pipeline de importação está pronto e a documentação sobe junto com o serviço. Comece pelo repositório.

Ver no GitHubLer o guia de instalação