# Salomão MCP Server

> Referência canônica e legível por IA das tools do Salomão.

## Descoberta

- Endpoint: `https://salomao.ia.br/api/v1/mcp`
- Catálogo JSON: https://salomao.ia.br/docs/mcp.json
- REST API: https://salomao.ia.br/docs/api.md

## Autenticação

Envie Authorization: Bearer <token>. Use JWT temporário do login ou token de API com prefixo slm_.

## Transportes

### Streamable HTTP

- Endpoint: `POST /api/v1/mcp`
- Protocolo MCP oficial (JSON-RPC 2.0). Use esta URL no cliente MCP com Authorization Bearer.

### REST (compatibilidade)

- Endpoint: `POST /api/v1/mcp`
- Corpo: { "tool": "<nome>", "arguments": { ... } } — para n8n/WhatsApp sem cliente MCP.

### Exemplo REST direto

```json
{
  "tool": "identificar_irmao",
  "arguments": {
    "telefone": "5511999887766"
  }
}
```

### Exemplo JSON-RPC via SSE

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "identificar_irmao",
    "arguments": {
      "telefone": "5511999887766"
    }
  }
}
```

## Mapa de capacidades

- **Localizar irmãos por loja, status ou texto antes de outra operação.** → `listar_irmaos`
  - REST: `GET /api/v1/irmaos`
- **Carregar o cadastro de um irmão conhecido por ID, CIM ou telefone.** → `buscar_irmao`
  - REST: `GET /api/v1/irmaos/:id`
- **Primeiro passo de uma conversa WhatsApp: validar o remetente ativo.** → `identificar_irmao`
  - REST: `POST /api/v1/whatsapp/validar-telefone`
- **Descobrir a loja correta para filtros e operações.** → `listar_lojas`
  - REST: `GET /api/v1/lojas`
- **Consultar uma loja conhecida e seus irmãos.** → `buscar_loja`
  - REST: `GET /api/v1/lojas/:id`
- **Descobrir potências para filtrar lojas.** → `listar_potencias`
  - REST: `GET /api/v1/potencias`
- **Consultar lançamentos do caixa; não usar como extrato pessoal.** → `consultar_financeiro`
  - REST: `GET /api/v1/financeiro`
- **Descobrir contas disponíveis para operações financeiras.** → `listar_contas_bancarias`
  - REST: `GET /api/v1/contas-bancarias`
- **Obter uma visão agregada rápida do sistema.** → `estatisticas_dashboard`
  - REST: `GET /api/v1/dashboard`
- **Listar cobranças e composição de uma loja.** → `listar_mensalidades`
  - REST: `GET /api/v1/mensalidades`
- **Comparar cobranças, pagamentos e saldo por irmão/período.** → `consultar_mensalidades_irmao`
  - REST: `GET /api/v1/mensalidades/relatorio`
- **Responder perguntas financeiras pessoais após identificar o telefone.** → `consultar_extrato_irmao`
  - REST: `GET /api/v1/irmaos/:id/extrato`
- **Entregar ao irmão um link temporário do extrato; envie somente a mensagem retornada.** → `gerar_link_extrato`
- **Entregar a última mensalidade e dados para pagamento em link permanente.** → `gerar_link_mensalidade`
- **Encaminhar para a equipe uma demanda textual do irmão.** → `criar_atendimento`
  - REST: `POST /api/v1/atendimentos`
- **Consultar créditos concedidos e saldo ainda disponível.** → `listar_creditos_irmao`
  - REST: `GET /api/v1/creditos`
- **Conceder crédito com motivo visível no extrato.** → `criar_credito_irmao`
  - REST: `POST /api/v1/creditos`
- **Consultar valores adicionais lançados na conta do irmão.** → `listar_debitos_irmao`
  - REST: `GET /api/v1/debitos`
- **Lançar valor adicional devido por um irmão.** → `criar_debito_irmao`
  - REST: `POST /api/v1/debitos`
- **Abater manualmente crédito disponível em uma cobrança específica.** → `aplicar_credito_irmao`
  - REST: `POST /api/v1/creditos/:id/aplicacoes`

## Tools

### listar_irmaos

Lista irmãos de uma loja maçônica com filtros opcionais

**Quando usar:** Localizar irmãos por loja, status ou texto antes de outra operação.

**REST equivalente:** `GET /api/v1/irmaos`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string` | Não | ID da loja para filtrar |
| `search` | `string` | Não | Busca por nome, CIM ou email |
| `ativo` | `boolean` | Não | Filtrar por status (default: true — só ativos) |
| `page` | `number` | Não | Página (default: 1) |
| `pageSize` | `number` | Não | Itens por página (default: 20) |

#### Exemplo de argumentos

```json
{
  "lojaId": "<uuid>",
  "ativo": true,
  "page": 1
}
```

#### JSON Schema

```json
{
  "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
}
```

### buscar_irmao

Busca detalhes completos de um irmão pelo ID, CIM ou telefone WhatsApp (aceita +, DDI e 9º dígito opcionais)

**Quando usar:** Carregar o cadastro de um irmão conhecido por ID, CIM ou telefone.

**REST equivalente:** `GET /api/v1/irmaos/:id`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string` | Não | UUID do irmão |
| `cim` | `string` | Não | CIM do irmão |
| `telefone` | `string` | Não | Telefone WhatsApp (DDI + DDD + número, sem +). Aceita espaços e com/sem 9º dígito. Ex: 556788776655 |

#### Exemplo de argumentos

```json
{
  "cim": "123456"
}
```

#### JSON Schema

```json
{
  "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
}
```

### identificar_irmao

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.

**Quando usar:** Primeiro passo de uma conversa WhatsApp: validar o remetente ativo.

**REST equivalente:** `POST /api/v1/whatsapp/validar-telefone`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `telefone` | `string` | Sim | Telefone do WhatsApp sem + (ex: 556788776655 = DDI + DDD + número sem 9º dígito, 5511999887766, 11999887766 ou JID Baileys) |

#### Exemplo de argumentos

```json
{
  "telefone": "556788776655"
}
```

#### JSON Schema

```json
{
  "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
}
```

### listar_lojas

Lista lojas maçônicas com informações de potência

**Quando usar:** Descobrir a loja correta para filtros e operações.

**REST equivalente:** `GET /api/v1/lojas`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `potenciaId` | `string` | Não | ID da potência para filtrar |
| `search` | `string` | Não | Busca por nome ou oriente |

#### Exemplo de argumentos

```json
{
  "search": "Salomão"
}
```

#### JSON Schema

```json
{
  "type": "object",
  "properties": {
    "potenciaId": {
      "description": "ID da potência para filtrar",
      "type": "string"
    },
    "search": {
      "description": "Busca por nome ou oriente",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

### buscar_loja

Busca detalhes de uma loja pelo ID, incluindo lista de irmãos

**Quando usar:** Consultar uma loja conhecida e seus irmãos.

**REST equivalente:** `GET /api/v1/lojas/:id`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string` | Sim | UUID da loja |

#### Exemplo de argumentos

```json
{
  "id": "<uuid>"
}
```

#### JSON Schema

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "UUID da loja"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
```

### listar_potencias

Lista todas as potências maçônicas cadastradas

**Quando usar:** Descobrir potências para filtrar lojas.

**REST equivalente:** `GET /api/v1/potencias`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `search` | `string` | Não | Busca por nome ou sigla |

#### Exemplo de argumentos

```json
{}
```

#### JSON Schema

```json
{
  "type": "object",
  "properties": {
    "search": {
      "description": "Busca por nome ou sigla",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

### consultar_financeiro

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.

**Quando usar:** Consultar lançamentos do caixa; não usar como extrato pessoal.

**REST equivalente:** `GET /api/v1/financeiro`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `potenciaId` | `string` | Não | ID da potência para filtrar |
| `lojaId` | `string` | Não | ID da loja |
| `irmaoId` | `string` | Não | ID do irmão |
| `tipo` | `string` | Não | Tipo da transação Valores: RECEITA, DESPESA, DOACAO. |
| `status` | `string` | Não | Status da transação Valores: PENDENTE, PAGO, CANCELADO, ATRASADO. |
| `search` | `string` | Não | Filtra por descrição original ou título alternativo |

#### Exemplo de argumentos

```json
{
  "lojaId": "<uuid>",
  "tipo": "RECEITA"
}
```

#### JSON Schema

```json
{
  "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
}
```

### listar_contas_bancarias

Lista contas bancárias cadastradas, opcionalmente filtradas por loja

**Quando usar:** Descobrir contas disponíveis para operações financeiras.

**REST equivalente:** `GET /api/v1/contas-bancarias`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string` | Não | ID da loja para filtrar |
| `ativa` | `boolean` | Não | Filtrar por status ativa/inativa |

#### Exemplo de argumentos

```json
{
  "lojaId": "<uuid>",
  "ativa": true
}
```

#### JSON Schema

```json
{
  "type": "object",
  "properties": {
    "lojaId": {
      "description": "ID da loja para filtrar",
      "type": "string"
    },
    "ativa": {
      "description": "Filtrar por status ativa/inativa",
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
```

### estatisticas_dashboard

Retorna estatísticas gerais do sistema

**Quando usar:** Obter uma visão agregada rápida do sistema.

**REST equivalente:** `GET /api/v1/dashboard`

#### Exemplo de argumentos

```json
{}
```

#### JSON Schema

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

### listar_mensalidades

Lista mensalidades de uma loja com itens de composição e irmãos vinculados

**Quando usar:** Listar cobranças e composição de uma loja.

**REST equivalente:** `GET /api/v1/mensalidades`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string` | Não | ID da loja para filtrar |
| `search` | `string` | Não | Busca por nome |

#### Exemplo de argumentos

```json
{
  "lojaId": "<uuid>"
}
```

#### JSON Schema

```json
{
  "type": "object",
  "properties": {
    "lojaId": {
      "description": "ID da loja para filtrar",
      "type": "string"
    },
    "search": {
      "description": "Busca por nome",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

### consultar_mensalidades_irmao

Consulta o relatório de mensalidades de um irmão, mostrando o que foi cobrado, pago e saldo (crédito/débito)

**Quando usar:** Comparar cobranças, pagamentos e saldo por irmão/período.

**REST equivalente:** `GET /api/v1/mensalidades/relatorio`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string` | Sim | ID da loja (obrigatório) |
| `irmaoId` | `string` | Não | ID do irmão (opcional, se omitido retorna todos) |
| `dataInicio` | `string` | Não | Data início do período (YYYY-MM-DD) |
| `dataFim` | `string` | Não | Data fim do período (YYYY-MM-DD) |

#### Exemplo de argumentos

```json
{
  "lojaId": "<uuid>",
  "irmaoId": "<uuid>"
}
```

#### JSON Schema

```json
{
  "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
}
```

### consultar_extrato_irmao

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.

**Quando usar:** Responder perguntas financeiras pessoais após identificar o telefone.

**REST equivalente:** `GET /api/v1/irmaos/:id/extrato`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `telefone` | `string` | Sim | Telefone WhatsApp do irmão (com ou sem +, com ou sem 9º dígito) |

#### Exemplo de argumentos

```json
{
  "telefone": "5511999887766"
}
```

#### JSON Schema

```json
{
  "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
}
```

### gerar_link_extrato

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.

**Quando usar:** Entregar ao irmão um link temporário do extrato; envie somente a mensagem retornada.

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `telefone` | `string` | Sim | Telefone do irmão no formato WhatsApp (código do país + DDD + número, ex: 5567999887766) |

#### Exemplo de argumentos

```json
{
  "telefone": "5511999887766"
}
```

#### JSON Schema

```json
{
  "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
}
```

### gerar_link_mensalidade

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.

**Quando usar:** Entregar a última mensalidade e dados para pagamento em link permanente.

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `telefone` | `string` | Sim | Telefone do irmão no formato WhatsApp (código do país + DDD + número, ex: 5567999887766) |

#### Exemplo de argumentos

```json
{
  "telefone": "5511999887766"
}
```

#### JSON Schema

```json
{
  "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
}
```

### criar_atendimento

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.

**Quando usar:** Encaminhar para a equipe uma demanda textual do irmão.

**REST equivalente:** `POST /api/v1/atendimentos`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `telefone` | `string` | Sim | Telefone WhatsApp do irmão (com ou sem +, com ou sem 9º dígito) |
| `texto` | `string` | Sim | Mensagem do atendimento (mínimo 10 caracteres) |
| `tipo` | `string` | Não | Tipo do atendimento (default: OUTROS) Valores: SUPORTE, DUVIDA, PAGAMENTOS, OUTROS, SOLICITAR_EXTRATO. |

#### Exemplo de argumentos

```json
{
  "telefone": "5511999887766",
  "texto": "Preciso de ajuda com meu pagamento."
}
```

#### JSON Schema

```json
{
  "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
}
```

### listar_creditos_irmao

Lista créditos concedidos aos irmãos (trabalhos ou gastos pela loja) e o valor ainda disponível para abater em cobranças

**Quando usar:** Consultar créditos concedidos e saldo ainda disponível.

**REST equivalente:** `GET /api/v1/creditos`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string` | Sim | ID da loja (obrigatório) |
| `irmaoId` | `string` | Não | Filtrar por irmão |
| `status` | `string` | Não | Filtrar por situação do crédito Valores: DISPONIVEL, PARCIAL, UTILIZADO, CANCELADO. |

#### Exemplo de argumentos

```json
{
  "lojaId": "<uuid>",
  "irmaoId": "<uuid>"
}
```

#### JSON Schema

```json
{
  "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
}
```

### criar_credito_irmao

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.

**Quando usar:** Conceder crédito com motivo visível no extrato.

**REST equivalente:** `POST /api/v1/creditos`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `irmaoId` | `string` | Sim | ID do irmão |
| `lojaId` | `string` | Sim | ID da loja |
| `valor` | `number` | Não | Valor do crédito em reais (omitido se itens for informado) |
| `itens` | `array` | Não | Composição opcional (nome, valor, desconto). Se omitido, gera um item com o valor e o motivo. |
| `data` | `string` | Não | Data do crédito (YYYY-MM-DD) |
| `motivo` | `string` | Sim | Motivo visível no extrato (ex.: Pagou material elétrico da sede) |

#### Exemplo de argumentos

```json
{
  "irmaoId": "<uuid>",
  "lojaId": "<uuid>",
  "valor": 100,
  "data": "2026-09-19",
  "motivo": "Reembolso de material"
}
```

#### JSON Schema

```json
{
  "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
}
```

### listar_debitos_irmao

Lista débitos lançados na conta do irmão (valores a mais a pagar). O título aparece no extrato.

**Quando usar:** Consultar valores adicionais lançados na conta do irmão.

**REST equivalente:** `GET /api/v1/debitos`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string` | Sim | ID da loja (obrigatório) |
| `irmaoId` | `string` | Não | Filtrar por irmão |
| `status` | `string` | Não | Filtrar por situação do débito Valores: ABERTO, QUITADO, CANCELADO. |

#### Exemplo de argumentos

```json
{
  "lojaId": "<uuid>",
  "status": "ABERTO"
}
```

#### JSON Schema

```json
{
  "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
}
```

### criar_debito_irmao

Lança um débito na conta do irmão (título, data, detalhes e valor). Aumenta o saldo devedor enquanto estiver em aberto.

**Quando usar:** Lançar valor adicional devido por um irmão.

**REST equivalente:** `POST /api/v1/debitos`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `irmaoId` | `string` | Sim | ID do irmão |
| `lojaId` | `string` | Sim | ID da loja |
| `valor` | `number` | Não | Valor do débito em reais (omitido se itens for informado) |
| `itens` | `array` | Não | Composição opcional (nome, valor, desconto). Se omitido, gera um item com o título e o valor. |
| `data` | `string` | Não | Data do débito (YYYY-MM-DD) |
| `titulo` | `string` | Sim | Título visível no extrato |
| `detalhes` | `string` | Não | Explicação do motivo (opcional) |

#### Exemplo de argumentos

```json
{
  "irmaoId": "<uuid>",
  "lojaId": "<uuid>",
  "valor": 50,
  "data": "2026-09-19",
  "titulo": "Evento"
}
```

#### JSON Schema

```json
{
  "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
}
```

### aplicar_credito_irmao

Aplica (abate) um crédito disponível em uma cobrança específica do irmão. Não aplica automaticamente em outras mensalidades.

**Quando usar:** Abater manualmente crédito disponível em uma cobrança específica.

**REST equivalente:** `POST /api/v1/creditos/:id/aplicacoes`

#### Parâmetros

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `creditoId` | `string` | Sim | ID do crédito |
| `mensalidadeIrmaoId` | `string` | Sim | ID do vínculo irmão-cobrança (rateio) que receberá o abatimento |
| `valor` | `number` | Sim | Valor a abater (pode ser parcial) |

#### Exemplo de argumentos

```json
{
  "creditoId": "<uuid>",
  "mensalidadeIrmaoId": "<uuid>",
  "valor": 50
}
```

#### JSON Schema

```json
{
  "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
}
```