{"name":"Salomão MCP Server API","version":"1.0.0","description":"API para gestão de lojas maçônicas, tesouraria e integrações por IA.","baseUrl":"/api/v1","baseUrlDevelopment":"http://localhost:3003/api/v1","baseUrlProduction":"https://salomao.ia.br/api/v1","authentication":{"type":"Bearer Token","description":"Envie Authorization: Bearer <token>. Use JWT temporário do login ou token de API com prefixo slm_.","example":{"header":"Authorization","value":"Bearer slm_SEU_TOKEN"}},"responseFormat":{"success":"{ \"success\": true, \"message\": \"Sucesso\", \"data\": <T> }","paginated":"{ \"success\": true, \"message\": \"Sucesso\", \"data\": <T[]>, \"pagination\": { \"page\": 1, \"pageSize\": 20, \"total\": 100, \"totalPages\": 5, \"hasNext\": true, \"hasPrevious\": false } }","error":"{ \"success\": false, \"message\": \"Mensagem\", \"errors\": <detalhes> | null }","statusCodes":{"200":"Sucesso","201":"Criado","400":"Requisição inválida","401":"Não autenticado","403":"Sem permissão","404":"Não encontrado","409":"Conflito","410":"Link público expirado ou inválido","422":"Erro de validação","500":"Erro interno"}},"capabilities":[{"intent":"Autenticar integração","routes":["POST /api/v1/auth/login","POST /api/v1/tokens"]},{"intent":"Identificar irmão por CPF, CIM ou telefone","routes":["POST /api/v1/irmaos/identificar"]},{"intent":"Identificar irmão por WhatsApp","routes":["POST /api/v1/whatsapp/validar-telefone"]},{"intent":"Consultar extrato do irmão","routes":["GET /api/v1/irmaos/:id/extrato"]},{"intent":"Gerar link público de cobrança","routes":["POST /api/v1/whatsapp/cobrancas/gerar-link"]},{"intent":"Integrar agente por MCP","routes":["POST /api/v1/mcp"]},{"intent":"Consultar caixa e relatórios","routes":["GET /api/v1/financeiro","GET /api/v1/financeiro/relatorio"]}],"endpoints":[{"group":"Autenticação","description":"Login e tokens usados por integrações.","routes":[{"method":"POST","path":"/api/v1/auth/login","description":"Autenticar por e-mail e senha e obter JWT válido por 7 dias.","auth":false,"params":{"body":{"email":{"type":"string (email)","required":true,"description":"E-mail do usuário."},"password":{"type":"string","required":true,"description":"Senha com pelo menos 6 caracteres."}}}},{"method":"GET","path":"/api/v1/tokens","description":"Listar tokens visíveis ao usuário.","auth":true},{"method":"POST","path":"/api/v1/tokens","description":"Criar token de API.","auth":true,"params":{"body":{"nome":{"type":"string","required":true,"description":"Nome do token."},"tipo":{"type":"string","required":true,"description":"Tipo.","enum":["PERMANENT","TEMPORARY"]},"expiresInDays":{"type":"integer","required":false,"description":"Validade em dias para token temporário."}}}},{"method":"GET","path":"/api/v1/tokens/:id","description":"Consultar token e estatísticas de uso.","auth":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"PATCH","path":"/api/v1/tokens/:id","description":"Ativar ou desativar token.","auth":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"nome":{"type":"string","required":false,"description":"Novo nome do token."},"ativo":{"type":"boolean","required":false,"description":"Novo estado do token."}}}},{"method":"DELETE","path":"/api/v1/tokens/:id","description":"Revogar e remover token.","auth":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}}]},{"group":"Potências e lojas","description":"Estrutura administrativa maçônica.","routes":[{"method":"GET","path":"/api/v1/potencias","description":"Listar potências.","auth":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."}}},"equivalentMcp":"listar_potencias"},{"method":"POST","path":"/api/v1/potencias","description":"Criar potência.","auth":true,"adminOnly":true,"params":{"body":{"nome":{"type":"string","required":true,"description":"Nome."},"sigla":{"type":"string","required":true,"description":"Sigla."},"descricao":{"type":"string","required":false,"description":"Descrição."},"website":{"type":"string (URL)","required":false,"description":"Site."},"ativa":{"type":"boolean","required":false,"description":"Ativa.","default":true}}}},{"method":"GET","path":"/api/v1/potencias/:id","description":"Obter potência.","auth":true,"adminOnly":false,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"PUT","path":"/api/v1/potencias/:id","description":"Atualizar potência.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"nome":{"type":"string","required":true,"description":"Nome."},"sigla":{"type":"string","required":true,"description":"Sigla."},"descricao":{"type":"string","required":false,"description":"Descrição."},"website":{"type":"string (URL)","required":false,"description":"Site."},"ativa":{"type":"boolean","required":false,"description":"Ativa.","default":true}}}},{"method":"DELETE","path":"/api/v1/potencias/:id","description":"Excluir potência.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"GET","path":"/api/v1/lojas","description":"Listar lojas.","auth":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."},"potenciaId":{"type":"string (UUID)","required":false,"description":"Filtrar por potência."}}},"equivalentMcp":"listar_lojas"},{"method":"POST","path":"/api/v1/lojas","description":"Criar loja.","auth":true,"adminOnly":true,"params":{"body":{"nome":{"type":"string","required":true,"description":"Nome."},"numero":{"type":"integer","required":true,"description":"Número."},"oriente":{"type":"string","required":true,"description":"Oriente."},"potenciaId":{"type":"string (UUID)","required":true,"description":"Potência."},"fundadaEm":{"type":"string (date)","required":false,"description":"Fundação."},"ativa":{"type":"boolean","required":false,"description":"Ativa.","default":true},"endereco":{"type":"string","required":false,"description":"Endereço."},"cidade":{"type":"string","required":false,"description":"Cidade."},"estado":{"type":"string","required":false,"description":"UF."},"cep":{"type":"string","required":false,"description":"CEP."},"telefone":{"type":"string","required":false,"description":"Telefone."},"email":{"type":"string (email)","required":false,"description":"E-mail."}}}},{"method":"GET","path":"/api/v1/lojas/:id","description":"Obter loja e irmãos.","auth":true,"adminOnly":false,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}},"equivalentMcp":"buscar_loja"},{"method":"PUT","path":"/api/v1/lojas/:id","description":"Atualizar loja.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"nome":{"type":"string","required":true,"description":"Nome."},"numero":{"type":"integer","required":true,"description":"Número."},"oriente":{"type":"string","required":true,"description":"Oriente."},"potenciaId":{"type":"string (UUID)","required":true,"description":"Potência."},"fundadaEm":{"type":"string (date)","required":false,"description":"Fundação."},"ativa":{"type":"boolean","required":false,"description":"Ativa.","default":true},"endereco":{"type":"string","required":false,"description":"Endereço."},"cidade":{"type":"string","required":false,"description":"Cidade."},"estado":{"type":"string","required":false,"description":"UF."},"cep":{"type":"string","required":false,"description":"CEP."},"telefone":{"type":"string","required":false,"description":"Telefone."},"email":{"type":"string (email)","required":false,"description":"E-mail."}}}},{"method":"DELETE","path":"/api/v1/lojas/:id","description":"Excluir loja.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}}]},{"group":"Irmãos","description":"Cadastro, status, histórico e extrato dos irmãos.","routes":[{"method":"GET","path":"/api/v1/irmaos","description":"Listar irmãos.","auth":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Busca por nome, CIM, e-mail ou cargo."},"lojaId":{"type":"string (UUID)","required":false,"description":"Filtrar por loja."},"ativo":{"type":"string","required":false,"description":"true (padrão), false, all ou todos.","default":"true","enum":["true","false","all","todos"]}}},"equivalentMcp":"listar_irmaos"},{"method":"POST","path":"/api/v1/irmaos/identificar","description":"Identificar irmão por conjunção de CPF, CIM e/ou telefone.","auth":true,"params":{"body":{"cpf":{"type":"string (11 dígitos)","required":false,"description":"CPF. Não é devolvido na resposta.","example":"12345678901"},"cim":{"type":"string","required":false,"description":"Cadastro de Identificação Maçônica.","example":"12345"},"telefone":{"type":"string","required":false,"description":"DDD + número ou DDI + DDD + número, sem +. Aceita espaços e com/sem 9º dígito (ex.: 556788776655).","example":"556788776655"}}},"notes":["Informe ao menos um de cpf, cim ou telefone.","Campos enviados são combinados com AND: todos devem corresponder ao mesmo irmão.","A resposta traz encontrado, id, nome, cim, ativo e loja. Não inclui CPF nem dados bancários.","Inclui irmãos ativos e inativos."]},{"method":"POST","path":"/api/v1/irmaos","description":"Cadastrar irmão.","auth":true,"adminOnly":true,"params":{"body":{"nome":{"type":"string","required":true,"description":"Nome completo."},"cpf":{"type":"string (11 dígitos)","required":false,"description":"CPF; dado sensível, não exponha ao usuário final."},"cim":{"type":"string","required":false,"description":"Cadastro de Identificação Maçônica."},"grau":{"type":"integer (1-33)","required":false,"description":"Grau maçônico.","default":1},"cargo":{"type":"string","required":false,"description":"Cargo na loja."},"email":{"type":"string (email)","required":false,"description":"E-mail."},"codigoPais":{"type":"string","required":false,"description":"DDI sem +.","default":"55","example":"55"},"telefone":{"type":"string","required":false,"description":"DDD + número ou E.164 sem +.","example":"11999887766"},"celular":{"type":"string","required":false,"description":"Celular alternativo."},"dataNascimento":{"type":"string (date)","required":false,"description":"Data de nascimento."},"dataIniciacao":{"type":"string (date)","required":false,"description":"Data de iniciação."},"dataElevacao":{"type":"string (date)","required":false,"description":"Data de elevação."},"dataExaltacao":{"type":"string (date)","required":false,"description":"Data de exaltação."},"profissao":{"type":"string","required":false,"description":"Profissão."},"endereco":{"type":"string","required":false,"description":"Endereço."},"cidade":{"type":"string","required":false,"description":"Cidade."},"estado":{"type":"string","required":false,"description":"UF."},"cep":{"type":"string","required":false,"description":"CEP."},"observacoes":{"type":"string","required":false,"description":"Observações internas."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja do irmão."}}}},{"method":"GET","path":"/api/v1/irmaos/:id","description":"Obter irmão.","auth":true,"adminOnly":false,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}},"equivalentMcp":"buscar_irmao"},{"method":"PUT","path":"/api/v1/irmaos/:id","description":"Atualizar irmão.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"nome":{"type":"string","required":true,"description":"Nome completo."},"cpf":{"type":"string (11 dígitos)","required":false,"description":"CPF; dado sensível, não exponha ao usuário final."},"cim":{"type":"string","required":false,"description":"Cadastro de Identificação Maçônica."},"grau":{"type":"integer (1-33)","required":false,"description":"Grau maçônico.","default":1},"cargo":{"type":"string","required":false,"description":"Cargo na loja."},"email":{"type":"string (email)","required":false,"description":"E-mail."},"codigoPais":{"type":"string","required":false,"description":"DDI sem +.","default":"55","example":"55"},"telefone":{"type":"string","required":false,"description":"DDD + número ou E.164 sem +.","example":"11999887766"},"celular":{"type":"string","required":false,"description":"Celular alternativo."},"dataNascimento":{"type":"string (date)","required":false,"description":"Data de nascimento."},"dataIniciacao":{"type":"string (date)","required":false,"description":"Data de iniciação."},"dataElevacao":{"type":"string (date)","required":false,"description":"Data de elevação."},"dataExaltacao":{"type":"string (date)","required":false,"description":"Data de exaltação."},"profissao":{"type":"string","required":false,"description":"Profissão."},"endereco":{"type":"string","required":false,"description":"Endereço."},"cidade":{"type":"string","required":false,"description":"Cidade."},"estado":{"type":"string","required":false,"description":"UF."},"cep":{"type":"string","required":false,"description":"CEP."},"observacoes":{"type":"string","required":false,"description":"Observações internas."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja do irmão."}}}},{"method":"DELETE","path":"/api/v1/irmaos/:id","description":"Excluir irmão.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"GET","path":"/api/v1/irmaos/:id/extrato","description":"Consultar extrato financeiro completo.","auth":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"query":{"lojaId":{"type":"string (UUID)","required":true,"description":"Loja do extrato."}}},"equivalentMcp":"consultar_extrato_irmao"},{"method":"GET","path":"/api/v1/irmaos/:id/rateios","description":"Listar cobranças disponíveis para alocação.","auth":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"query":{"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."}}}},{"method":"POST","path":"/api/v1/irmaos/:id/inativar","description":"Inativar irmão e registrar histórico.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"motivo":{"type":"string","required":true,"description":"Motivo da inativação."}}}},{"method":"POST","path":"/api/v1/irmaos/:id/reativar","description":"Reativar irmão.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"motivo":{"type":"string","required":false,"description":"Motivo opcional."}}}},{"method":"GET","path":"/api/v1/irmaos/:id/historico","description":"Listar histórico do irmão.","auth":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."}}}},{"method":"POST","path":"/api/v1/irmaos/:id/historico","description":"Registrar evento livre no histórico.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"descricao":{"type":"string","required":true,"description":"Descrição do evento."}}}},{"method":"GET","path":"/api/v1/irmaos/:id/aliases","description":"Listar aliases.","auth":true,"adminOnly":false,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"POST","path":"/api/v1/irmaos/:id/aliases","description":"Criar alias.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"nome":{"type":"string","required":false,"description":"Nome alternativo; nome ou cpfCnpj é obrigatório."},"cpfCnpj":{"type":"string","required":false,"description":"CPF/CNPJ alternativo; nome ou cpfCnpj é obrigatório."},"descricao":{"type":"string","required":false,"description":"Descrição do vínculo."}}}},{"method":"DELETE","path":"/api/v1/irmaos/:id/aliases","description":"Excluir alias informado no corpo.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"aliasId":{"type":"string (UUID)","required":true,"description":"Alias a excluir."}}}},{"method":"GET","path":"/api/v1/irmaos/:id/justificativas","description":"Listar justificativas.","auth":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"query":{"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."}}}},{"method":"POST","path":"/api/v1/irmaos/:id/justificativas","description":"Registrar justificativa.","auth":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"dataContato":{"type":"string (date)","required":true,"description":"Data do contato."},"texto":{"type":"string","required":true,"description":"Texto da justificativa."}}}},{"method":"PUT","path":"/api/v1/irmaos/:id/justificativas/:justId","description":"Atualizar justificativa.","auth":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."},"justId":{"type":"string (UUID)","required":true,"description":"Justificativa."}},"body":{"dataContato":{"type":"string (date)","required":false,"description":"Nova data do contato."},"texto":{"type":"string","required":false,"description":"Novo texto."}}}},{"method":"DELETE","path":"/api/v1/irmaos/:id/justificativas/:justId","description":"Excluir justificativa.","auth":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."},"justId":{"type":"string (UUID)","required":true,"description":"Justificativa."}}}}]},{"group":"Financeiro e contas","description":"Caixa, contas bancárias, doações e relatórios.","routes":[{"method":"GET","path":"/api/v1/financeiro","description":"Listar lançamentos e agregados.","auth":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."},"potenciaId":{"type":"string (UUID)","required":false,"description":"Potência."},"lojaId":{"type":"string (UUID)","required":false,"description":"Loja."},"irmaoId":{"type":"string (UUID)","required":false,"description":"Irmão."},"tipo":{"type":"string","required":false,"description":"Tipo.","enum":["RECEITA","DESPESA","DOACAO"]},"status":{"type":"string","required":false,"description":"Status.","enum":["PENDENTE","PAGO","CANCELADO","ATRASADO","A_RECEBER"]},"ano":{"type":"integer","required":false,"description":"Ano."},"dataInicio":{"type":"string (YYYY-MM-DD)","required":false,"description":"Data de pagamento inicial."},"dataFim":{"type":"string (YYYY-MM-DD)","required":false,"description":"Data de pagamento final."},"tagIds":{"type":"string","required":false,"description":"UUIDs de tags separados por vírgula."},"origem":{"type":"string","required":false,"description":"Origem.","enum":["banco","especie"]}}},"equivalentMcp":"consultar_financeiro"},{"method":"POST","path":"/api/v1/financeiro","description":"Criar lançamento.","auth":true,"adminOnly":true,"params":{"body":{"tipo":{"type":"string","required":true,"description":"Tipo do lançamento.","enum":["RECEITA","DESPESA","DOACAO"]},"status":{"type":"string","required":false,"description":"Situação.","default":"PENDENTE","enum":["PENDENTE","PAGO","CANCELADO","ATRASADO","A_RECEBER"]},"descricao":{"type":"string","required":true,"description":"Descrição original."},"valor":{"type":"number","required":false,"description":"Valor positivo; opcional quando itens é informado."},"dataVencimento":{"type":"string (date)","required":false,"description":"Vencimento."},"dataPagamento":{"type":"string (date)","required":false,"description":"Pagamento."},"irmaoId":{"type":"string (UUID)","required":false,"description":"Irmão relacionado."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"contaBancariaId":{"type":"string (UUID)","required":true,"description":"Conta bancária."},"observacoes":{"type":"string","required":false,"description":"Observações."},"mensalidadeIrmaoId":{"type":"string (UUID)","required":false,"description":"Rateio relacionado."},"tituloAlternativo":{"type":"string","required":false,"description":"Título exibido no lugar da descrição."},"tagIds":{"type":"string[]","required":false,"description":"Tags vinculadas."},"itens":{"type":"array","required":false,"description":"Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto."}}}},{"method":"GET","path":"/api/v1/financeiro/:id","description":"Obter lançamento.","auth":true,"adminOnly":false,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"PUT","path":"/api/v1/financeiro/:id","description":"Atualizar lançamento.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"tipo":{"type":"string","required":true,"description":"Tipo do lançamento.","enum":["RECEITA","DESPESA","DOACAO"]},"status":{"type":"string","required":false,"description":"Situação.","default":"PENDENTE","enum":["PENDENTE","PAGO","CANCELADO","ATRASADO","A_RECEBER"]},"descricao":{"type":"string","required":true,"description":"Descrição original."},"valor":{"type":"number","required":false,"description":"Valor positivo; opcional quando itens é informado."},"dataVencimento":{"type":"string (date)","required":false,"description":"Vencimento."},"dataPagamento":{"type":"string (date)","required":false,"description":"Pagamento."},"irmaoId":{"type":"string (UUID)","required":false,"description":"Irmão relacionado."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"contaBancariaId":{"type":"string (UUID)","required":true,"description":"Conta bancária."},"observacoes":{"type":"string","required":false,"description":"Observações."},"mensalidadeIrmaoId":{"type":"string (UUID)","required":false,"description":"Rateio relacionado."},"tituloAlternativo":{"type":"string","required":false,"description":"Título exibido no lugar da descrição."},"tagIds":{"type":"string[]","required":false,"description":"Tags vinculadas."},"itens":{"type":"array","required":false,"description":"Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto."}}}},{"method":"DELETE","path":"/api/v1/financeiro/:id","description":"Excluir lançamento.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"POST","path":"/api/v1/financeiro/import-ofx","description":"Importar OFX; duplicados por FITID são ignorados.","auth":true,"adminOnly":true,"contentType":"multipart/form-data","params":{"body":{"file":{"type":"File (.ofx)","required":true,"description":"Arquivo OFX."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"contaBancariaId":{"type":"string (UUID)","required":true,"description":"Conta."}}}},{"method":"GET","path":"/api/v1/financeiro/relatorio","description":"Relatório filtrado do caixa com insights.","auth":true,"params":{"query":{"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"dataInicio":{"type":"string (YYYY-MM-DD)","required":false,"description":"Início."},"dataFim":{"type":"string (YYYY-MM-DD)","required":false,"description":"Fim."},"tagIds":{"type":"string","required":false,"description":"UUIDs de tags separados por vírgula."},"irmaoId":{"type":"string (UUID)","required":false,"description":"Irmão."},"tipo":{"type":"string","required":false,"description":"Tipo."},"status":{"type":"string","required":false,"description":"Status."},"contaBancariaId":{"type":"string (UUID)","required":false,"description":"Conta."},"search":{"type":"string","required":false,"description":"Busca."}}},"notes":["Exige pelo menos um filtro além de lojaId."]},{"method":"POST","path":"/api/v1/financeiro/:id/converter-especie","description":"Depositar dinheiro em conta corrente.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"financeiroBancoId":{"type":"string (UUID)","required":false,"description":"Lançamento bancário existente."},"contaBancariaId":{"type":"string (UUID)","required":false,"description":"Conta para gerar o crédito."}}}},{"method":"DELETE","path":"/api/v1/financeiro/:id/converter-especie","description":"Desfazer depósito.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"GET","path":"/api/v1/doacoes","description":"Listar doações em banco e espécie.","auth":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."},"lojaId":{"type":"string (UUID)","required":false,"description":"Loja."},"irmaoId":{"type":"string (UUID)","required":false,"description":"Irmão."},"dataInicio":{"type":"string (YYYY-MM-DD)","required":false,"description":"Início."},"dataFim":{"type":"string (YYYY-MM-DD)","required":false,"description":"Fim."},"tagIds":{"type":"string","required":false,"description":"UUIDs de tags separados por vírgula."}}}},{"method":"GET","path":"/api/v1/contas-bancarias","description":"Listar contas.","auth":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."},"lojaId":{"type":"string (UUID)","required":false,"description":"Loja."},"ativa":{"type":"boolean","required":false,"description":"Status."},"incluirEspecie":{"type":"boolean","required":false,"description":"Incluir conta virtual de espécie.","default":false}}},"equivalentMcp":"listar_contas_bancarias"},{"method":"POST","path":"/api/v1/contas-bancarias","description":"Criar conta.","auth":true,"adminOnly":true,"params":{"body":{"banco":{"type":"string","required":true,"description":"Banco."},"agencia":{"type":"string","required":true,"description":"Agência."},"conta":{"type":"string","required":true,"description":"Conta."},"tipoConta":{"type":"string","required":false,"description":"Tipo.","default":"CORRENTE","enum":["CORRENTE","POUPANCA","INVESTIMENTO","OUTRO"]},"titular":{"type":"string","required":false,"description":"Titular."},"chavePix":{"type":"string","required":false,"description":"Chave Pix."},"descricao":{"type":"string","required":false,"description":"Descrição."},"ativa":{"type":"boolean","required":false,"description":"Ativa.","default":true},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."}}}},{"method":"GET","path":"/api/v1/contas-bancarias/:id","description":"Obter conta.","auth":true,"adminOnly":false,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"PUT","path":"/api/v1/contas-bancarias/:id","description":"Atualizar conta.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"banco":{"type":"string","required":true,"description":"Banco."},"agencia":{"type":"string","required":true,"description":"Agência."},"conta":{"type":"string","required":true,"description":"Conta."},"tipoConta":{"type":"string","required":false,"description":"Tipo.","default":"CORRENTE","enum":["CORRENTE","POUPANCA","INVESTIMENTO","OUTRO"]},"titular":{"type":"string","required":false,"description":"Titular."},"chavePix":{"type":"string","required":false,"description":"Chave Pix."},"descricao":{"type":"string","required":false,"description":"Descrição."},"ativa":{"type":"boolean","required":false,"description":"Ativa.","default":true},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."}}}},{"method":"DELETE","path":"/api/v1/contas-bancarias/:id","description":"Excluir conta sem vínculos.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}}]},{"group":"Cobranças, créditos e débitos","description":"Mensalidades, rateios, créditos, débitos e abatimentos.","routes":[{"method":"GET","path":"/api/v1/mensalidades","description":"Listar cobranças.","auth":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."},"lojaId":{"type":"string (UUID)","required":false,"description":"Loja."},"potenciaId":{"type":"string (UUID)","required":false,"description":"Potência."},"tipo":{"type":"string","required":false,"description":"Tipo.","enum":["MENSALIDADE","OUTROS"]},"tagIds":{"type":"string","required":false,"description":"UUIDs de tags separados por vírgula."}}},"equivalentMcp":"listar_mensalidades"},{"method":"POST","path":"/api/v1/mensalidades","description":"Criar cobrança.","auth":true,"adminOnly":true,"params":{"body":{"nome":{"type":"string","required":true,"description":"Nome da cobrança."},"descricao":{"type":"string","required":false,"description":"Descrição."},"tipo":{"type":"string","required":false,"description":"Tipo da cobrança.","default":"MENSALIDADE","enum":["MENSALIDADE","OUTROS"]},"dataVencimento":{"type":"string (date)","required":true,"description":"Vencimento."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"ativa":{"type":"boolean","required":false,"description":"Cobrança ativa.","default":true},"itens":{"type":"array","required":true,"description":"Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto."},"tagIds":{"type":"string[]","required":false,"description":"Tags vinculadas."}}}},{"method":"GET","path":"/api/v1/mensalidades/:id","description":"Obter cobrança.","auth":true,"adminOnly":false,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"PUT","path":"/api/v1/mensalidades/:id","description":"Atualizar cobrança.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"nome":{"type":"string","required":true,"description":"Nome da cobrança."},"descricao":{"type":"string","required":false,"description":"Descrição."},"tipo":{"type":"string","required":false,"description":"Tipo da cobrança.","default":"MENSALIDADE","enum":["MENSALIDADE","OUTROS"]},"dataVencimento":{"type":"string (date)","required":true,"description":"Vencimento."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"ativa":{"type":"boolean","required":false,"description":"Cobrança ativa.","default":true},"itens":{"type":"array","required":true,"description":"Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto."},"tagIds":{"type":"string[]","required":false,"description":"Tags vinculadas."}}}},{"method":"DELETE","path":"/api/v1/mensalidades/:id","description":"Excluir cobrança.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"POST","path":"/api/v1/mensalidades/:id/irmaos","description":"Vincular irmãos à cobrança.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"irmaoIds":{"type":"string[]","required":true,"description":"Irmãos."},"contaBancariaId":{"type":"string (UUID)","required":true,"description":"Conta para pagamentos."}}}},{"method":"DELETE","path":"/api/v1/mensalidades/:id/irmaos","description":"Desvincular irmãos.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"irmaoId":{"type":"string (UUID)","required":true,"description":"Irmão a desvincular."}}}},{"method":"PUT","path":"/api/v1/mensalidades/:id/irmaos/:irmaoId/itens","description":"Personalizar itens do rateio.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."},"irmaoId":{"type":"string (UUID)","required":true,"description":"Irmão."}},"body":{"itens":{"type":"array","required":true,"description":"Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto."}}}},{"method":"DELETE","path":"/api/v1/mensalidades/:id/irmaos/:irmaoId/itens","description":"Restaurar itens padrão.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."},"irmaoId":{"type":"string (UUID)","required":true,"description":"Irmão."}}}},{"method":"GET","path":"/api/v1/mensalidades/relatorio","description":"Relatório de mensalidades por período.","auth":true,"params":{"query":{"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"irmaoId":{"type":"string (UUID)","required":false,"description":"Irmão."},"dataInicio":{"type":"string (YYYY-MM-DD)","required":false,"description":"Início."},"dataFim":{"type":"string (YYYY-MM-DD)","required":false,"description":"Fim."}}},"equivalentMcp":"consultar_mensalidades_irmao"},{"method":"GET","path":"/api/v1/mensalidades/situacoes","description":"Listar situações dos irmãos na loja.","auth":true,"params":{"query":{"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."}}}},{"method":"GET","path":"/api/v1/mensalidades/cruzamento","description":"Consultar cruzamento de cobranças e créditos.","auth":true,"adminOnly":false,"params":{"query":{"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"dataInicio":{"type":"string (YYYY-MM-DD)","required":false,"description":"Início."},"dataFim":{"type":"string (YYYY-MM-DD)","required":false,"description":"Fim."}}}},{"method":"POST","path":"/api/v1/mensalidades/cruzamento","description":"Vincular crédito/rateio.","auth":true,"adminOnly":true,"params":{"body":{"financeiroId":{"type":"string (UUID)","required":true,"description":"Crédito financeiro."},"irmaoId":{"type":"string (UUID)","required":true,"description":"Irmão."},"mensalidadeIrmaoId":{"type":"string (UUID)","required":false,"description":"Rateio."},"creditoOutroFim":{"type":"boolean","required":false,"description":"Destinar para outro fim."},"descricaoOutroFim":{"type":"string","required":false,"description":"Motivo quando créditoOutroFim for true."},"destinoOutroFim":{"type":"string","required":false,"description":"Destino.","enum":["OUTRO","DOACAO","DEBITO"]},"debitoId":{"type":"string (UUID)","required":false,"description":"Débito quando destino for DEBITO."},"items":{"type":"array","required":false,"description":"Modo em lote: financeiroId, irmaoId, mensalidadeIrmaoId?, creditoOutroFim? e descricaoOutroFim?."}}}},{"method":"PATCH","path":"/api/v1/mensalidades/cruzamento","description":"Alterar vínculo ou destino.","auth":true,"adminOnly":true,"params":{"body":{"financeiroId":{"type":"string (UUID)","required":true,"description":"Crédito financeiro."},"mensalidadeIrmaoId":{"type":"string (UUID | null)","required":false,"description":"Rateio ou null."},"vinculadoLoja":{"type":"boolean","required":false,"description":"Vincular ou desvincular da loja."},"descricaoVinculoLoja":{"type":"string","required":false,"description":"Descrição do vínculo com a loja."},"creditoOutroFim":{"type":"boolean","required":false,"description":"Marcar ou desmarcar outro fim."},"descricaoOutroFim":{"type":"string","required":false,"description":"Motivo do outro fim."}}}},{"method":"DELETE","path":"/api/v1/mensalidades/cruzamento","description":"Desvincular crédito.","auth":true,"adminOnly":true,"params":{"body":{"financeiroId":{"type":"string (UUID)","required":true,"description":"Crédito a desvincular."}}}},{"method":"GET","path":"/api/v1/creditos","description":"Listar créditos.","auth":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."},"lojaId":{"type":"string (UUID)","required":false,"description":"Loja."},"irmaoId":{"type":"string (UUID)","required":false,"description":"Irmão."},"status":{"type":"string","required":false,"description":"Status.","enum":["DISPONIVEL","PARCIAL","UTILIZADO","CANCELADO"]},"tagIds":{"type":"string","required":false,"description":"UUIDs de tags separados por vírgula."}}},"equivalentMcp":"listar_creditos_irmao"},{"method":"POST","path":"/api/v1/creditos","description":"Conceder crédito.","auth":true,"adminOnly":true,"params":{"body":{"irmaoId":{"type":"string (UUID)","required":true,"description":"Irmão."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"valor":{"type":"number","required":false,"description":"Valor; omita se enviar itens."},"data":{"type":"string (date)","required":true,"description":"Data."},"motivo":{"type":"string","required":true,"description":"Motivo visível no extrato."},"observacoes":{"type":"string","required":false,"description":"Observações."},"registrarDespesa":{"type":"boolean","required":false,"description":"Registrar despesa.","default":false},"contaBancariaId":{"type":"string (UUID)","required":false,"description":"Conta da despesa."},"tagIds":{"type":"string[]","required":false,"description":"Tags."},"itens":{"type":"array","required":false,"description":"Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto."}}},"equivalentMcp":"criar_credito_irmao"},{"method":"GET","path":"/api/v1/creditos/:id","description":"Obter crédito.","auth":true,"adminOnly":false,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"PATCH","path":"/api/v1/creditos/:id","description":"Atualizar ou cancelar crédito.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"valor":{"type":"number","required":false,"description":"Novo valor."},"data":{"type":"string (date)","required":false,"description":"Nova data."},"motivo":{"type":"string","required":false,"description":"Novo motivo."},"observacoes":{"type":"string","required":false,"description":"Observações."},"status":{"type":"string","required":false,"description":"Somente cancelamento.","enum":["CANCELADO"]},"tagIds":{"type":"string[]","required":false,"description":"Tags."},"itens":{"type":"array","required":false,"description":"Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto."}}}},{"method":"POST","path":"/api/v1/creditos/:id/aplicacoes","description":"Aplicar crédito em uma cobrança.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"mensalidadeIrmaoId":{"type":"string (UUID)","required":true,"description":"Rateio."},"valor":{"type":"number","required":true,"description":"Valor."}}},"equivalentMcp":"aplicar_credito_irmao"},{"method":"DELETE","path":"/api/v1/creditos/:id/aplicacoes/:aplicacaoId","description":"Estornar aplicação.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."},"aplicacaoId":{"type":"string (UUID)","required":true,"description":"Aplicação."}}}},{"method":"GET","path":"/api/v1/debitos","description":"Listar débitos.","auth":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."},"lojaId":{"type":"string (UUID)","required":false,"description":"Loja."},"irmaoId":{"type":"string (UUID)","required":false,"description":"Irmão."},"status":{"type":"string","required":false,"description":"Status.","enum":["ABERTO","QUITADO","CANCELADO"]},"tagIds":{"type":"string","required":false,"description":"UUIDs de tags separados por vírgula."}}},"equivalentMcp":"listar_debitos_irmao"},{"method":"POST","path":"/api/v1/debitos","description":"Lançar débito.","auth":true,"adminOnly":true,"params":{"body":{"irmaoId":{"type":"string (UUID)","required":true,"description":"Irmão."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"valor":{"type":"number","required":false,"description":"Valor; omita se enviar itens."},"data":{"type":"string (date)","required":true,"description":"Data."},"titulo":{"type":"string","required":true,"description":"Título visível no extrato."},"detalhes":{"type":"string","required":false,"description":"Detalhes."},"tagIds":{"type":"string[]","required":false,"description":"Tags."},"itens":{"type":"array","required":false,"description":"Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto."}}},"equivalentMcp":"criar_debito_irmao"},{"method":"GET","path":"/api/v1/debitos/:id","description":"Obter débito.","auth":true,"adminOnly":false,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"PATCH","path":"/api/v1/debitos/:id","description":"Atualizar ou cancelar débito.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"valor":{"type":"number","required":false,"description":"Novo valor."},"data":{"type":"string (date)","required":false,"description":"Nova data."},"titulo":{"type":"string","required":false,"description":"Novo título."},"detalhes":{"type":"string","required":false,"description":"Detalhes."},"status":{"type":"string","required":false,"description":"Somente cancelamento.","enum":["CANCELADO"]},"tagIds":{"type":"string[]","required":false,"description":"Tags."},"itens":{"type":"array","required":false,"description":"Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto."}}}},{"method":"POST","path":"/api/v1/debitos/:id/aplicacoes","description":"Abater débito com crédito.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"creditoId":{"type":"string (UUID)","required":true,"description":"Crédito."},"valor":{"type":"number","required":true,"description":"Valor."}}}}]},{"group":"Tags, relatórios e auditoria","description":"Classificação do caixa, links de relatório e trilha de auditoria.","routes":[{"method":"GET","path":"/api/v1/tags","description":"Listar tags.","auth":true,"params":{"query":{"lojaId":{"type":"string (UUID)","required":false,"description":"Filtrar por loja."},"q":{"type":"string","required":false,"description":"Busca typeahead."},"search":{"type":"string","required":false,"description":"Alias de q."},"incluirOcultas":{"type":"boolean","required":false,"description":"Incluir ocultas.","default":false},"comUsos":{"type":"boolean","required":false,"description":"Incluir contagem de usos.","default":false}}}},{"method":"POST","path":"/api/v1/tags","description":"Criar tag.","auth":true,"adminOnly":true,"params":{"body":{"nome":{"type":"string","required":true,"description":"Nome."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."}}}},{"method":"PATCH","path":"/api/v1/tags/:id","description":"Renomear ou ocultar tag.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"nome":{"type":"string","required":false,"description":"Novo nome."},"oculta":{"type":"boolean","required":false,"description":"Ocultar ou exibir."}}}},{"method":"DELETE","path":"/api/v1/tags/:id","description":"Excluir tag e vínculos.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"POST","path":"/api/v1/tags/:id/substituir","description":"Migrar vínculos e apagar tag de origem.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"tagDestinoId":{"type":"string (UUID)","required":true,"description":"Tag destino."}}}},{"method":"GET","path":"/api/v1/relatorios-caixa","description":"Listar links de relatório.","auth":true,"params":{"query":{"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."}}}},{"method":"POST","path":"/api/v1/relatorios-caixa","description":"Criar link temporário de relatório.","auth":true,"adminOnly":true,"params":{"body":{"titulo":{"type":"string","required":true,"description":"Título."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"filtros":{"type":"object","required":true,"description":"Filtros do relatório."},"dias":{"type":"integer (1-60)","required":true,"description":"Validade em dias."}}}},{"method":"PATCH","path":"/api/v1/relatorios-caixa/:id","description":"Renovar validade.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"dias":{"type":"integer (1-60)","required":true,"description":"Nova validade."}}}},{"method":"DELETE","path":"/api/v1/relatorios-caixa/:id","description":"Excluir link.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"GET","path":"/api/v1/tesouraria-log","description":"Consultar trilha de auditoria.","auth":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."},"lojaId":{"type":"string (UUID)","required":false,"description":"Loja."},"acao":{"type":"string","required":false,"description":"Ação."},"entidade":{"type":"string","required":false,"description":"Entidade."},"dataInicio":{"type":"string (YYYY-MM-DD)","required":false,"description":"Início."},"dataFim":{"type":"string (YYYY-MM-DD)","required":false,"description":"Fim."}}}},{"method":"GET","path":"/api/v1/chamadas","description":"Histórico de chamadas da API e do MCP.","auth":true,"adminOnly":true,"notes":["Cada chamada /api/v1 e MCP gera um evento com data, rota, status e autor.","Não inclui corpo, query string nem o valor do token.","Links públicos gravam a rota com :token no lugar do segredo."],"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."},"origem":{"type":"string","required":false,"description":"API ou MCP.","enum":["API","MCP"]},"metodo":{"type":"string","required":false,"description":"Método HTTP.","enum":["GET","POST","PUT","PATCH","DELETE"]},"dataInicio":{"type":"string (YYYY-MM-DD)","required":false,"description":"Início."},"dataFim":{"type":"string (YYYY-MM-DD)","required":false,"description":"Fim."}}}}]},{"group":"Mensagens, e-mail e atendimento","description":"Templates, envios, inbox e integração WhatsApp.","routes":[{"method":"GET","path":"/api/v1/contato/desafio","description":"Gerar desafio HMAC do formulário público.","auth":false},{"method":"POST","path":"/api/v1/contato","description":"Enviar contato público.","auth":false,"contentType":"multipart/form-data","params":{"body":{"tipo":{"type":"string","required":true,"description":"Tipo.","enum":["SUPORTE","DUVIDA","PAGAMENTOS","OUTROS","SOLICITAR_EXTRATO"]},"cim":{"type":"string (1-7 dígitos)","required":true,"description":"CIM."},"descricao":{"type":"string","required":false,"description":"Descrição; dispensada ao solicitar extrato."},"valor":{"type":"number","required":false,"description":"Obrigatório para PAGAMENTOS."},"desafio":{"type":"string","required":true,"description":"Desafio HMAC."},"anexos":{"type":"File[]","required":false,"description":"Até 5 arquivos de 10 MB."},"website":{"type":"string","required":false,"description":"Honeypot; deixe vazio."},"company":{"type":"string","required":false,"description":"Honeypot; deixe vazio."}}}},{"method":"GET","path":"/api/v1/contato","description":"Listar inbox.","auth":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."},"tipo":{"type":"string","required":false,"description":"Tipo."},"status":{"type":"string","required":false,"description":"Status.","enum":["NAO_LIDA","LIDA"]}}}},{"method":"GET","path":"/api/v1/contato/:id","description":"Obter mensagem.","auth":true,"adminOnly":false,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"PATCH","path":"/api/v1/contato/:id","description":"Alterar status.","auth":true,"adminOnly":false,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"status":{"type":"string","required":true,"description":"Status.","enum":["NAO_LIDA","LIDA"]}}}},{"method":"DELETE","path":"/api/v1/contato/:id","description":"Excluir mensagem.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"POST","path":"/api/v1/atendimentos","description":"Criar atendimento por telefone.","auth":true,"params":{"body":{"telefone":{"type":"string","required":true,"description":"Telefone WhatsApp."},"texto":{"type":"string","required":true,"description":"Texto com 10 a 4000 caracteres."},"tipo":{"type":"string","required":false,"description":"Tipo.","default":"OUTROS"}}},"equivalentMcp":"criar_atendimento"},{"method":"POST","path":"/api/v1/whatsapp/validar-telefone","description":"Identificar irmão ativo por telefone.","auth":true,"params":{"body":{"telefone":{"type":"string","required":true,"description":"Telefone sem + (DDI + DDD + número, com ou sem 9º dígito) ou JID Baileys. Ex.: 556788776655.","example":"556788776655"},"plataforma":{"type":"string","required":false,"description":"Origem.","enum":["meta","baileys"]}}},"equivalentMcp":"identificar_irmao"},{"method":"POST","path":"/api/v1/whatsapp/cobrancas/gerar-link","description":"Gerar link temporário da tabela de cobranças.","auth":true,"params":{"body":{"irmaoId":{"type":"string (UUID)","required":true,"description":"Irmão."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"expiracaoMinutos":{"type":"integer","required":false,"description":"Validade em minutos."},"expiracaoDias":{"type":"integer","required":false,"description":"Validade em dias."}}},"notes":["Informe expiracaoMinutos ou expiracaoDias; expiracaoDias tem prioridade."]},{"method":"GET","path":"/api/v1/whatsapp/historico","description":"Listar histórico de envios.","auth":true,"adminOnly":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."},"irmaoId":{"type":"string (UUID)","required":false,"description":"Irmão."},"templateId":{"type":"string (UUID)","required":false,"description":"Template WhatsApp."},"emailTemplateId":{"type":"string (UUID)","required":false,"description":"Template de e-mail."},"canal":{"type":"string","required":false,"description":"Canal.","enum":["WHATSAPP","EMAIL"]},"sucesso":{"type":"boolean","required":false,"description":"Filtrar sucesso."}}}},{"method":"GET","path":"/api/v1/whatsapp/variaveis","description":"Listar variáveis permitidas em templates.","auth":true,"adminOnly":true},{"method":"POST","path":"/api/v1/whatsapp/enviar","description":"Enviar template WhatsApp.","auth":true,"adminOnly":true,"params":{"body":{"templateId":{"type":"string (UUID)","required":true,"description":"Template."},"irmaoId":{"type":"string (UUID)","required":false,"description":"Irmão."},"irmaoIds":{"type":"string[]","required":false,"description":"Irmãos."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"enviarParaTodos":{"type":"boolean","required":false,"description":"Enviar para todos.","default":false}}}},{"method":"GET","path":"/api/v1/whatsapp/templates","description":"Listar templates WhatsApp.","auth":true,"adminOnly":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."}}}},{"method":"POST","path":"/api/v1/whatsapp/templates","description":"Criar template WhatsApp.","auth":true,"adminOnly":true,"params":{"body":{"nome":{"type":"string","required":true,"description":"Nome do template."},"conteudo":{"type":"string","required":true,"description":"Conteúdo."},"descricao":{"type":"string","required":false,"description":"Descrição."},"ativo":{"type":"boolean","required":false,"description":"Template ativo.","default":true}}}},{"method":"GET","path":"/api/v1/whatsapp/templates/:id","description":"Obter template WhatsApp.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"PUT","path":"/api/v1/whatsapp/templates/:id","description":"Atualizar template.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"nome":{"type":"string","required":true,"description":"Nome do template."},"conteudo":{"type":"string","required":true,"description":"Conteúdo."},"descricao":{"type":"string","required":false,"description":"Descrição."},"ativo":{"type":"boolean","required":false,"description":"Template ativo.","default":true}}}},{"method":"DELETE","path":"/api/v1/whatsapp/templates/:id","description":"Excluir template.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"GET","path":"/api/v1/emails/templates","description":"Listar templates de e-mail.","auth":true,"adminOnly":true,"params":{"query":{"page":{"type":"integer","required":false,"description":"Página, iniciando em 1.","default":1},"limit":{"type":"integer","required":false,"description":"Itens por página (máximo 500).","default":20},"pageSize":{"type":"integer","required":false,"description":"Alias de limit.","default":20},"search":{"type":"string","required":false,"description":"Texto de busca."}}}},{"method":"POST","path":"/api/v1/emails/templates","description":"Criar template de e-mail.","auth":true,"adminOnly":true,"params":{"body":{"nome":{"type":"string","required":true,"description":"Nome do template."},"assunto":{"type":"string","required":true,"description":"Assunto."},"bodyHtml":{"type":"string (HTML)","required":true,"description":"Corpo HTML."},"headerTitle":{"type":"string","required":false,"description":"Título do cabeçalho."},"ativo":{"type":"boolean","required":false,"description":"Template ativo.","default":true}}}},{"method":"GET","path":"/api/v1/emails/templates/:id","description":"Obter template de e-mail.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"PUT","path":"/api/v1/emails/templates/:id","description":"Atualizar template.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}},"body":{"nome":{"type":"string","required":true,"description":"Nome do template."},"assunto":{"type":"string","required":true,"description":"Assunto."},"bodyHtml":{"type":"string (HTML)","required":true,"description":"Corpo HTML."},"headerTitle":{"type":"string","required":false,"description":"Título do cabeçalho."},"ativo":{"type":"boolean","required":false,"description":"Template ativo.","default":true}}}},{"method":"DELETE","path":"/api/v1/emails/templates/:id","description":"Excluir template.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"POST","path":"/api/v1/emails/enviar","description":"Enviar e-mail a um irmão.","auth":true,"adminOnly":true,"params":{"body":{"templateId":{"type":"string (UUID)","required":true,"description":"Template."},"irmaoId":{"type":"string (UUID)","required":true,"description":"Irmão."}}}},{"method":"POST","path":"/api/v1/emails/teste","description":"Enviar e-mail de teste.","auth":true,"adminOnly":true,"params":{"body":{"templateId":{"type":"string (UUID)","required":true,"description":"Template."},"lojaId":{"type":"string (UUID)","required":true,"description":"Loja."},"irmaoId":{"type":"string (UUID)","required":false,"description":"Irmão; informe irmão ou e-mail."},"email":{"type":"string (email)","required":false,"description":"Destinatário; informe irmão ou e-mail."}}}},{"method":"POST","path":"/api/v1/emails/preview","description":"Gerar prévia renderizada.","auth":true,"adminOnly":true,"params":{"body":{"bodyHtml":{"type":"string (HTML)","required":true,"description":"Corpo HTML."},"assunto":{"type":"string","required":false,"description":"Assunto.","default":""},"headerTitle":{"type":"string","required":false,"description":"Título do cabeçalho."},"lojaId":{"type":"string (UUID)","required":false,"description":"Loja."},"irmaoId":{"type":"string (UUID)","required":false,"description":"Irmão."}}}},{"method":"POST","path":"/api/v1/emails/validar","description":"Validar HTML com IA quando configurada.","auth":true,"adminOnly":true,"params":{"body":{"content":{"type":"string (HTML)","required":true,"description":"HTML para validar."}}}}]},{"group":"Configuração, anexos e dashboard","description":"Configuração da loja, arquivos e estatísticas.","routes":[{"method":"GET","path":"/api/v1/configuracoes","description":"Obter configuração.","auth":true},{"method":"PUT","path":"/api/v1/configuracoes","description":"Atualizar padrões e contatos notificados.","auth":true,"adminOnly":true,"params":{"body":{"potenciaId":{"type":"string (UUID)","required":false,"description":"Potência padrão."},"lojaId":{"type":"string (UUID)","required":false,"description":"Loja padrão."},"contatoNotificarIrmaoIds":{"type":"string[]","required":false,"description":"Irmãos notificados."}}}},{"method":"GET","path":"/api/v1/dashboard","description":"Obter estatísticas gerais.","auth":true,"equivalentMcp":"estatisticas_dashboard"},{"method":"GET","path":"/api/v1/anexos","description":"Listar anexos de uma entidade.","auth":true,"params":{"query":{"entidade":{"type":"string","required":true,"description":"Tipo da entidade."},"entidadeId":{"type":"string (UUID)","required":true,"description":"Entidade."}}}},{"method":"POST","path":"/api/v1/anexos","description":"Enviar anexo.","auth":true,"adminOnly":true,"contentType":"multipart/form-data","params":{"body":{"file":{"type":"File","required":true,"description":"Arquivo."},"entidade":{"type":"string","required":true,"description":"Tipo da entidade."},"entidadeId":{"type":"string (UUID)","required":true,"description":"Entidade."}}}},{"method":"GET","path":"/api/v1/anexos/:id/download","description":"Baixar anexo.","auth":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}},{"method":"DELETE","path":"/api/v1/anexos/:id","description":"Excluir anexo.","auth":true,"adminOnly":true,"params":{"path":{"id":{"type":"string (UUID)","required":true,"description":"Identificador do recurso."}}}}]},{"group":"MCP e documentação","description":"Descoberta e chamada das ferramentas de IA.","routes":[{"method":"POST","path":"/api/v1/mcp","description":"Streamable HTTP (JSON-RPC) ou REST de compatibilidade ({ tool, arguments }).","auth":true,"notes":["Clientes MCP enviam JSON-RPC 2.0 (initialize, tools/list, tools/call).","Body { tool, arguments } continua suportado para agentes HTTP simples."],"params":{"body":{"jsonrpc":{"type":"string","required":false,"description":"Versão JSON-RPC (clientes MCP).","example":"2.0"},"method":{"type":"string","required":false,"description":"Método MCP, por exemplo tools/call."},"tool":{"type":"string","required":false,"description":"Nome da tool (somente modo REST)."},"arguments":{"type":"object","required":false,"description":"Argumentos da tool (modo REST).","default":{}}}}},{"method":"GET","path":"/api/v1/mcp","description":"GET Streamable HTTP (sessões/SSE). Em modo stateless costuma responder 405.","auth":true},{"method":"DELETE","path":"/api/v1/mcp","description":"Encerrar sessão Streamable HTTP, se o cliente usar sessão.","auth":true},{"method":"GET","path":"/api/v1/docs","description":"Catálogo completo em envelope ApiResponse.","auth":false}]},{"group":"Links públicos","description":"Leituras por token, sem autenticação de usuário.","routes":[{"method":"GET","path":"/api/v1/extrato-publico/:token","description":"Extrato temporário do irmão.","auth":false,"params":{"path":{"token":{"type":"string","required":true,"description":"Token público presente no link."}}}},{"method":"GET","path":"/api/v1/cobrancas-publico/:token","description":"Tabela pública temporária de cobranças.","auth":false,"params":{"path":{"token":{"type":"string","required":true,"description":"Token público presente no link."}}}},{"method":"GET","path":"/api/v1/mensalidade-publica/:token","description":"Última mensalidade em link permanente.","auth":false,"params":{"path":{"token":{"type":"string","required":true,"description":"Token público presente no link."}}},"notes":["O token é criado pela tool MCP gerar_link_mensalidade; não há rota REST de criação."]},{"method":"GET","path":"/api/v1/relatorios-caixa-publico/:token","description":"Relatório do caixa ao vivo; 410 se expirado.","auth":false,"params":{"path":{"token":{"type":"string","required":true,"description":"Token público presente no link."}}}}]}],"publicOrigin":"https://salomao.ia.br","mcp":{"name":"Salomão MCP Server","version":"1.0.0","protocolVersion":"2026-07-28","description":"Ferramentas estruturadas para agentes de IA integrarem com o Salomão.","baseUrl":"/api/v1/mcp","authentication":{"type":"Bearer Token","description":"Envie Authorization: Bearer <token>. Use JWT temporário do login ou token de API com prefixo slm_.","example":{"header":"Authorization","value":"Bearer slm_SEU_TOKEN"}},"transports":[{"name":"Streamable HTTP","endpoint":"POST /api/v1/mcp","description":"Protocolo MCP oficial (JSON-RPC 2.0). Use esta URL no cliente MCP com Authorization Bearer."},{"name":"REST (compatibilidade)","endpoint":"POST /api/v1/mcp","description":"Corpo: { \"tool\": \"<nome>\", \"arguments\": { ... } } — para n8n/WhatsApp sem cliente MCP."}]},"mcpTools":[{"name":"listar_irmaos","description":"Lista irmãos de uma loja maçônica com filtros opcionais","whenToUse":"Localizar irmãos por loja, status ou texto antes de outra operação.","equivalentRest":["GET /api/v1/irmaos"],"inputSchema":{"type":"object","properties":{"lojaId":{"description":"ID da loja para filtrar","type":"string"},"search":{"description":"Busca por nome, CIM ou email","type":"string"},"ativo":{"description":"Filtrar por status (default: true — só ativos)","type":"boolean"},"page":{"description":"Página (default: 1)","type":"number"},"pageSize":{"description":"Itens por página (default: 20)","type":"number"}},"additionalProperties":false},"parameters":{"lojaId":{"type":"string","required":false,"description":"ID da loja para filtrar"},"search":{"type":"string","required":false,"description":"Busca por nome, CIM ou email"},"ativo":{"type":"boolean","required":false,"description":"Filtrar por status (default: true — só ativos)"},"page":{"type":"number","required":false,"description":"Página (default: 1)"},"pageSize":{"type":"number","required":false,"description":"Itens por página (default: 20)"}},"example":{"lojaId":"<uuid>","ativo":true,"page":1}},{"name":"buscar_irmao","description":"Busca detalhes completos de um irmão pelo ID, CIM ou telefone WhatsApp (aceita +, DDI e 9º dígito opcionais)","whenToUse":"Carregar o cadastro de um irmão conhecido por ID, CIM ou telefone.","equivalentRest":["GET /api/v1/irmaos/:id"],"inputSchema":{"type":"object","properties":{"id":{"description":"UUID do irmão","type":"string"},"cim":{"description":"CIM do irmão","type":"string"},"telefone":{"description":"Telefone WhatsApp (DDI + DDD + número, sem +). Aceita espaços e com/sem 9º dígito. Ex: 556788776655","type":"string"}},"additionalProperties":false},"parameters":{"id":{"type":"string","required":false,"description":"UUID do irmão"},"cim":{"type":"string","required":false,"description":"CIM do irmão"},"telefone":{"type":"string","required":false,"description":"Telefone WhatsApp (DDI + DDD + número, sem +). Aceita espaços e com/sem 9º dígito. Ex: 556788776655"}},"example":{"cim":"123456"}},{"name":"identificar_irmao","description":"Identifica se um telefone WhatsApp pertence a um irmão ativo cadastrado. Use no início da conversa para autenticar o irmão. Aceita DDI + DDD + número sem + e sem o 9º dígito (ex.: 556788776655), além de +, espaços e JID Baileys.","whenToUse":"Primeiro passo de uma conversa WhatsApp: validar o remetente ativo.","equivalentRest":["POST /api/v1/whatsapp/validar-telefone"],"inputSchema":{"type":"object","properties":{"telefone":{"type":"string","description":"Telefone do WhatsApp sem + (ex: 556788776655 = DDI + DDD + número sem 9º dígito, 5511999887766, 11999887766 ou JID Baileys)"}},"required":["telefone"],"additionalProperties":false},"parameters":{"telefone":{"type":"string","required":true,"description":"Telefone do WhatsApp sem + (ex: 556788776655 = DDI + DDD + número sem 9º dígito, 5511999887766, 11999887766 ou JID Baileys)"}},"example":{"telefone":"556788776655"}},{"name":"listar_lojas","description":"Lista lojas maçônicas com informações de potência","whenToUse":"Descobrir a loja correta para filtros e operações.","equivalentRest":["GET /api/v1/lojas"],"inputSchema":{"type":"object","properties":{"potenciaId":{"description":"ID da potência para filtrar","type":"string"},"search":{"description":"Busca por nome ou oriente","type":"string"}},"additionalProperties":false},"parameters":{"potenciaId":{"type":"string","required":false,"description":"ID da potência para filtrar"},"search":{"type":"string","required":false,"description":"Busca por nome ou oriente"}},"example":{"search":"Salomão"}},{"name":"buscar_loja","description":"Busca detalhes de uma loja pelo ID, incluindo lista de irmãos","whenToUse":"Consultar uma loja conhecida e seus irmãos.","equivalentRest":["GET /api/v1/lojas/:id"],"inputSchema":{"type":"object","properties":{"id":{"type":"string","description":"UUID da loja"}},"required":["id"],"additionalProperties":false},"parameters":{"id":{"type":"string","required":true,"description":"UUID da loja"}},"example":{"id":"<uuid>"}},{"name":"listar_potencias","description":"Lista todas as potências maçônicas cadastradas","whenToUse":"Descobrir potências para filtrar lojas.","equivalentRest":["GET /api/v1/potencias"],"inputSchema":{"type":"object","properties":{"search":{"description":"Busca por nome ou sigla","type":"string"}},"additionalProperties":false},"parameters":{"search":{"type":"string","required":false,"description":"Busca por nome ou sigla"}},"example":{}},{"name":"consultar_financeiro","description":"Consulta lançamentos do caixa da loja (receitas, despesas, doações). Não é o extrato pessoal do irmão — use consultar_extrato_irmao para isso.","whenToUse":"Consultar lançamentos do caixa; não usar como extrato pessoal.","equivalentRest":["GET /api/v1/financeiro"],"inputSchema":{"type":"object","properties":{"potenciaId":{"description":"ID da potência para filtrar","type":"string"},"lojaId":{"description":"ID da loja","type":"string"},"irmaoId":{"description":"ID do irmão","type":"string"},"tipo":{"description":"Tipo da transação","type":"string","enum":["RECEITA","DESPESA","DOACAO"]},"status":{"description":"Status da transação","type":"string","enum":["PENDENTE","PAGO","CANCELADO","ATRASADO"]},"search":{"description":"Filtra por descrição original ou título alternativo","type":"string"}},"additionalProperties":false},"parameters":{"potenciaId":{"type":"string","required":false,"description":"ID da potência para filtrar"},"lojaId":{"type":"string","required":false,"description":"ID da loja"},"irmaoId":{"type":"string","required":false,"description":"ID do irmão"},"tipo":{"type":"string","required":false,"description":"Tipo da transação","enum":["RECEITA","DESPESA","DOACAO"]},"status":{"type":"string","required":false,"description":"Status da transação","enum":["PENDENTE","PAGO","CANCELADO","ATRASADO"]},"search":{"type":"string","required":false,"description":"Filtra por descrição original ou título alternativo"}},"example":{"lojaId":"<uuid>","tipo":"RECEITA"}},{"name":"listar_contas_bancarias","description":"Lista contas bancárias cadastradas, opcionalmente filtradas por loja","whenToUse":"Descobrir contas disponíveis para operações financeiras.","equivalentRest":["GET /api/v1/contas-bancarias"],"inputSchema":{"type":"object","properties":{"lojaId":{"description":"ID da loja para filtrar","type":"string"},"ativa":{"description":"Filtrar por status ativa/inativa","type":"boolean"}},"additionalProperties":false},"parameters":{"lojaId":{"type":"string","required":false,"description":"ID da loja para filtrar"},"ativa":{"type":"boolean","required":false,"description":"Filtrar por status ativa/inativa"}},"example":{"lojaId":"<uuid>","ativa":true}},{"name":"estatisticas_dashboard","description":"Retorna estatísticas gerais do sistema","whenToUse":"Obter uma visão agregada rápida do sistema.","equivalentRest":["GET /api/v1/dashboard"],"inputSchema":{"type":"object","properties":{},"additionalProperties":false},"parameters":{},"example":{}},{"name":"listar_mensalidades","description":"Lista mensalidades de uma loja com itens de composição e irmãos vinculados","whenToUse":"Listar cobranças e composição de uma loja.","equivalentRest":["GET /api/v1/mensalidades"],"inputSchema":{"type":"object","properties":{"lojaId":{"description":"ID da loja para filtrar","type":"string"},"search":{"description":"Busca por nome","type":"string"}},"additionalProperties":false},"parameters":{"lojaId":{"type":"string","required":false,"description":"ID da loja para filtrar"},"search":{"type":"string","required":false,"description":"Busca por nome"}},"example":{"lojaId":"<uuid>"}},{"name":"consultar_mensalidades_irmao","description":"Consulta o relatório de mensalidades de um irmão, mostrando o que foi cobrado, pago e saldo (crédito/débito)","whenToUse":"Comparar cobranças, pagamentos e saldo por irmão/período.","equivalentRest":["GET /api/v1/mensalidades/relatorio"],"inputSchema":{"type":"object","properties":{"lojaId":{"type":"string","description":"ID da loja (obrigatório)"},"irmaoId":{"description":"ID do irmão (opcional, se omitido retorna todos)","type":"string"},"dataInicio":{"description":"Data início do período (YYYY-MM-DD)","type":"string"},"dataFim":{"description":"Data fim do período (YYYY-MM-DD)","type":"string"}},"required":["lojaId"],"additionalProperties":false},"parameters":{"lojaId":{"type":"string","required":true,"description":"ID da loja (obrigatório)"},"irmaoId":{"type":"string","required":false,"description":"ID do irmão (opcional, se omitido retorna todos)"},"dataInicio":{"type":"string","required":false,"description":"Data início do período (YYYY-MM-DD)"},"dataFim":{"type":"string","required":false,"description":"Data fim do período (YYYY-MM-DD)"}},"example":{"lojaId":"<uuid>","irmaoId":"<uuid>"}},{"name":"consultar_extrato_irmao","description":"Consulta o extrato financeiro completo do irmão identificado pelo telefone WhatsApp (mensalidades, depósitos, créditos, débitos e saldo). Use após identificar_irmao.","whenToUse":"Responder perguntas financeiras pessoais após identificar o telefone.","equivalentRest":["GET /api/v1/irmaos/:id/extrato"],"inputSchema":{"type":"object","properties":{"telefone":{"type":"string","description":"Telefone WhatsApp do irmão (com ou sem +, com ou sem 9º dígito)"}},"required":["telefone"],"additionalProperties":false},"parameters":{"telefone":{"type":"string","required":true,"description":"Telefone WhatsApp do irmão (com ou sem +, com ou sem 9º dígito)"}},"example":{"telefone":"5511999887766"}},{"name":"gerar_link_extrato","description":"Gera um link público temporário (10 minutos) para o irmão visualizar seu extrato de cobranças. Use quando um irmão identificado pelo WhatsApp perguntar sobre seu extrato ou mensalidades. Identifica o irmão pelo telefone do WhatsApp. O link gerado é pessoal e mostra apenas os dados do irmão solicitante.","whenToUse":"Entregar ao irmão um link temporário do extrato; envie somente a mensagem retornada.","inputSchema":{"type":"object","properties":{"telefone":{"type":"string","description":"Telefone do irmão no formato WhatsApp (código do país + DDD + número, ex: 5567999887766)"}},"required":["telefone"],"additionalProperties":false},"parameters":{"telefone":{"type":"string","required":true,"description":"Telefone do irmão no formato WhatsApp (código do país + DDD + número, ex: 5567999887766)"}},"example":{"telefone":"5511999887766"}},{"name":"gerar_link_mensalidade","description":"Gera um link público permanente para o irmão visualizar sua última mensalidade com detalhamento de valores, descontos e dados bancários para pagamento. Diferente do extrato, este link não expira. Use quando o irmão perguntar sobre o valor da mensalidade atual, desconto, ou queira dados para pagar.","whenToUse":"Entregar a última mensalidade e dados para pagamento em link permanente.","inputSchema":{"type":"object","properties":{"telefone":{"type":"string","description":"Telefone do irmão no formato WhatsApp (código do país + DDD + número, ex: 5567999887766)"}},"required":["telefone"],"additionalProperties":false},"parameters":{"telefone":{"type":"string","required":true,"description":"Telefone do irmão no formato WhatsApp (código do país + DDD + número, ex: 5567999887766)"}},"example":{"telefone":"5511999887766"}},{"name":"criar_atendimento","description":"Registra um atendimento (somente texto, sem anexos) na inbox da loja, identificado pelo telefone WhatsApp do irmão. Também notifica a equipe pelos WhatsApps configurados em Configurações.","whenToUse":"Encaminhar para a equipe uma demanda textual do irmão.","equivalentRest":["POST /api/v1/atendimentos"],"inputSchema":{"type":"object","properties":{"telefone":{"type":"string","description":"Telefone WhatsApp do irmão (com ou sem +, com ou sem 9º dígito)"},"texto":{"type":"string","description":"Mensagem do atendimento (mínimo 10 caracteres)"},"tipo":{"description":"Tipo do atendimento (default: OUTROS)","type":"string","enum":["SUPORTE","DUVIDA","PAGAMENTOS","OUTROS","SOLICITAR_EXTRATO"]}},"required":["telefone","texto"],"additionalProperties":false},"parameters":{"telefone":{"type":"string","required":true,"description":"Telefone WhatsApp do irmão (com ou sem +, com ou sem 9º dígito)"},"texto":{"type":"string","required":true,"description":"Mensagem do atendimento (mínimo 10 caracteres)"},"tipo":{"type":"string","required":false,"description":"Tipo do atendimento (default: OUTROS)","enum":["SUPORTE","DUVIDA","PAGAMENTOS","OUTROS","SOLICITAR_EXTRATO"]}},"example":{"telefone":"5511999887766","texto":"Preciso de ajuda com meu pagamento."}},{"name":"listar_creditos_irmao","description":"Lista créditos concedidos aos irmãos (trabalhos ou gastos pela loja) e o valor ainda disponível para abater em cobranças","whenToUse":"Consultar créditos concedidos e saldo ainda disponível.","equivalentRest":["GET /api/v1/creditos"],"inputSchema":{"type":"object","properties":{"lojaId":{"type":"string","description":"ID da loja (obrigatório)"},"irmaoId":{"description":"Filtrar por irmão","type":"string"},"status":{"description":"Filtrar por situação do crédito","type":"string","enum":["DISPONIVEL","PARCIAL","UTILIZADO","CANCELADO"]}},"required":["lojaId"],"additionalProperties":false},"parameters":{"lojaId":{"type":"string","required":true,"description":"ID da loja (obrigatório)"},"irmaoId":{"type":"string","required":false,"description":"Filtrar por irmão"},"status":{"type":"string","required":false,"description":"Filtrar por situação do crédito","enum":["DISPONIVEL","PARCIAL","UTILIZADO","CANCELADO"]}},"example":{"lojaId":"<uuid>","irmaoId":"<uuid>"}},{"name":"criar_credito_irmao","description":"Concede um crédito ao irmão. O crédito fica disponível até ser aplicado manualmente em uma cobrança. Informe um motivo claro, pois o irmão verá esse texto no extrato.","whenToUse":"Conceder crédito com motivo visível no extrato.","equivalentRest":["POST /api/v1/creditos"],"inputSchema":{"type":"object","properties":{"irmaoId":{"type":"string","description":"ID do irmão"},"lojaId":{"type":"string","description":"ID da loja"},"valor":{"description":"Valor do crédito em reais (omitido se itens for informado)","type":"number"},"itens":{"description":"Composição opcional (nome, valor, desconto). Se omitido, gera um item com o valor e o motivo.","type":"array","items":{"type":"object","properties":{"nome":{"type":"string","description":"Nome do item"},"valor":{"type":"number","description":"Valor do item em reais"},"desconto":{"description":"Desconto opcional","type":"number"},"descricao":{"description":"Descrição opcional","type":"string"}},"required":["nome","valor"],"additionalProperties":false}},"data":{"description":"Data do crédito (YYYY-MM-DD)","type":"string"},"motivo":{"type":"string","description":"Motivo visível no extrato (ex.: Pagou material elétrico da sede)"}},"required":["irmaoId","lojaId","motivo"],"additionalProperties":false},"parameters":{"irmaoId":{"type":"string","required":true,"description":"ID do irmão"},"lojaId":{"type":"string","required":true,"description":"ID da loja"},"valor":{"type":"number","required":false,"description":"Valor do crédito em reais (omitido se itens for informado)"},"itens":{"type":"array","required":false,"description":"Composição opcional (nome, valor, desconto). Se omitido, gera um item com o valor e o motivo."},"data":{"type":"string","required":false,"description":"Data do crédito (YYYY-MM-DD)"},"motivo":{"type":"string","required":true,"description":"Motivo visível no extrato (ex.: Pagou material elétrico da sede)"}},"example":{"irmaoId":"<uuid>","lojaId":"<uuid>","valor":100,"data":"2026-09-19","motivo":"Reembolso de material"}},{"name":"listar_debitos_irmao","description":"Lista débitos lançados na conta do irmão (valores a mais a pagar). O título aparece no extrato.","whenToUse":"Consultar valores adicionais lançados na conta do irmão.","equivalentRest":["GET /api/v1/debitos"],"inputSchema":{"type":"object","properties":{"lojaId":{"type":"string","description":"ID da loja (obrigatório)"},"irmaoId":{"description":"Filtrar por irmão","type":"string"},"status":{"description":"Filtrar por situação do débito","type":"string","enum":["ABERTO","QUITADO","CANCELADO"]}},"required":["lojaId"],"additionalProperties":false},"parameters":{"lojaId":{"type":"string","required":true,"description":"ID da loja (obrigatório)"},"irmaoId":{"type":"string","required":false,"description":"Filtrar por irmão"},"status":{"type":"string","required":false,"description":"Filtrar por situação do débito","enum":["ABERTO","QUITADO","CANCELADO"]}},"example":{"lojaId":"<uuid>","status":"ABERTO"}},{"name":"criar_debito_irmao","description":"Lança um débito na conta do irmão (título, data, detalhes e valor). Aumenta o saldo devedor enquanto estiver em aberto.","whenToUse":"Lançar valor adicional devido por um irmão.","equivalentRest":["POST /api/v1/debitos"],"inputSchema":{"type":"object","properties":{"irmaoId":{"type":"string","description":"ID do irmão"},"lojaId":{"type":"string","description":"ID da loja"},"valor":{"description":"Valor do débito em reais (omitido se itens for informado)","type":"number"},"itens":{"description":"Composição opcional (nome, valor, desconto). Se omitido, gera um item com o título e o valor.","type":"array","items":{"type":"object","properties":{"nome":{"type":"string","description":"Nome do item"},"valor":{"type":"number","description":"Valor do item em reais"},"desconto":{"description":"Desconto opcional","type":"number"},"descricao":{"description":"Descrição opcional","type":"string"}},"required":["nome","valor"],"additionalProperties":false}},"data":{"description":"Data do débito (YYYY-MM-DD)","type":"string"},"titulo":{"type":"string","description":"Título visível no extrato"},"detalhes":{"description":"Explicação do motivo (opcional)","type":"string"}},"required":["irmaoId","lojaId","titulo"],"additionalProperties":false},"parameters":{"irmaoId":{"type":"string","required":true,"description":"ID do irmão"},"lojaId":{"type":"string","required":true,"description":"ID da loja"},"valor":{"type":"number","required":false,"description":"Valor do débito em reais (omitido se itens for informado)"},"itens":{"type":"array","required":false,"description":"Composição opcional (nome, valor, desconto). Se omitido, gera um item com o título e o valor."},"data":{"type":"string","required":false,"description":"Data do débito (YYYY-MM-DD)"},"titulo":{"type":"string","required":true,"description":"Título visível no extrato"},"detalhes":{"type":"string","required":false,"description":"Explicação do motivo (opcional)"}},"example":{"irmaoId":"<uuid>","lojaId":"<uuid>","valor":50,"data":"2026-09-19","titulo":"Evento"}},{"name":"aplicar_credito_irmao","description":"Aplica (abate) um crédito disponível em uma cobrança específica do irmão. Não aplica automaticamente em outras mensalidades.","whenToUse":"Abater manualmente crédito disponível em uma cobrança específica.","equivalentRest":["POST /api/v1/creditos/:id/aplicacoes"],"inputSchema":{"type":"object","properties":{"creditoId":{"type":"string","description":"ID do crédito"},"mensalidadeIrmaoId":{"type":"string","description":"ID do vínculo irmão-cobrança (rateio) que receberá o abatimento"},"valor":{"type":"number","description":"Valor a abater (pode ser parcial)"}},"required":["creditoId","mensalidadeIrmaoId","valor"],"additionalProperties":false},"parameters":{"creditoId":{"type":"string","required":true,"description":"ID do crédito"},"mensalidadeIrmaoId":{"type":"string","required":true,"description":"ID do vínculo irmão-cobrança (rateio) que receberá o abatimento"},"valor":{"type":"number","required":true,"description":"Valor a abater (pode ser parcial)"}},"example":{"creditoId":"<uuid>","mensalidadeIrmaoId":"<uuid>","valor":50}}]}