{"openapi":"3.1.0","info":{"title":"SINPRES API","version":"1.1.0","description":"# SINPRES — Sistema Nacional de Preços Setoriais\n\nAPI pública e open-source para consulta de preços, insumos e composições por setor da economia brasileira.\n\n## Sobre o projeto\n\nO SINPRES organiza dados públicos de referência de preços de diferentes setores em uma API unificada. Cada setor possui seu próprio schema isolado no banco de dados, garantindo organização e escalabilidade.\n\n## Bases de dados disponíveis\n\n| Setor | Slug | Fonte | Itens | Status |\n|---|---|---|---|---|\n| **Construção Civil** | `civil-construction` | [SINAPI](https://www.caixa.gov.br/poder-publico/modernizacao-gestao/sinapi/) — Caixa Econômica Federal / IBGE | Insumos + Composições por UF e mês | Disponível |\n| **Saúde** | `health` | — | — | Em breve |\n| **Alimentação** | `food` | — | — | Em breve |\n| **Energia** | `energy` | — | — | Em breve |\n\n## Como usar\n\n### 1. Listar setores disponíveis\n```\nGET /api/v1/sectors\n```\n\n### 2. Buscar insumos por texto (full-text search em português)\n```\nGET /api/v1/sectors/civil-construction/items?search=tubo pvc\n```\n\n### 3. Buscar composições por texto\n```\nGET /api/v1/sectors/civil-construction/compositions?search=alvenaria\n```\n\n### 4. Detalhar composição com itens\n```\nGET /api/v1/sectors/civil-construction/compositions/7327\n```\n\n### 5. Filtrar por UF e mês de referência\n```\nGET /api/v1/sectors/civil-construction/items?state=SP&month=2026-03\n```\n\n### 6. Listar UFs disponíveis\n```\nGET /api/v1/sinapi/states\n```\n\n### 7. Listar meses de referência disponíveis\n```\nGET /api/v1/sinapi/reference-months?state=SP\n```\n\n## Unidades de medida disponíveis (Construção Civil)\n\n`KG`, `M`, `M2`, `M3`, `UN`, `L`, `CJ`, `JG`, `PAR`, `H`, `DIA`, `MES`, `T`, `MIL`, `CENTO`, `SC25KG`, `KWH`, `100M`, `310ML`, `MXMES`, `M2XMES`, `M/MES`, `UNXMES`\n\n## Substituição de códigos (`previousCode`)\n\nOs objetos de insumo e composição retornam o campo `previousCode`, que indica o código anterior quando a Caixa publica uma substituição explícita (ex: o código `11616` foi substituído pelo `11281`; nesse caso o registro do `11281` retorna `previousCode: 11616`).\n\nUse este campo para **detectar se o código que você está consultando é um substituto de outro**, permitindo migrar registros locais (orçamentos, planilhas, integrações) sempre que o SINAPI reorganiza seu catálogo. Quando `previousCode` é `null`, o código é original e não substitui nenhum código anterior.\n\n## Links\n\n- [GitHub — sinpres-api](https://github.com/sinpres/sinpres-api)\n- [TREE.IA](https://tree.ia.br?utm_source=sinpres&utm_medium=openapi&utm_campaign=api)\n","contact":{"name":"TREE.IA","url":"https://tree.ia.br?utm_source=sinpres&utm_medium=openapi&utm_campaign=api"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://api.sinpres.com.br","description":"Production server"}],"tags":[{"name":"Health","description":"Verificação de status da API."},{"name":"Sectors","description":"Setores da economia disponíveis para consulta. Cada setor possui sua própria base de dados isolada com categorias e itens. Use o `slug` do setor para acessar seus dados."},{"name":"Categories","description":"Categorias de itens dentro de um setor. Permite organizar os itens por tipo (ex: materiais hidráulicos, elétricos, estruturais, etc.)."},{"name":"Items","description":"Itens (insumos) de um setor. Suporta busca textual em português (full-text search), filtro por unidade de medida, UF, mês de referência, regime tributário e paginação. Cada item possui código, descrição, unidade, preço unitário, normas técnicas, informações gerais e imagem de referência."},{"name":"Compositions","description":"Composições (serviços completos) de um setor. No SINAPI, uma composição representa um serviço de construção civil com seus insumos e sub-composições, coeficientes e preços resultantes. Suporta busca textual, filtros por unidade, UF, mês e regime tributário."},{"name":"SINAPI","description":"Metadados e informações auxiliares sobre os dados SINAPI, como UFs disponíveis e meses de referência."}],"components":{"schemas":{},"parameters":{}},"paths":{"/health":{"get":{"tags":["Health"],"responses":{"200":{"description":"API is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}},"required":["status"]}}}}}}},"/api/v1/sectors":{"get":{"tags":["Sectors"],"summary":"Listar setores","description":"Retorna todos os setores disponíveis para consulta. Use o campo `slug` do setor para acessar suas categorias e itens.","responses":{"200":{"description":"Lista de setores disponíveis","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"schemaName":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","slug","name","description","schemaName","createdAt"]}}},"required":["data"]}}}}}}},"/api/v1/sectors/{slug}":{"get":{"tags":["Sectors"],"summary":"Detalhar setor","description":"Retorna os detalhes de um setor específico pelo seu slug. Exemplo: `civil-construction`.","parameters":[{"schema":{"type":"string","example":"civil-construction"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Detalhes do setor","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"number"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"schemaName":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","slug","name","description","schemaName","createdAt"]}},"required":["data"]}}}},"404":{"description":"Setor não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/sectors/{slug}/categories":{"get":{"tags":["Categories"],"summary":"Listar categorias de um setor","description":"Retorna todas as categorias de itens disponíveis dentro de um setor específico.","parameters":[{"schema":{"type":"string","example":"civil-construction"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Lista de categorias do setor","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"slug":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","slug","name","createdAt"]}}},"required":["data"]}}}},"404":{"description":"Setor não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/sectors/{slug}/items":{"get":{"tags":["Items"],"summary":"Buscar itens de um setor","description":"Retorna uma lista paginada de itens (insumos) de um setor.\n\n**Busca textual:** Use o parâmetro `search` para buscar por descrição ou informações gerais. A busca utiliza full-text search em português (PostgreSQL `tsvector`).\n\n**Filtro por unidade:** Use o parâmetro `unit` para filtrar por unidade de medida (ex: KG, M, M2, UN).\n\n**Filtro por UF:** Use o parâmetro `state` para filtrar por estado (ex: SP, RJ, MG).\n\n**Filtro por mês:** Use o parâmetro `month` no formato AAAA-MM. Se não informado, retorna o último mês disponível.\n\n**Regime tributário:** Use o parâmetro `is_desonerated` para filtrar por desoneração. Default: `false`.\n\n**Paginação:** Use `page` e `limit` para controlar a paginação. Máximo de 100 itens por página.\n\n**Performance:** Use `include_total=false` para evitar `COUNT(*)` e `compact=true` para retornar payload reduzido.","parameters":[{"schema":{"type":"string","example":"civil-construction"},"required":true,"name":"slug","in":"path"},{"schema":{"type":"integer","minimum":1,"default":1,"example":1,"description":"Número da página"},"required":false,"description":"Número da página","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"example":50,"description":"Itens por página (máx. 100)"},"required":false,"description":"Itens por página (máx. 100)","name":"limit","in":"query"},{"schema":{"type":"boolean","default":true,"example":true,"description":"Inclui total e totalPages na paginação. Use false para evitar COUNT(*) em listagens grandes."},"required":false,"description":"Inclui total e totalPages na paginação. Use false para evitar COUNT(*) em listagens grandes.","name":"include_total","in":"query"},{"schema":{"type":"string","example":"tubo pvc","description":"Termo de busca (full-text search em português)"},"required":false,"description":"Termo de busca (full-text search em português)","name":"search","in":"query"},{"schema":{"type":"string","example":"KG","description":"Filtrar por unidade de medida"},"required":false,"description":"Filtrar por unidade de medida","name":"unit","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"SP","description":"UF de 2 letras (ex: SP, RJ, MG)"},"required":false,"description":"UF de 2 letras (ex: SP, RJ, MG)","name":"state","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$","example":"2026-03","description":"Mês de referência no formato AAAA-MM"},"required":false,"description":"Mês de referência no formato AAAA-MM","name":"month","in":"query"},{"schema":{"type":"boolean","default":false,"example":false,"description":"Regime tributário: true = desonerado, false = não desonerado"},"required":false,"description":"Regime tributário: true = desonerado, false = não desonerado","name":"is_desonerated","in":"query"},{"schema":{"type":"boolean","default":false,"example":false,"description":"Retorna payload reduzido para listagens de alta performance"},"required":false,"description":"Retorna payload reduzido para listagens de alta performance","name":"compact","in":"query"}],"responses":{"200":{"description":"Lista paginada de itens com metadados de paginação","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"categoryId":{"type":"number","nullable":true},"code":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"stateCode":{"type":"string","nullable":true,"minLength":2,"maxLength":2},"referenceMonth":{"type":"string","nullable":true,"minLength":7,"maxLength":7},"isDesonerated":{"type":"boolean","nullable":true},"unitPrice":{"type":"number","nullable":true},"technicalStandards":{"type":"string","nullable":true},"generalInfo":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true},"metadata":{"nullable":true},"sourceUpdatedAt":{"type":"string","nullable":true},"previousCode":{"type":"number","nullable":true,"example":null,"description":"Código anterior deste insumo quando houve substituição publicada pela Caixa. Null se o código é original. Use para migrar registros locais quando o SINAPI substitui um código por outro."},"createdAt":{"type":"string"}},"required":["id","categoryId","code","description","unit","stateCode","referenceMonth","isDesonerated","unitPrice","technicalStandards","generalInfo","imageUrl","sourceUpdatedAt","previousCode","createdAt"]},{"type":"object","properties":{"id":{"type":"number"},"categoryId":{"type":"number","nullable":true},"code":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"stateCode":{"type":"string","nullable":true,"minLength":2,"maxLength":2},"referenceMonth":{"type":"string","nullable":true,"minLength":7,"maxLength":7},"isDesonerated":{"type":"boolean","nullable":true},"unitPrice":{"type":"number","nullable":true},"previousCode":{"type":"number","nullable":true}},"required":["id","categoryId","code","description","unit","stateCode","referenceMonth","isDesonerated","unitPrice","previousCode"]}]}},"meta":{"type":"object","properties":{"total":{"type":"number","nullable":true},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number","nullable":true},"hasNextPage":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasNextPage"]}},"required":["data","meta"]}}}},"404":{"description":"Setor não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/sectors/{slug}/items/{code}":{"get":{"tags":["Items"],"summary":"Detalhar item por código","description":"Retorna os detalhes completos de um item (insumo) pelo seu código de referência. Para Construção Civil, o código corresponde ao código SINAPI. Aceita filtros opcionais de UF, mês e regime tributário.","parameters":[{"schema":{"type":"string","example":"civil-construction"},"required":true,"name":"slug","in":"path"},{"schema":{"type":"number","nullable":true,"example":34},"required":false,"name":"code","in":"path"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"SP","description":"UF de 2 letras (ex: SP, RJ, MG)"},"required":false,"description":"UF de 2 letras (ex: SP, RJ, MG)","name":"state","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$","example":"2026-03","description":"Mês de referência no formato AAAA-MM"},"required":false,"description":"Mês de referência no formato AAAA-MM","name":"month","in":"query"},{"schema":{"type":"boolean","default":false,"example":false,"description":"Regime tributário: true = desonerado, false = não desonerado"},"required":false,"description":"Regime tributário: true = desonerado, false = não desonerado","name":"is_desonerated","in":"query"}],"responses":{"200":{"description":"Detalhes do item","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"number"},"categoryId":{"type":"number","nullable":true},"code":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"stateCode":{"type":"string","nullable":true,"minLength":2,"maxLength":2},"referenceMonth":{"type":"string","nullable":true,"minLength":7,"maxLength":7},"isDesonerated":{"type":"boolean","nullable":true},"unitPrice":{"type":"number","nullable":true},"technicalStandards":{"type":"string","nullable":true},"generalInfo":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true},"metadata":{"nullable":true},"sourceUpdatedAt":{"type":"string","nullable":true},"previousCode":{"type":"number","nullable":true,"example":null,"description":"Código anterior deste insumo quando houve substituição publicada pela Caixa. Null se o código é original. Use para migrar registros locais quando o SINAPI substitui um código por outro."},"createdAt":{"type":"string"}},"required":["id","categoryId","code","description","unit","stateCode","referenceMonth","isDesonerated","unitPrice","technicalStandards","generalInfo","imageUrl","sourceUpdatedAt","previousCode","createdAt"]}},"required":["data"]}}}},"404":{"description":"Item ou setor não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/sectors/{slug}/items/bulk":{"post":{"tags":["Items"],"summary":"Buscar múltiplos insumos por código","description":"Retorna múltiplos insumos em uma única request, preservando a ordem de entrada e evitando N+1 no consumidor. Limite máximo de 100 consultas por request.","parameters":[{"schema":{"type":"string","example":"civil-construction"},"required":true,"name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^\\d+$","example":"34","description":"Código SINAPI do insumo"},"state":{"type":"string","minLength":2,"maxLength":2,"example":"SP","description":"UF de 2 letras"},"month":{"type":"string","pattern":"^\\d{4}-\\d{2}$","example":"2026-03","description":"Mês de referência no formato AAAA-MM"},"is_desonerated":{"type":"boolean","example":false,"description":"Regime tributário"}},"required":["code","state","month","is_desonerated"]},"maxItems":100}},"required":["queries"]}}}},"responses":{"200":{"description":"Resultados dos insumos solicitados","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"found":{"type":"boolean"},"item":{"type":"object","properties":{"id":{"type":"number"},"categoryId":{"type":"number","nullable":true},"code":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"stateCode":{"type":"string","nullable":true,"minLength":2,"maxLength":2},"referenceMonth":{"type":"string","nullable":true,"minLength":7,"maxLength":7},"isDesonerated":{"type":"boolean","nullable":true},"unitPrice":{"type":"number","nullable":true},"technicalStandards":{"type":"string","nullable":true},"generalInfo":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true},"metadata":{"nullable":true},"sourceUpdatedAt":{"type":"string","nullable":true},"previousCode":{"type":"number","nullable":true,"example":null,"description":"Código anterior deste insumo quando houve substituição publicada pela Caixa. Null se o código é original. Use para migrar registros locais quando o SINAPI substitui um código por outro."},"createdAt":{"type":"string"}},"required":["id","categoryId","code","description","unit","stateCode","referenceMonth","isDesonerated","unitPrice","technicalStandards","generalInfo","imageUrl","sourceUpdatedAt","previousCode","createdAt"]},"reason":{"type":"string","enum":["no_price_for_coordinate"]}},"required":["code","found"]}}},"required":["results"]}}}},"400":{"description":"Payload inválido ou acima do limite de 100 consultas","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Setor não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/sectors/{slug}/compositions":{"get":{"tags":["Compositions"],"summary":"Buscar composições de um setor","description":"Retorna uma lista paginada de composições (serviços SINAPI) de um setor.\n\n**Busca textual:** Use o parâmetro `search` para buscar por descrição. A busca utiliza full-text search em português (PostgreSQL `tsvector`).\n\n**Filtro por unidade:** Use o parâmetro `unit` para filtrar por unidade de medida (ex: M2, M3, UN).\n\n**Filtro por UF:** Use o parâmetro `state` para filtrar por estado (ex: SP, RJ, MG).\n\n**Filtro por mês:** Use o parâmetro `month` no formato AAAA-MM. Se não informado, retorna o último mês disponível.\n\n**Regime tributário:** Use o parâmetro `is_desonerated` para filtrar por desoneração. Default: `false`.\n\n**Paginação:** Use `page` e `limit` para controlar a paginação. Máximo de 100 itens por página.\n\n**Performance:** Use `include_total=false` para evitar `COUNT(*)` e `compact=true` para retornar payload reduzido.","parameters":[{"schema":{"type":"string","example":"civil-construction"},"required":true,"name":"slug","in":"path"},{"schema":{"type":"integer","minimum":1,"default":1,"example":1,"description":"Número da página"},"required":false,"description":"Número da página","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"example":50,"description":"Itens por página (máx. 100)"},"required":false,"description":"Itens por página (máx. 100)","name":"limit","in":"query"},{"schema":{"type":"boolean","default":true,"example":true,"description":"Inclui total e totalPages na paginação. Use false para evitar COUNT(*) em listagens grandes."},"required":false,"description":"Inclui total e totalPages na paginação. Use false para evitar COUNT(*) em listagens grandes.","name":"include_total","in":"query"},{"schema":{"type":"string","example":"alvenaria","description":"Termo de busca (full-text search em português)"},"required":false,"description":"Termo de busca (full-text search em português)","name":"search","in":"query"},{"schema":{"type":"string","example":"M2","description":"Filtrar por unidade de medida"},"required":false,"description":"Filtrar por unidade de medida","name":"unit","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"SP","description":"UF de 2 letras (ex: SP, RJ, MG)"},"required":false,"description":"UF de 2 letras (ex: SP, RJ, MG)","name":"state","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$","example":"2026-03","description":"Mês de referência no formato AAAA-MM"},"required":false,"description":"Mês de referência no formato AAAA-MM","name":"month","in":"query"},{"schema":{"type":"boolean","default":false,"example":false,"description":"Regime tributário: true = desonerado, false = não desonerado"},"required":false,"description":"Regime tributário: true = desonerado, false = não desonerado","name":"is_desonerated","in":"query"},{"schema":{"type":"boolean","default":false,"example":false,"description":"Retorna payload reduzido para listagens de alta performance"},"required":false,"description":"Retorna payload reduzido para listagens de alta performance","name":"compact","in":"query"}],"responses":{"200":{"description":"Lista paginada de composições com metadados de paginação","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"stateCode":{"type":"string","nullable":true,"minLength":2,"maxLength":2},"referenceMonth":{"type":"string","nullable":true,"minLength":7,"maxLength":7},"isDesonerated":{"type":"boolean","nullable":true},"baseUnitCost":{"type":"number","nullable":true},"sourceUpdatedAt":{"type":"string","nullable":true},"previousCode":{"type":"number","nullable":true,"example":null,"description":"Código anterior desta composição quando houve substituição publicada pela Caixa. Null se o código é original. Use para migrar registros locais quando o SINAPI substitui um código por outro."},"createdAt":{"type":"string"}},"required":["id","code","description","unit","stateCode","referenceMonth","isDesonerated","baseUnitCost","sourceUpdatedAt","previousCode","createdAt"]},{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"stateCode":{"type":"string","nullable":true,"minLength":2,"maxLength":2},"referenceMonth":{"type":"string","nullable":true,"minLength":7,"maxLength":7},"isDesonerated":{"type":"boolean","nullable":true},"baseUnitCost":{"type":"number","nullable":true},"previousCode":{"type":"number","nullable":true}},"required":["id","code","description","unit","stateCode","referenceMonth","isDesonerated","baseUnitCost","previousCode"]}]}},"meta":{"type":"object","properties":{"total":{"type":"number","nullable":true},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number","nullable":true},"hasNextPage":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasNextPage"]}},"required":["data","meta"]}}}},"404":{"description":"Setor não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/sectors/{slug}/compositions/{code}":{"get":{"tags":["Compositions"],"summary":"Detalhar composição por código","description":"Retorna os detalhes completos de uma composição (serviço SINAPI) pelo seu código de referência, incluindo todos os itens que a compõem (insumos e sub-composições) com coeficientes e preços.","parameters":[{"schema":{"type":"string","example":"civil-construction"},"required":true,"name":"slug","in":"path"},{"schema":{"type":"number","nullable":true,"example":7327},"required":false,"name":"code","in":"path"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"SP","description":"UF de 2 letras (ex: SP, RJ, MG)"},"required":false,"description":"UF de 2 letras (ex: SP, RJ, MG)","name":"state","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$","example":"2026-03","description":"Mês de referência no formato AAAA-MM"},"required":false,"description":"Mês de referência no formato AAAA-MM","name":"month","in":"query"},{"schema":{"type":"boolean","default":false,"example":false,"description":"Regime tributário: true = desonerado, false = não desonerado"},"required":false,"description":"Regime tributário: true = desonerado, false = não desonerado","name":"is_desonerated","in":"query"}],"responses":{"200":{"description":"Detalhes da composição com itens","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"stateCode":{"type":"string","nullable":true,"minLength":2,"maxLength":2},"referenceMonth":{"type":"string","nullable":true,"minLength":7,"maxLength":7},"isDesonerated":{"type":"boolean","nullable":true},"baseUnitCost":{"type":"number","nullable":true},"sourceUpdatedAt":{"type":"string","nullable":true},"previousCode":{"type":"number","nullable":true,"example":null,"description":"Código anterior desta composição quando houve substituição publicada pela Caixa. Null se o código é original. Use para migrar registros locais quando o SINAPI substitui um código por outro."},"createdAt":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"itemType":{"type":"string","enum":["INPUT","SUB_COMPOSITION"]},"code":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"resourceType":{"type":"string","nullable":true,"enum":["MATERIAL","LABOR","EQUIPMENT",null]},"coefficient":{"type":"string"},"unitPrice":{"type":"number"},"totalPrice":{"type":"number"}},"required":["itemType","code","description","unit","resourceType","coefficient","unitPrice","totalPrice"]}}},"required":["id","code","description","unit","stateCode","referenceMonth","isDesonerated","baseUnitCost","sourceUpdatedAt","previousCode","createdAt","items"]}},"required":["data"]}}}},"404":{"description":"Composição ou setor não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/sectors/{slug}/compositions/bulk":{"post":{"tags":["Compositions"],"summary":"Buscar múltiplas composições por código","description":"Retorna múltiplas composições em uma única request, preservando a ordem de entrada. Não retorna os itens da composição; use o endpoint expanded para árvore recursiva.","parameters":[{"schema":{"type":"string","example":"civil-construction"},"required":true,"name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^\\d+$","example":"7327","description":"Código SINAPI da composição"},"state":{"type":"string","minLength":2,"maxLength":2,"example":"SP","description":"UF de 2 letras"},"month":{"type":"string","pattern":"^\\d{4}-\\d{2}$","example":"2026-03","description":"Mês de referência no formato AAAA-MM"},"is_desonerated":{"type":"boolean","example":false,"description":"Regime tributário"}},"required":["code","state","month","is_desonerated"]},"maxItems":100}},"required":["queries"]}}}},"responses":{"200":{"description":"Resultados das composições solicitadas","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"found":{"type":"boolean"},"composition":{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"stateCode":{"type":"string","nullable":true,"minLength":2,"maxLength":2},"referenceMonth":{"type":"string","nullable":true,"minLength":7,"maxLength":7},"isDesonerated":{"type":"boolean","nullable":true},"baseUnitCost":{"type":"number","nullable":true},"sourceUpdatedAt":{"type":"string","nullable":true},"previousCode":{"type":"number","nullable":true,"example":null,"description":"Código anterior desta composição quando houve substituição publicada pela Caixa. Null se o código é original. Use para migrar registros locais quando o SINAPI substitui um código por outro."},"createdAt":{"type":"string"}},"required":["id","code","description","unit","stateCode","referenceMonth","isDesonerated","baseUnitCost","sourceUpdatedAt","previousCode","createdAt"]},"reason":{"type":"string","enum":["no_price_for_coordinate"]}},"required":["code","found"]}}},"required":["results"]}}}},"400":{"description":"Payload inválido ou acima do limite de 100 consultas","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Setor não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/sectors/{slug}/compositions/{code}/expanded":{"get":{"tags":["Compositions"],"summary":"Expandir composição recursivamente","description":"Resolve a árvore de uma composição no servidor, incluindo insumos e sub-composições até a profundidade solicitada. O limite máximo aplicado pelo servidor é 8.","parameters":[{"schema":{"type":"string","example":"civil-construction"},"required":true,"name":"slug","in":"path"},{"schema":{"type":"number","nullable":true,"example":87514},"required":false,"name":"code","in":"path"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"SP","description":"UF de 2 letras"},"required":true,"description":"UF de 2 letras","name":"state","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$","example":"2026-03","description":"Mês de referência no formato AAAA-MM"},"required":true,"description":"Mês de referência no formato AAAA-MM","name":"month","in":"query"},{"schema":{"type":"boolean","example":false,"description":"Regime tributário"},"required":true,"description":"Regime tributário","name":"is_desonerated","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":5,"example":5,"description":"Profundidade máxima da árvore. Valores acima de 8 são limitados pelo servidor."},"required":false,"description":"Profundidade máxima da árvore. Valores acima de 8 são limitados pelo servidor.","name":"max_depth","in":"query"}],"responses":{"200":{"description":"Árvore expandida da composição","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":"string"},"unit":{"type":"string","nullable":true},"depth":{"type":"number"},"coefficient":{"type":"string","nullable":true},"item_type":{"type":"string","enum":["COMPOSITION","INPUT","SUB_COMPOSITION"]},"unit_price":{"type":"number","nullable":true},"items":{"type":"array","items":{"nullable":true},"description":"Nós filhos da composição expandida, com o mesmo formato do nó atual."},"truncated":{"type":"boolean"}},"required":["code","description","unit","depth","coefficient","item_type","unit_price","items","truncated"]}},"required":["data"]}}}},"404":{"description":"Composição ou setor não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/sinapi/states":{"get":{"tags":["SINAPI"],"summary":"Listar UFs disponíveis","description":"Retorna a lista de UFs (estados) que possuem dados de insumos ou composições no SINAPI.","responses":{"200":{"description":"Lista de UFs disponíveis","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2}}},"required":["data"]}}}}}}},"/api/v1/sinapi/reference-months":{"get":{"tags":["SINAPI"],"summary":"Listar meses de referência disponíveis","description":"Retorna a lista de meses de referência disponíveis, ordenados do mais recente para o mais antigo. Opcionalmente filtre por UF.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"SP","description":"UF de 2 letras para filtrar meses disponíveis"},"required":false,"description":"UF de 2 letras para filtrar meses disponíveis","name":"state","in":"query"}],"responses":{"200":{"description":"Lista de meses de referência disponíveis","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}}},"required":["data"]}}}}}}}}}