{"openapi":"3.0.3","info":{"title":"API Catálogo","version":"2.1.0","description":"Busca inteligente sobre qualquer lista de itens, organizada em coleções (padrao, vagas). Só o título é obrigatório; papéis por coleção (preço, categoria, código, identificador, data, ativo); tipos inferidos; filtros por qualquer campo. /api/produtos/... e /api/itens/... são apelidos da coleção padrão (ou da coleção indicada em X-Colecao / ?colecao=). Chaves com escopo (leitura/escrita/admin) em x-api-key ou Bearer; limite de requisições por cliente (X-RateLimit-*, 429 + Retry-After)."},"servers":[{"url":"https://103-199-185-217.sslip.io"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key"},"Bearer":{"type":"http","scheme":"bearer"}},"schemas":{"Item":{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true},"RespostaBusca":{"type":"object","properties":{"ok":{"type":"boolean"},"consulta":{"type":"object","properties":{"original":{"type":"string"},"texto":{"type":"string"},"termos":{"type":"array","items":{"type":"string"}},"interpretada":{"type":"string"},"correcoes":{"type":"array","items":{"type":"object","properties":{"de":{"type":"string"},"para":{"type":"string"},"tipo":{"type":"string"}}}},"termos_sem_correspondencia":{"type":"array","items":{"type":"string"}},"filtros":{"type":"object"},"filtros_ignorados":{"type":"array","items":{"type":"string"}},"filtros_extraidos":{"type":"object"}}},"total":{"type":"integer"},"pagina":{"type":"integer"},"por_pagina":{"type":"integer"},"total_paginas":{"type":"integer"},"itens":{"type":"array","items":{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true}},"sugestoes":{"type":"array","items":{"type":"string"}},"facetas":{"type":"object"},"tempo_ms":{"type":"number"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]},{}],"paths":{"/api/mcp":{"post":{"tags":["MCP (agente de IA)"],"summary":"Servidor MCP (streamable-http, sem sessão): todas as funcionalidades como ferramentas — buscar, itens, importar, sinônimos, config, fontes, chaves. Envie JSON-RPC 2.0 (initialize, tools/list, tools/call) com Authorization: Bearer <chave>; /mcp é apelido, /mcp/{colecao} prende a uma coleção. GET devolve a lista de ferramentas do escopo.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":["integer","string"]},"method":{"type":"string","enum":["initialize","tools/list","tools/call","resources/list","resources/read","prompts/list","prompts/get"]},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"Resposta JSON-RPC"}}},"get":{"tags":["MCP (agente de IA)"],"summary":"Descrição do servidor MCP e ferramentas disponíveis para a chave","responses":{"200":{"description":"OK"}}}},"/api/mcp/{colecao}":{"post":{"tags":["MCP (agente de IA)"],"summary":"Servidor MCP preso a uma coleção (ferramentas sem o parâmetro colecao)","parameters":[{"name":"colecao","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resposta JSON-RPC"}}}},"/api/colecoes":{"get":{"tags":["Coleções"],"summary":"Listar coleções","responses":{"200":{"description":"Lista"}}},"post":{"tags":["Coleções"],"summary":"Criar coleção (admin): { nome, titulo, dominio, papeis }","responses":{"201":{"description":"Criada"}}}},"/api/colecoes/{nome}":{"get":{"tags":["Coleções"],"summary":"Resumo da coleção","parameters":[{"name":"nome","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"delete":{"tags":["Coleções"],"summary":"Remover coleção (admin; vai para data/lixeira)","parameters":[{"name":"nome","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/chaves":{"get":{"tags":["Chaves"],"summary":"Listar chaves (admin)","responses":{"200":{"description":"Lista"}}},"post":{"tags":["Chaves"],"summary":"Criar chave (admin): { nome, escopo: leitura|escrita|admin, colecoes: [\"*\"] }","responses":{"201":{"description":"A chave só é mostrada nesta resposta"}}}},"/api/chaves/{id}":{"delete":{"tags":["Chaves"],"summary":"Revogar chave (admin)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/dominios":{"get":{"tags":["Coleções"],"summary":"Pacotes de domínio disponíveis (sinônimos/stopwords/pesos)","responses":{"200":{"description":"Lista"}}}},"/api/v1/geral/produtos/":{"post":{"tags":["Omie"],"summary":"Chamada no estilo Omie (coleção padrão): { call: ListarProdutos|BuscarProdutos|ConsultarProduto|IncluirProduto|AlterarProduto|UpsertProduto|IncluirProdutosLote|ExcluirProduto, app_key, app_secret, param: [{...}] }","responses":{"200":{"description":"Formato Omie (produto_servico_cadastro)"}}}},"/api/colecoes/{nome}/buscar":{"get":{"tags":["Coleção {nome}"],"summary":"Buscar itens (texto livre + filtros por qualquer campo)","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Texto da busca (pode ser a frase inteira do cliente). Corrige digitação e pronúncia (motocera → motosserra), plural, acentos e sinônimos; \"campo:valor\" e expressões como \"até 500 mil\", \"2 quartos\", \"esta semana\" viram filtros."},{"name":"filtros","in":"query","schema":{"type":"string"},"description":"JSON {campo: valor} com filtros por qualquer campo (nome ou slug, veja /campos). Alternativa: passar slug=valor direto na query. Valores: \"a|b\" OU, \"=x\" exato, \">100\", \"<100\", \"100-200\" (números e datas dd/mm/aaaa), listas casam por parte."},{"name":"modo","in":"query","schema":{"type":"string","enum":["auto","todos","qualquer"],"default":"auto"},"description":"auto: itens que casam o maior número de termos; todos: exige todos; qualquer: basta um."},{"name":"fuzzy","in":"query","schema":{"type":"boolean","default":true},"description":"false desliga a correção de digitação."},{"name":"extrair_filtros","in":"query","schema":{"type":"boolean","default":true},"description":"false desliga a extração de filtros da frase."},{"name":"incluir_relacionados","in":"query","schema":{"type":"boolean","default":false},"description":"Por padrão \"motosserra\" devolve as motosserras e resume em `relacionados` o que só cita o termo (lâmina, corrente, óleo…). true junta tudo numa lista só."},{"name":"tolerancia","in":"query","schema":{"type":"integer","default":0},"description":"No modo auto, quantos termos a menos que o melhor resultado ainda entram."},{"name":"min_score","in":"query","schema":{"type":"number","default":0},"description":"Descarta resultados abaixo desta relevância (0..1)."},{"name":"preco_min","in":"query","schema":{"type":"number"},"description":"Mínimo do campo com papel preço."},{"name":"preco_max","in":"query","schema":{"type":"number"},"description":"Máximo do campo com papel preço."},{"name":"ids","in":"query","schema":{"type":"string"},"description":"Lista de ids separados por vírgula."},{"name":"codigos","in":"query","schema":{"type":"string"},"description":"Lista de códigos (papel código) separados por vírgula."},{"name":"ordenar","in":"query","schema":{"type":"string"},"description":"relevancia | titulo | preco_asc | preco_desc | <slug do campo> | -<slug> (decrescente)."},{"name":"pagina","in":"query","schema":{"type":"integer","default":1}},{"name":"por_pagina","in":"query","schema":{"type":"integer","default":50,"maximum":500}},{"name":"facetas","in":"query","schema":{"type":"boolean","default":true},"description":"Contagens por campo categórico/lista/booleano e faixas para números/datas."},{"name":"facetas_campos","in":"query","schema":{"type":"string"},"description":"Quais campos contar, separados por vírgula."},{"name":"campos","in":"query","schema":{"type":"string"},"description":"Campos a devolver (nome ou slug), separados por vírgula. Ex.: titulo,cidade,salario"},{"name":"apenas_ativos","in":"query","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"consulta":{"type":"object","properties":{"original":{"type":"string"},"texto":{"type":"string"},"termos":{"type":"array","items":{"type":"string"}},"interpretada":{"type":"string"},"correcoes":{"type":"array","items":{"type":"object","properties":{"de":{"type":"string"},"para":{"type":"string"},"tipo":{"type":"string"}}}},"termos_sem_correspondencia":{"type":"array","items":{"type":"string"}},"filtros":{"type":"object"},"filtros_ignorados":{"type":"array","items":{"type":"string"}},"filtros_extraidos":{"type":"object"}}},"total":{"type":"integer"},"pagina":{"type":"integer"},"por_pagina":{"type":"integer"},"total_paginas":{"type":"integer"},"itens":{"type":"array","items":{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true}},"sugestoes":{"type":"array","items":{"type":"string"}},"facetas":{"type":"object"},"tempo_ms":{"type":"number"}}}}}}}},"post":{"tags":["Coleção {nome}"],"summary":"Buscar (parâmetros no corpo JSON)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string"},"filtros":{"type":"string"},"modo":{"type":"string","enum":["auto","todos","qualquer"],"default":"auto"},"fuzzy":{"type":"boolean","default":true},"extrair_filtros":{"type":"boolean","default":true},"incluir_relacionados":{"type":"boolean","default":false},"tolerancia":{"type":"integer","default":0},"min_score":{"type":"number","default":0},"preco_min":{"type":"number"},"preco_max":{"type":"number"},"ids":{"type":"string"},"codigos":{"type":"string"},"ordenar":{"type":"string"},"pagina":{"type":"integer","default":1},"por_pagina":{"type":"integer","default":50,"maximum":500},"facetas":{"type":"boolean","default":true},"facetas_campos":{"type":"string"},"campos":{"type":"string"},"apenas_ativos":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"consulta":{"type":"object","properties":{"original":{"type":"string"},"texto":{"type":"string"},"termos":{"type":"array","items":{"type":"string"}},"interpretada":{"type":"string"},"correcoes":{"type":"array","items":{"type":"object","properties":{"de":{"type":"string"},"para":{"type":"string"},"tipo":{"type":"string"}}}},"termos_sem_correspondencia":{"type":"array","items":{"type":"string"}},"filtros":{"type":"object"},"filtros_ignorados":{"type":"array","items":{"type":"string"}},"filtros_extraidos":{"type":"object"}}},"total":{"type":"integer"},"pagina":{"type":"integer"},"por_pagina":{"type":"integer"},"total_paginas":{"type":"integer"},"itens":{"type":"array","items":{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true}},"sugestoes":{"type":"array","items":{"type":"string"}},"facetas":{"type":"object"},"tempo_ms":{"type":"number"}}}}}}}}},"/api/colecoes/{nome}/itens":{"get":{"tags":["Coleção {nome}"],"summary":"Listar itens (sem texto, com filtros e paginação)","parameters":[{"name":"filtros","in":"query","schema":{"type":"string"},"description":"JSON {campo: valor} com filtros por qualquer campo (nome ou slug, veja /campos). Alternativa: passar slug=valor direto na query. Valores: \"a|b\" OU, \"=x\" exato, \">100\", \"<100\", \"100-200\" (números e datas dd/mm/aaaa), listas casam por parte."},{"name":"modo","in":"query","schema":{"type":"string","enum":["auto","todos","qualquer"],"default":"auto"},"description":"auto: itens que casam o maior número de termos; todos: exige todos; qualquer: basta um."},{"name":"fuzzy","in":"query","schema":{"type":"boolean","default":true},"description":"false desliga a correção de digitação."},{"name":"extrair_filtros","in":"query","schema":{"type":"boolean","default":true},"description":"false desliga a extração de filtros da frase."},{"name":"incluir_relacionados","in":"query","schema":{"type":"boolean","default":false},"description":"Por padrão \"motosserra\" devolve as motosserras e resume em `relacionados` o que só cita o termo (lâmina, corrente, óleo…). true junta tudo numa lista só."},{"name":"tolerancia","in":"query","schema":{"type":"integer","default":0},"description":"No modo auto, quantos termos a menos que o melhor resultado ainda entram."},{"name":"min_score","in":"query","schema":{"type":"number","default":0},"description":"Descarta resultados abaixo desta relevância (0..1)."},{"name":"preco_min","in":"query","schema":{"type":"number"},"description":"Mínimo do campo com papel preço."},{"name":"preco_max","in":"query","schema":{"type":"number"},"description":"Máximo do campo com papel preço."},{"name":"ids","in":"query","schema":{"type":"string"},"description":"Lista de ids separados por vírgula."},{"name":"codigos","in":"query","schema":{"type":"string"},"description":"Lista de códigos (papel código) separados por vírgula."},{"name":"ordenar","in":"query","schema":{"type":"string"},"description":"relevancia | titulo | preco_asc | preco_desc | <slug do campo> | -<slug> (decrescente)."},{"name":"pagina","in":"query","schema":{"type":"integer","default":1}},{"name":"por_pagina","in":"query","schema":{"type":"integer","default":50,"maximum":500}},{"name":"facetas","in":"query","schema":{"type":"boolean","default":true},"description":"Contagens por campo categórico/lista/booleano e faixas para números/datas."},{"name":"facetas_campos","in":"query","schema":{"type":"string"},"description":"Quais campos contar, separados por vírgula."},{"name":"campos","in":"query","schema":{"type":"string"},"description":"Campos a devolver (nome ou slug), separados por vírgula. Ex.: titulo,cidade,salario"},{"name":"apenas_ativos","in":"query","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Lista","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"consulta":{"type":"object","properties":{"original":{"type":"string"},"texto":{"type":"string"},"termos":{"type":"array","items":{"type":"string"}},"interpretada":{"type":"string"},"correcoes":{"type":"array","items":{"type":"object","properties":{"de":{"type":"string"},"para":{"type":"string"},"tipo":{"type":"string"}}}},"termos_sem_correspondencia":{"type":"array","items":{"type":"string"}},"filtros":{"type":"object"},"filtros_ignorados":{"type":"array","items":{"type":"string"}},"filtros_extraidos":{"type":"object"}}},"total":{"type":"integer"},"pagina":{"type":"integer"},"por_pagina":{"type":"integer"},"total_paginas":{"type":"integer"},"itens":{"type":"array","items":{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true}},"sugestoes":{"type":"array","items":{"type":"string"}},"facetas":{"type":"object"},"tempo_ms":{"type":"number"}}}}}}}},"post":{"tags":["Coleção {nome}"],"summary":"Cadastrar um item (ou lista) — só \"titulo\" (ou \"descricao\") é obrigatório; qualquer outro campo é livre","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true},{"type":"array","items":{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true}}]}}}},"responses":{"201":{"description":"Criado"}}},"delete":{"tags":["Coleção {nome}"],"summary":"Apagar todos os itens (?confirmar=sim, admin)","responses":{"200":{"description":"OK"}}}},"/api/colecoes/{nome}/itens/{id}":{"get":{"tags":["Coleção {nome}"],"summary":"Um item por id ou código","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Item"},"404":{"description":"Não encontrado"}}},"put":{"tags":["Coleção {nome}"],"summary":"Atualizar (campos alterados ficam protegidos da sincronização)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true}}}},"responses":{"200":{"description":"Atualizado"}}},"delete":{"tags":["Coleção {nome}"],"summary":"Remover","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Removido"}}}},"/api/colecoes/{nome}/itens/importar":{"post":{"tags":["Coleção {nome}"],"summary":"Importar planilha (xlsx/xls/ods/csv/tsv/txt/json/md) ou texto colado","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"arquivo":{"type":"string","format":"binary"},"texto":{"type":"string"},"modo":{"type":"string","enum":["mesclar","adicionar","substituir","espelhar"]},"previa":{"type":"string","enum":["0","1"]},"mapeamento":{"type":"string","description":"JSON {titulo, preco, categoria, codigo, identificador, data, ativo, ignorar:[...]} — só a descrição/título precisa existir"},"aplicar_papeis":{"type":"string"},"planilha":{"type":"string"},"delimitador":{"type":"string"},"sem_cabecalho":{"type":"string"}}}}}},"responses":{"200":{"description":"Resumo da importação"}}}},"/api/colecoes/{nome}/itens/exportar":{"get":{"tags":["Coleção {nome}"],"summary":"Exportar (json, csv ou xlsx)","parameters":[{"name":"formato","in":"query","schema":{"type":"string","enum":["json","csv","xlsx"]}}],"responses":{"200":{"description":"Arquivo"}}}},"/api/colecoes/{nome}/itens/modelo":{"get":{"tags":["Coleção {nome}"],"summary":"Planilha modelo","parameters":[{"name":"formato","in":"query","schema":{"type":"string","enum":["xlsx","csv"]}},{"name":"tipo","in":"query","schema":{"type":"string","enum":["generico","produtos","vagas","imoveis"]}}],"responses":{"200":{"description":"Arquivo"}}}},"/api/colecoes/{nome}/campos":{"get":{"tags":["Coleção {nome}"],"summary":"Campos da coleção: nome, slug, papel, tipo (numero|data|booleano|lista|categoria|texto), exemplos, min/max","responses":{"200":{"description":"Campos"}}}},"/api/colecoes/{nome}/valores":{"get":{"tags":["Coleção {nome}"],"summary":"Valores distintos de um campo","parameters":[{"name":"campo","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Valores"}}}},"/api/colecoes/{nome}/facetas":{"get":{"tags":["Coleção {nome}"],"summary":"Facetas de toda a coleção","responses":{"200":{"description":"Facetas"}}}},"/api/colecoes/{nome}/sugestoes":{"get":{"tags":["Coleção {nome}"],"summary":"Autocompletar / você quis dizer","parameters":[{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Sugestões"}}}},"/api/colecoes/{nome}/contexto":{"get":{"tags":["Coleção {nome}"],"summary":"Texto pronto para o system prompt do agente (campos, tipos, exemplos, sinônimos, como chamar)","parameters":[{"name":"formato","in":"query","schema":{"type":"string","enum":["texto","json"]}}],"responses":{"200":{"description":"Texto"}}}},"/api/colecoes/{nome}/sinonimos":{"get":{"tags":["Coleção {nome}"],"summary":"Grupos de sinônimos","responses":{"200":{"description":"Lista"}}},"post":{"tags":["Coleção {nome}"],"summary":"Adicionar grupo","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"termos":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Criado"}}},"put":{"tags":["Coleção {nome}"],"summary":"Substituir todos","responses":{"200":{"description":"OK"}}}},"/api/colecoes/{nome}/status":{"get":{"tags":["Coleção {nome}"],"summary":"Estatísticas","responses":{"200":{"description":"OK"}}}},"/api/colecoes/{nome}/consultas":{"get":{"tags":["Coleção {nome}"],"summary":"Consultas recebidas (sem_resultado=1 para as que não acharam nada)","responses":{"200":{"description":"OK"}}}},"/api/colecoes/{nome}/config":{"get":{"tags":["Coleção {nome}"],"summary":"Config da coleção (admin): título, domínio, papéis, pesos, mapeamento salvo, fontes","responses":{"200":{"description":"Config"}}},"put":{"tags":["Coleção {nome}"],"summary":"Alterar config (admin)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"titulo":{"type":"string"},"descricao":{"type":"string"},"dominio":{"type":"string"},"papeis":{"type":"object"},"separador_listas":{"type":"string"},"pesos":{"type":"object"},"stopwords":{"type":"array","items":{"type":"string"}},"mapeamento":{"type":"object"}}}}}},"responses":{"200":{"description":"OK"}}}},"/api/colecoes/{nome}/fontes":{"get":{"tags":["Coleção {nome}"],"summary":"Fontes de sincronização (admin)","responses":{"200":{"description":"Lista"}}},"post":{"tags":["Coleção {nome}"],"summary":"Criar fonte (admin): { id, tipo: url-json|url-csv|google-sheets|omie|bling|tiny, url|app_key+app_secret|token, intervalo_min, modo: mesclar|espelhar, mapeamento }","responses":{"201":{"description":"Criada"}}}},"/api/colecoes/{nome}/fontes/{id}/executar":{"post":{"tags":["Coleção {nome}"],"summary":"Sincronizar agora (admin)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Execução"}}}},"/api/colecoes/{nome}/webhook":{"post":{"tags":["Coleção {nome}"],"summary":"ERP empurra alterações: { acao: upsert|remover, itens: [...] } com x-webhook-token","responses":{"200":{"description":"OK"}}}},"/api/colecoes/{nome}/eventos":{"get":{"tags":["Coleção {nome}"],"summary":"Auditoria (admin)","responses":{"200":{"description":"Eventos"}}}},"/api/produtos/buscar":{"get":{"tags":["Coleção padrão (apelido)"],"summary":"Buscar itens (texto livre + filtros por qualquer campo)","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Texto da busca (pode ser a frase inteira do cliente). Corrige digitação e pronúncia (motocera → motosserra), plural, acentos e sinônimos; \"campo:valor\" e expressões como \"até 500 mil\", \"2 quartos\", \"esta semana\" viram filtros."},{"name":"filtros","in":"query","schema":{"type":"string"},"description":"JSON {campo: valor} com filtros por qualquer campo (nome ou slug, veja /campos). Alternativa: passar slug=valor direto na query. Valores: \"a|b\" OU, \"=x\" exato, \">100\", \"<100\", \"100-200\" (números e datas dd/mm/aaaa), listas casam por parte."},{"name":"modo","in":"query","schema":{"type":"string","enum":["auto","todos","qualquer"],"default":"auto"},"description":"auto: itens que casam o maior número de termos; todos: exige todos; qualquer: basta um."},{"name":"fuzzy","in":"query","schema":{"type":"boolean","default":true},"description":"false desliga a correção de digitação."},{"name":"extrair_filtros","in":"query","schema":{"type":"boolean","default":true},"description":"false desliga a extração de filtros da frase."},{"name":"incluir_relacionados","in":"query","schema":{"type":"boolean","default":false},"description":"Por padrão \"motosserra\" devolve as motosserras e resume em `relacionados` o que só cita o termo (lâmina, corrente, óleo…). true junta tudo numa lista só."},{"name":"tolerancia","in":"query","schema":{"type":"integer","default":0},"description":"No modo auto, quantos termos a menos que o melhor resultado ainda entram."},{"name":"min_score","in":"query","schema":{"type":"number","default":0},"description":"Descarta resultados abaixo desta relevância (0..1)."},{"name":"preco_min","in":"query","schema":{"type":"number"},"description":"Mínimo do campo com papel preço."},{"name":"preco_max","in":"query","schema":{"type":"number"},"description":"Máximo do campo com papel preço."},{"name":"ids","in":"query","schema":{"type":"string"},"description":"Lista de ids separados por vírgula."},{"name":"codigos","in":"query","schema":{"type":"string"},"description":"Lista de códigos (papel código) separados por vírgula."},{"name":"ordenar","in":"query","schema":{"type":"string"},"description":"relevancia | titulo | preco_asc | preco_desc | <slug do campo> | -<slug> (decrescente)."},{"name":"pagina","in":"query","schema":{"type":"integer","default":1}},{"name":"por_pagina","in":"query","schema":{"type":"integer","default":50,"maximum":500}},{"name":"facetas","in":"query","schema":{"type":"boolean","default":true},"description":"Contagens por campo categórico/lista/booleano e faixas para números/datas."},{"name":"facetas_campos","in":"query","schema":{"type":"string"},"description":"Quais campos contar, separados por vírgula."},{"name":"campos","in":"query","schema":{"type":"string"},"description":"Campos a devolver (nome ou slug), separados por vírgula. Ex.: titulo,cidade,salario"},{"name":"apenas_ativos","in":"query","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"consulta":{"type":"object","properties":{"original":{"type":"string"},"texto":{"type":"string"},"termos":{"type":"array","items":{"type":"string"}},"interpretada":{"type":"string"},"correcoes":{"type":"array","items":{"type":"object","properties":{"de":{"type":"string"},"para":{"type":"string"},"tipo":{"type":"string"}}}},"termos_sem_correspondencia":{"type":"array","items":{"type":"string"}},"filtros":{"type":"object"},"filtros_ignorados":{"type":"array","items":{"type":"string"}},"filtros_extraidos":{"type":"object"}}},"total":{"type":"integer"},"pagina":{"type":"integer"},"por_pagina":{"type":"integer"},"total_paginas":{"type":"integer"},"itens":{"type":"array","items":{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true}},"sugestoes":{"type":"array","items":{"type":"string"}},"facetas":{"type":"object"},"tempo_ms":{"type":"number"}}}}}}}},"post":{"tags":["Coleção padrão (apelido)"],"summary":"Buscar (parâmetros no corpo JSON)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string"},"filtros":{"type":"string"},"modo":{"type":"string","enum":["auto","todos","qualquer"],"default":"auto"},"fuzzy":{"type":"boolean","default":true},"extrair_filtros":{"type":"boolean","default":true},"incluir_relacionados":{"type":"boolean","default":false},"tolerancia":{"type":"integer","default":0},"min_score":{"type":"number","default":0},"preco_min":{"type":"number"},"preco_max":{"type":"number"},"ids":{"type":"string"},"codigos":{"type":"string"},"ordenar":{"type":"string"},"pagina":{"type":"integer","default":1},"por_pagina":{"type":"integer","default":50,"maximum":500},"facetas":{"type":"boolean","default":true},"facetas_campos":{"type":"string"},"campos":{"type":"string"},"apenas_ativos":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"consulta":{"type":"object","properties":{"original":{"type":"string"},"texto":{"type":"string"},"termos":{"type":"array","items":{"type":"string"}},"interpretada":{"type":"string"},"correcoes":{"type":"array","items":{"type":"object","properties":{"de":{"type":"string"},"para":{"type":"string"},"tipo":{"type":"string"}}}},"termos_sem_correspondencia":{"type":"array","items":{"type":"string"}},"filtros":{"type":"object"},"filtros_ignorados":{"type":"array","items":{"type":"string"}},"filtros_extraidos":{"type":"object"}}},"total":{"type":"integer"},"pagina":{"type":"integer"},"por_pagina":{"type":"integer"},"total_paginas":{"type":"integer"},"itens":{"type":"array","items":{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true}},"sugestoes":{"type":"array","items":{"type":"string"}},"facetas":{"type":"object"},"tempo_ms":{"type":"number"}}}}}}}}},"/api/produtos/itens":{"get":{"tags":["Coleção padrão (apelido)"],"summary":"Listar itens (sem texto, com filtros e paginação)","parameters":[{"name":"filtros","in":"query","schema":{"type":"string"},"description":"JSON {campo: valor} com filtros por qualquer campo (nome ou slug, veja /campos). Alternativa: passar slug=valor direto na query. Valores: \"a|b\" OU, \"=x\" exato, \">100\", \"<100\", \"100-200\" (números e datas dd/mm/aaaa), listas casam por parte."},{"name":"modo","in":"query","schema":{"type":"string","enum":["auto","todos","qualquer"],"default":"auto"},"description":"auto: itens que casam o maior número de termos; todos: exige todos; qualquer: basta um."},{"name":"fuzzy","in":"query","schema":{"type":"boolean","default":true},"description":"false desliga a correção de digitação."},{"name":"extrair_filtros","in":"query","schema":{"type":"boolean","default":true},"description":"false desliga a extração de filtros da frase."},{"name":"incluir_relacionados","in":"query","schema":{"type":"boolean","default":false},"description":"Por padrão \"motosserra\" devolve as motosserras e resume em `relacionados` o que só cita o termo (lâmina, corrente, óleo…). true junta tudo numa lista só."},{"name":"tolerancia","in":"query","schema":{"type":"integer","default":0},"description":"No modo auto, quantos termos a menos que o melhor resultado ainda entram."},{"name":"min_score","in":"query","schema":{"type":"number","default":0},"description":"Descarta resultados abaixo desta relevância (0..1)."},{"name":"preco_min","in":"query","schema":{"type":"number"},"description":"Mínimo do campo com papel preço."},{"name":"preco_max","in":"query","schema":{"type":"number"},"description":"Máximo do campo com papel preço."},{"name":"ids","in":"query","schema":{"type":"string"},"description":"Lista de ids separados por vírgula."},{"name":"codigos","in":"query","schema":{"type":"string"},"description":"Lista de códigos (papel código) separados por vírgula."},{"name":"ordenar","in":"query","schema":{"type":"string"},"description":"relevancia | titulo | preco_asc | preco_desc | <slug do campo> | -<slug> (decrescente)."},{"name":"pagina","in":"query","schema":{"type":"integer","default":1}},{"name":"por_pagina","in":"query","schema":{"type":"integer","default":50,"maximum":500}},{"name":"facetas","in":"query","schema":{"type":"boolean","default":true},"description":"Contagens por campo categórico/lista/booleano e faixas para números/datas."},{"name":"facetas_campos","in":"query","schema":{"type":"string"},"description":"Quais campos contar, separados por vírgula."},{"name":"campos","in":"query","schema":{"type":"string"},"description":"Campos a devolver (nome ou slug), separados por vírgula. Ex.: titulo,cidade,salario"},{"name":"apenas_ativos","in":"query","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Lista","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"consulta":{"type":"object","properties":{"original":{"type":"string"},"texto":{"type":"string"},"termos":{"type":"array","items":{"type":"string"}},"interpretada":{"type":"string"},"correcoes":{"type":"array","items":{"type":"object","properties":{"de":{"type":"string"},"para":{"type":"string"},"tipo":{"type":"string"}}}},"termos_sem_correspondencia":{"type":"array","items":{"type":"string"}},"filtros":{"type":"object"},"filtros_ignorados":{"type":"array","items":{"type":"string"}},"filtros_extraidos":{"type":"object"}}},"total":{"type":"integer"},"pagina":{"type":"integer"},"por_pagina":{"type":"integer"},"total_paginas":{"type":"integer"},"itens":{"type":"array","items":{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true}},"sugestoes":{"type":"array","items":{"type":"string"}},"facetas":{"type":"object"},"tempo_ms":{"type":"number"}}}}}}}},"post":{"tags":["Coleção padrão (apelido)"],"summary":"Cadastrar um item (ou lista) — só \"titulo\" (ou \"descricao\") é obrigatório; qualquer outro campo é livre","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true},{"type":"array","items":{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true}}]}}}},"responses":{"201":{"description":"Criado"}}},"delete":{"tags":["Coleção padrão (apelido)"],"summary":"Apagar todos os itens (?confirmar=sim, admin)","responses":{"200":{"description":"OK"}}}},"/api/produtos/itens/{id}":{"get":{"tags":["Coleção padrão (apelido)"],"summary":"Um item por id ou código","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Item"},"404":{"description":"Não encontrado"}}},"put":{"tags":["Coleção padrão (apelido)"],"summary":"Atualizar (campos alterados ficam protegidos da sincronização)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Item achatado: só os campos que existem. Apelidos de papel: descricao (= titulo), preco/preco_formatado, codigo, categoria.","properties":{"id":{"type":"string"},"titulo":{"type":"string"},"descricao":{"type":"string","description":"Apelido de titulo."},"preco":{"type":"number"},"preco_formatado":{"type":"string"},"codigo":{"type":"string"},"categoria":{"type":"string"},"ativo":{"type":"boolean","description":"Só aparece quando false."},"score":{"type":"number"},"termos_casados":{"type":"integer"},"termos_total":{"type":"integer"}},"additionalProperties":true}}}},"responses":{"200":{"description":"Atualizado"}}},"delete":{"tags":["Coleção padrão (apelido)"],"summary":"Remover","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Removido"}}}},"/api/produtos/itens/importar":{"post":{"tags":["Coleção padrão (apelido)"],"summary":"Importar planilha (xlsx/xls/ods/csv/tsv/txt/json/md) ou texto colado","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"arquivo":{"type":"string","format":"binary"},"texto":{"type":"string"},"modo":{"type":"string","enum":["mesclar","adicionar","substituir","espelhar"]},"previa":{"type":"string","enum":["0","1"]},"mapeamento":{"type":"string","description":"JSON {titulo, preco, categoria, codigo, identificador, data, ativo, ignorar:[...]} — só a descrição/título precisa existir"},"aplicar_papeis":{"type":"string"},"planilha":{"type":"string"},"delimitador":{"type":"string"},"sem_cabecalho":{"type":"string"}}}}}},"responses":{"200":{"description":"Resumo da importação"}}}},"/api/produtos/itens/exportar":{"get":{"tags":["Coleção padrão (apelido)"],"summary":"Exportar (json, csv ou xlsx)","parameters":[{"name":"formato","in":"query","schema":{"type":"string","enum":["json","csv","xlsx"]}}],"responses":{"200":{"description":"Arquivo"}}}},"/api/produtos/itens/modelo":{"get":{"tags":["Coleção padrão (apelido)"],"summary":"Planilha modelo","parameters":[{"name":"formato","in":"query","schema":{"type":"string","enum":["xlsx","csv"]}},{"name":"tipo","in":"query","schema":{"type":"string","enum":["generico","produtos","vagas","imoveis"]}}],"responses":{"200":{"description":"Arquivo"}}}},"/api/produtos/campos":{"get":{"tags":["Coleção padrão (apelido)"],"summary":"Campos da coleção: nome, slug, papel, tipo (numero|data|booleano|lista|categoria|texto), exemplos, min/max","responses":{"200":{"description":"Campos"}}}},"/api/produtos/valores":{"get":{"tags":["Coleção padrão (apelido)"],"summary":"Valores distintos de um campo","parameters":[{"name":"campo","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Valores"}}}},"/api/produtos/facetas":{"get":{"tags":["Coleção padrão (apelido)"],"summary":"Facetas de toda a coleção","responses":{"200":{"description":"Facetas"}}}},"/api/produtos/sugestoes":{"get":{"tags":["Coleção padrão (apelido)"],"summary":"Autocompletar / você quis dizer","parameters":[{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Sugestões"}}}},"/api/produtos/contexto":{"get":{"tags":["Coleção padrão (apelido)"],"summary":"Texto pronto para o system prompt do agente (campos, tipos, exemplos, sinônimos, como chamar)","parameters":[{"name":"formato","in":"query","schema":{"type":"string","enum":["texto","json"]}}],"responses":{"200":{"description":"Texto"}}}},"/api/produtos/sinonimos":{"get":{"tags":["Coleção padrão (apelido)"],"summary":"Grupos de sinônimos","responses":{"200":{"description":"Lista"}}},"post":{"tags":["Coleção padrão (apelido)"],"summary":"Adicionar grupo","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"termos":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Criado"}}},"put":{"tags":["Coleção padrão (apelido)"],"summary":"Substituir todos","responses":{"200":{"description":"OK"}}}},"/api/produtos/status":{"get":{"tags":["Coleção padrão (apelido)"],"summary":"Estatísticas","responses":{"200":{"description":"OK"}}}},"/api/produtos/consultas":{"get":{"tags":["Coleção padrão (apelido)"],"summary":"Consultas recebidas (sem_resultado=1 para as que não acharam nada)","responses":{"200":{"description":"OK"}}}}}}