{ "openapi": "3.1.0", "info": { "title": "API pública do Franquiei", "version": "1.0.0", "summary": "Diagnóstico de franqueabilidade, calculadora de royalties, nichos e guias de franquia.", "description": "API somente leitura, gratuita e sem autenticação para agentes e LLMs. Valores em reais (BRL) e percentuais em pontos (5 = 5%). Os resultados são estimativas e não substituem orientação jurídica, contábil ou financeira. As mesmas ferramentas existem como servidor MCP em https://franquiei.com/mcp. Índice do site para LLMs: https://franquiei.com/llms.txt.", "contact": { "name": "Franquiei", "url": "https://franquiei.com" } }, "servers": [ { "url": "https://franquiei.com" } ], "externalDocs": { "description": "llms.txt", "url": "https://franquiei.com/llms.txt" }, "paths": { "/api/v1/diagnostico": { "get": { "operationId": "diagnosticar_franquia", "summary": "Diagnóstico de franqueabilidade", "description": "Avalia se um negócio pode virar franquia: nota de 0 a 100 em 6 dimensões, veredito, taxa de franquia, royalties, fundo de marketing e investimento do franqueado sugeridos, mais o link do plano no Franquiei. Campos omitidos usam os valores de referência do nicho.", "parameters": [ { "name": "nicho", "in": "query", "required": true, "description": "Slug do segmento (veja listar_nichos). Use \"outro\" se nenhum servir.", "schema": { "type": "string", "description": "Slug do segmento (veja listar_nichos). Use \"outro\" se nenhum servir.", "enum": [ "hamburgueria", "pizzaria", "acai", "cafeteria", "padaria-artesanal", "doceria", "marmita-fitness", "food-truck", "sorveteria", "comida-japonesa", "salao-de-beleza", "barbearia", "esmalteria", "estetica-depilacao", "design-sobrancelha", "estudio-funcional", "pilates", "clinica-odontologica", "fisioterapia", "escola-de-idiomas", "reforco-escolar", "escola-programacao-kids", "pet-shop", "banho-tosa-movel", "creche-canina", "lavanderia", "lavagem-de-tenis", "assistencia-celular", "limpeza-residencial", "dedetizacao", "reparos-residenciais", "estetica-automotiva", "troca-de-oleo", "mercado-autonomo", "presentes-personalizados", "floricultura", "brecho", "escape-room", "buffet-infantil", "taproom", "agencia-marketing", "contabilidade", "coworking", "outro" ] } }, { "name": "nome", "in": "query", "required": false, "description": "Nome do negócio.", "schema": { "type": "string", "description": "Nome do negócio." } }, { "name": "cidade", "in": "query", "required": false, "description": "Cidade da unidade principal.", "schema": { "type": "string", "description": "Cidade da unidade principal." } }, { "name": "anos", "in": "query", "required": false, "description": "Anos de operação.", "schema": { "type": "integer", "description": "Anos de operação.", "minimum": 0, "maximum": 80 } }, { "name": "unidades", "in": "query", "required": false, "description": "Unidades próprias em operação.", "schema": { "type": "integer", "description": "Unidades próprias em operação.", "minimum": 0, "maximum": 500 } }, { "name": "faturamento", "in": "query", "required": false, "description": "Faturamento mensal por unidade, em reais. Padrão: referência do nicho.", "schema": { "type": "number", "description": "Faturamento mensal por unidade, em reais. Padrão: referência do nicho.", "minimum": 1000, "maximum": 50000000 } }, { "name": "margem", "in": "query", "required": false, "description": "Margem líquida mensal, em % (18 = 18%). Padrão: referência do nicho.", "schema": { "type": "number", "description": "Margem líquida mensal, em % (18 = 18%). Padrão: referência do nicho.", "minimum": -50, "maximum": 90 } }, { "name": "investimento", "in": "query", "required": false, "description": "Investimento para montar uma unidade, em reais. Padrão: referência do nicho.", "schema": { "type": "number", "description": "Investimento para montar uma unidade, em reais. Padrão: referência do nicho.", "minimum": 1000, "maximum": 100000000 } }, { "name": "formato", "in": "query", "required": false, "description": "Formato da unidade franqueada.", "schema": { "type": "string", "description": "Formato da unidade franqueada.", "enum": [ "loja", "quiosque", "home", "delivery", "movel" ] } }, { "name": "processos", "in": "query", "required": false, "description": "Os processos estão documentados?", "schema": { "type": "string", "description": "Os processos estão documentados?", "enum": [ "nao", "parcial", "sim" ] } }, { "name": "marca", "in": "query", "required": false, "description": "Situação da marca no INPI.", "schema": { "type": "string", "description": "Situação da marca no INPI.", "enum": [ "nao", "pedido", "registrada" ] } }, { "name": "meta", "in": "query", "required": false, "description": "Meta de unidades franqueadas em 5 anos.", "schema": { "type": "integer", "description": "Meta de unidades franqueadas em 5 anos.", "minimum": 1, "maximum": 5000 } } ], "responses": { "200": { "description": "Resultado em JSON.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Erro" } } } }, "/api/v1/calculadora": { "get": { "operationId": "calcular_royalties", "summary": "Calculadora de royalties e payback", "description": "Simula a margem final e o lucro mensal do franqueado, o payback, os royalties por unidade e da rede e o total de taxas de franquia, a partir de faturamento, margem, royalties, fundo de marketing, investimento, taxa e número de unidades.", "parameters": [ { "name": "faturamento", "in": "query", "required": false, "description": "Faturamento mensal da unidade, em reais (padrão 80000).", "schema": { "type": "number", "description": "Faturamento mensal da unidade, em reais (padrão 80000).", "minimum": 1 } }, { "name": "margem", "in": "query", "required": false, "description": "Margem líquida antes dos royalties, em % (padrão 18).", "schema": { "type": "number", "description": "Margem líquida antes dos royalties, em % (padrão 18)." } }, { "name": "royalties", "in": "query", "required": false, "description": "Royalties, em % do faturamento (padrão 5).", "schema": { "type": "number", "description": "Royalties, em % do faturamento (padrão 5).", "minimum": 0 } }, { "name": "fundo", "in": "query", "required": false, "description": "Fundo de marketing, em % do faturamento (padrão 2).", "schema": { "type": "number", "description": "Fundo de marketing, em % do faturamento (padrão 2).", "minimum": 0 } }, { "name": "investimento", "in": "query", "required": false, "description": "Investimento na unidade, em reais (padrão 200000).", "schema": { "type": "number", "description": "Investimento na unidade, em reais (padrão 200000).", "minimum": 0 } }, { "name": "taxa", "in": "query", "required": false, "description": "Taxa de franquia, em reais (padrão 40000).", "schema": { "type": "number", "description": "Taxa de franquia, em reais (padrão 40000).", "minimum": 0 } }, { "name": "unidades", "in": "query", "required": false, "description": "Unidades franqueadas na rede (padrão 20).", "schema": { "type": "integer", "description": "Unidades franqueadas na rede (padrão 20).", "minimum": 0 } } ], "responses": { "200": { "description": "Resultado em JSON.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Erro" } } } }, "/api/v1/nichos": { "get": { "operationId": "listar_nichos", "summary": "Nichos de franquia", "description": "Lista os 43 segmentos com referências de franquia no Franquiei (slug, nome, categoria e resumo). Use o slug em diagnosticar_franquia e consultar_nicho.", "parameters": [ { "name": "categoria", "in": "query", "required": false, "description": "Filtra por categoria.", "schema": { "type": "string", "description": "Filtra por categoria.", "enum": [ "Alimentação", "Beleza & Bem-estar", "Saúde", "Educação", "Pets", "Serviços", "Automotivo", "Varejo", "Entretenimento", "Negócios" ] } } ], "responses": { "200": { "description": "Resultado em JSON.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Erro" } } } }, "/api/v1/nichos/{slug}": { "get": { "operationId": "consultar_nicho", "summary": "Referências de um nicho", "description": "Valores de referência de um segmento (faturamento, margem, investimento) e a simulação de franquia com eles: taxa de franquia, royalties, investimento total e payback, além do que padronizar, riscos típicos e formatos possíveis.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Slug do nicho (veja listar_nichos).", "schema": { "type": "string", "description": "Slug do nicho (veja listar_nichos).", "enum": [ "hamburgueria", "pizzaria", "acai", "cafeteria", "padaria-artesanal", "doceria", "marmita-fitness", "food-truck", "sorveteria", "comida-japonesa", "salao-de-beleza", "barbearia", "esmalteria", "estetica-depilacao", "design-sobrancelha", "estudio-funcional", "pilates", "clinica-odontologica", "fisioterapia", "escola-de-idiomas", "reforco-escolar", "escola-programacao-kids", "pet-shop", "banho-tosa-movel", "creche-canina", "lavanderia", "lavagem-de-tenis", "assistencia-celular", "limpeza-residencial", "dedetizacao", "reparos-residenciais", "estetica-automotiva", "troca-de-oleo", "mercado-autonomo", "presentes-personalizados", "floricultura", "brecho", "escape-room", "buffet-infantil", "taproom", "agencia-marketing", "contabilidade", "coworking" ] } } ], "responses": { "200": { "description": "Resultado em JSON.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Erro" }, "404": { "$ref": "#/components/responses/Erro" } } } }, "/api/v1/guias": { "get": { "operationId": "buscar_guias", "summary": "Busca nos guias de franquia", "description": "Busca nos 206 guias do Franquiei (Lei 13.966/2019, COF, taxas, royalties, manual, expansão, gestão da rede). Devolve título, resposta curta e links HTML e markdown.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Termos de busca, ex.: \"royalties academia\". Sem q, lista os guias.", "schema": { "type": "string", "description": "Termos de busca, ex.: \"royalties academia\". Sem q, lista os guias." } }, { "name": "categoria", "in": "query", "required": false, "description": "Filtra por categoria.", "schema": { "type": "string", "description": "Filtra por categoria.", "enum": [ "Primeiros passos", "Jurídico", "Finanças", "Operação", "Expansão", "Marketing e vendas", "Gestão da rede", "Comparativos", "Por segmento" ] } }, { "name": "limite", "in": "query", "required": false, "description": "Máximo de resultados (padrão 10).", "schema": { "type": "integer", "description": "Máximo de resultados (padrão 10).", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Resultado em JSON.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Erro" } } } }, "/api/v1/guias/{slug}": { "get": { "operationId": "ler_guia", "summary": "Ler um guia", "description": "Conteúdo completo de um guia em markdown (resposta curta, seções, FAQ e fontes), pelo slug.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Slug do guia (veja buscar_guias).", "schema": { "type": "string", "description": "Slug do guia (veja buscar_guias)." } } ], "responses": { "200": { "description": "Resultado em JSON.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Erro" }, "404": { "$ref": "#/components/responses/Erro" } } } } }, "components": { "responses": { "Erro": { "description": "Parâmetro inválido ou recurso inexistente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "string" } }, "required": [ "erro" ] } } } } } } }