# Salomão REST API

> Referência canônica e legível por IA para integração com o sistema Salomão.

## Descoberta

- URL base: `https://salomao.ia.br/api/v1`
- Catálogo JSON: https://salomao.ia.br/docs/api.json
- Documentação MCP: https://salomao.ia.br/docs/mcp.md

## Autenticação

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

```http
Authorization: Bearer slm_SEU_TOKEN
```

## Mapa de capacidades

### Autenticar integração
- `POST /api/v1/auth/login`
- `POST /api/v1/tokens`

### Identificar irmão por CPF, CIM ou telefone
- `POST /api/v1/irmaos/identificar`

### Identificar irmão por WhatsApp
- `POST /api/v1/whatsapp/validar-telefone`

### Consultar extrato do irmão
- `GET /api/v1/irmaos/:id/extrato`

### Gerar link público de cobrança
- `POST /api/v1/whatsapp/cobrancas/gerar-link`

### Integrar agente por MCP
- `POST /api/v1/mcp`

### Consultar caixa e relatórios
- `GET /api/v1/financeiro`
- `GET /api/v1/financeiro/relatorio`

## Formato de resposta

```json
{ "success": true, "message": "Sucesso", "data": <T> }
```

Paginação:

```json
{ "success": true, "message": "Sucesso", "data": <T[]>, "pagination": { "page": 1, "pageSize": 20, "total": 100, "totalPages": 5, "hasNext": true, "hasPrevious": false } }
```

Erros:

```json
{ "success": false, "message": "Mensagem", "errors": <detalhes> | null }
```

## Endpoints

# Autenticação

Login e tokens usados por integrações.

### POST /api/v1/auth/login

Autenticar por e-mail e senha e obter JWT válido por 7 dias.

- Autenticação: pública

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `email` | `string (email)` | Sim | E-mail do usuário. |
| `password` | `string` | Sim | Senha com pelo menos 6 caracteres. |

### GET /api/v1/tokens

Listar tokens visíveis ao usuário.

- Autenticação: Bearer token

### POST /api/v1/tokens

Criar token de API.

- Autenticação: Bearer token

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome do token. |
| `tipo` | `string` | Sim | Tipo. Valores: PERMANENT, TEMPORARY. |
| `expiresInDays` | `integer` | Não | Validade em dias para token temporário. |

### GET /api/v1/tokens/:id

Consultar token e estatísticas de uso.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### PATCH /api/v1/tokens/:id

Ativar ou desativar token.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Não | Novo nome do token. |
| `ativo` | `boolean` | Não | Novo estado do token. |

### DELETE /api/v1/tokens/:id

Revogar e remover token.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

# Potências e lojas

Estrutura administrativa maçônica.

### GET /api/v1/potencias

Listar potências.

- Autenticação: Bearer token
- Tool MCP equivalente: `listar_potencias`

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |

### POST /api/v1/potencias

Criar potência.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome. |
| `sigla` | `string` | Sim | Sigla. |
| `descricao` | `string` | Não | Descrição. |
| `website` | `string (URL)` | Não | Site. |
| `ativa` | `boolean` | Não | Ativa. Padrão: true. |

### GET /api/v1/potencias/:id

Obter potência.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### PUT /api/v1/potencias/:id

Atualizar potência.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome. |
| `sigla` | `string` | Sim | Sigla. |
| `descricao` | `string` | Não | Descrição. |
| `website` | `string (URL)` | Não | Site. |
| `ativa` | `boolean` | Não | Ativa. Padrão: true. |

### DELETE /api/v1/potencias/:id

Excluir potência.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### GET /api/v1/lojas

Listar lojas.

- Autenticação: Bearer token
- Tool MCP equivalente: `listar_lojas`

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |
| `potenciaId` | `string (UUID)` | Não | Filtrar por potência. |

### POST /api/v1/lojas

Criar loja.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome. |
| `numero` | `integer` | Sim | Número. |
| `oriente` | `string` | Sim | Oriente. |
| `potenciaId` | `string (UUID)` | Sim | Potência. |
| `fundadaEm` | `string (date)` | Não | Fundação. |
| `ativa` | `boolean` | Não | Ativa. Padrão: true. |
| `endereco` | `string` | Não | Endereço. |
| `cidade` | `string` | Não | Cidade. |
| `estado` | `string` | Não | UF. |
| `cep` | `string` | Não | CEP. |
| `telefone` | `string` | Não | Telefone. |
| `email` | `string (email)` | Não | E-mail. |

### GET /api/v1/lojas/:id

Obter loja e irmãos.

- Autenticação: Bearer token
- Tool MCP equivalente: `buscar_loja`

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### PUT /api/v1/lojas/:id

Atualizar loja.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome. |
| `numero` | `integer` | Sim | Número. |
| `oriente` | `string` | Sim | Oriente. |
| `potenciaId` | `string (UUID)` | Sim | Potência. |
| `fundadaEm` | `string (date)` | Não | Fundação. |
| `ativa` | `boolean` | Não | Ativa. Padrão: true. |
| `endereco` | `string` | Não | Endereço. |
| `cidade` | `string` | Não | Cidade. |
| `estado` | `string` | Não | UF. |
| `cep` | `string` | Não | CEP. |
| `telefone` | `string` | Não | Telefone. |
| `email` | `string (email)` | Não | E-mail. |

### DELETE /api/v1/lojas/:id

Excluir loja.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

# Irmãos

Cadastro, status, histórico e extrato dos irmãos.

### GET /api/v1/irmaos

Listar irmãos.

- Autenticação: Bearer token
- Tool MCP equivalente: `listar_irmaos`

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Busca por nome, CIM, e-mail ou cargo. |
| `lojaId` | `string (UUID)` | Não | Filtrar por loja. |
| `ativo` | `string` | Não | true (padrão), false, all ou todos. Valores: true, false, all, todos. Padrão: "true". |

### POST /api/v1/irmaos/identificar

Identificar irmão por conjunção de CPF, CIM e/ou telefone.

- Autenticação: Bearer token

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `cpf` | `string (11 dígitos)` | Não | CPF. Não é devolvido na resposta. Exemplo: "12345678901". |
| `cim` | `string` | Não | Cadastro de Identificação Maçônica. Exemplo: "12345". |
| `telefone` | `string` | Não | DDD + número ou DDI + DDD + número, sem +. Aceita espaços e com/sem 9º dígito (ex.: 556788776655). Exemplo: "556788776655". |

#### Notas

- 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.

### POST /api/v1/irmaos

Cadastrar irmão.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome completo. |
| `cpf` | `string (11 dígitos)` | Não | CPF; dado sensível, não exponha ao usuário final. |
| `cim` | `string` | Não | Cadastro de Identificação Maçônica. |
| `grau` | `integer (1-33)` | Não | Grau maçônico. Padrão: 1. |
| `cargo` | `string` | Não | Cargo na loja. |
| `email` | `string (email)` | Não | E-mail. |
| `codigoPais` | `string` | Não | DDI sem +. Padrão: "55". Exemplo: "55". |
| `telefone` | `string` | Não | DDD + número ou E.164 sem +. Exemplo: "11999887766". |
| `celular` | `string` | Não | Celular alternativo. |
| `dataNascimento` | `string (date)` | Não | Data de nascimento. |
| `dataIniciacao` | `string (date)` | Não | Data de iniciação. |
| `dataElevacao` | `string (date)` | Não | Data de elevação. |
| `dataExaltacao` | `string (date)` | Não | Data de exaltação. |
| `profissao` | `string` | Não | Profissão. |
| `endereco` | `string` | Não | Endereço. |
| `cidade` | `string` | Não | Cidade. |
| `estado` | `string` | Não | UF. |
| `cep` | `string` | Não | CEP. |
| `observacoes` | `string` | Não | Observações internas. |
| `lojaId` | `string (UUID)` | Sim | Loja do irmão. |

### GET /api/v1/irmaos/:id

Obter irmão.

- Autenticação: Bearer token
- Tool MCP equivalente: `buscar_irmao`

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### PUT /api/v1/irmaos/:id

Atualizar irmão.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome completo. |
| `cpf` | `string (11 dígitos)` | Não | CPF; dado sensível, não exponha ao usuário final. |
| `cim` | `string` | Não | Cadastro de Identificação Maçônica. |
| `grau` | `integer (1-33)` | Não | Grau maçônico. Padrão: 1. |
| `cargo` | `string` | Não | Cargo na loja. |
| `email` | `string (email)` | Não | E-mail. |
| `codigoPais` | `string` | Não | DDI sem +. Padrão: "55". Exemplo: "55". |
| `telefone` | `string` | Não | DDD + número ou E.164 sem +. Exemplo: "11999887766". |
| `celular` | `string` | Não | Celular alternativo. |
| `dataNascimento` | `string (date)` | Não | Data de nascimento. |
| `dataIniciacao` | `string (date)` | Não | Data de iniciação. |
| `dataElevacao` | `string (date)` | Não | Data de elevação. |
| `dataExaltacao` | `string (date)` | Não | Data de exaltação. |
| `profissao` | `string` | Não | Profissão. |
| `endereco` | `string` | Não | Endereço. |
| `cidade` | `string` | Não | Cidade. |
| `estado` | `string` | Não | UF. |
| `cep` | `string` | Não | CEP. |
| `observacoes` | `string` | Não | Observações internas. |
| `lojaId` | `string (UUID)` | Sim | Loja do irmão. |

### DELETE /api/v1/irmaos/:id

Excluir irmão.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### GET /api/v1/irmaos/:id/extrato

Consultar extrato financeiro completo.

- Autenticação: Bearer token
- Tool MCP equivalente: `consultar_extrato_irmao`

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string (UUID)` | Sim | Loja do extrato. |

### GET /api/v1/irmaos/:id/rateios

Listar cobranças disponíveis para alocação.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string (UUID)` | Sim | Loja. |

### POST /api/v1/irmaos/:id/inativar

Inativar irmão e registrar histórico.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `motivo` | `string` | Sim | Motivo da inativação. |

### POST /api/v1/irmaos/:id/reativar

Reativar irmão.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `motivo` | `string` | Não | Motivo opcional. |

### GET /api/v1/irmaos/:id/historico

Listar histórico do irmão.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |

### POST /api/v1/irmaos/:id/historico

Registrar evento livre no histórico.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `descricao` | `string` | Sim | Descrição do evento. |

### GET /api/v1/irmaos/:id/aliases

Listar aliases.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### POST /api/v1/irmaos/:id/aliases

Criar alias.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Não | Nome alternativo; nome ou cpfCnpj é obrigatório. |
| `cpfCnpj` | `string` | Não | CPF/CNPJ alternativo; nome ou cpfCnpj é obrigatório. |
| `descricao` | `string` | Não | Descrição do vínculo. |

### DELETE /api/v1/irmaos/:id/aliases

Excluir alias informado no corpo.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `aliasId` | `string (UUID)` | Sim | Alias a excluir. |

### GET /api/v1/irmaos/:id/justificativas

Listar justificativas.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string (UUID)` | Sim | Loja. |

### POST /api/v1/irmaos/:id/justificativas

Registrar justificativa.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `dataContato` | `string (date)` | Sim | Data do contato. |
| `texto` | `string` | Sim | Texto da justificativa. |

### PUT /api/v1/irmaos/:id/justificativas/:justId

Atualizar justificativa.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |
| `justId` | `string (UUID)` | Sim | Justificativa. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `dataContato` | `string (date)` | Não | Nova data do contato. |
| `texto` | `string` | Não | Novo texto. |

### DELETE /api/v1/irmaos/:id/justificativas/:justId

Excluir justificativa.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |
| `justId` | `string (UUID)` | Sim | Justificativa. |

# Financeiro e contas

Caixa, contas bancárias, doações e relatórios.

### GET /api/v1/financeiro

Listar lançamentos e agregados.

- Autenticação: Bearer token
- Tool MCP equivalente: `consultar_financeiro`

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |
| `potenciaId` | `string (UUID)` | Não | Potência. |
| `lojaId` | `string (UUID)` | Não | Loja. |
| `irmaoId` | `string (UUID)` | Não | Irmão. |
| `tipo` | `string` | Não | Tipo. Valores: RECEITA, DESPESA, DOACAO. |
| `status` | `string` | Não | Status. Valores: PENDENTE, PAGO, CANCELADO, ATRASADO, A_RECEBER. |
| `ano` | `integer` | Não | Ano. |
| `dataInicio` | `string (YYYY-MM-DD)` | Não | Data de pagamento inicial. |
| `dataFim` | `string (YYYY-MM-DD)` | Não | Data de pagamento final. |
| `tagIds` | `string` | Não | UUIDs de tags separados por vírgula. |
| `origem` | `string` | Não | Origem. Valores: banco, especie. |

### POST /api/v1/financeiro

Criar lançamento.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `tipo` | `string` | Sim | Tipo do lançamento. Valores: RECEITA, DESPESA, DOACAO. |
| `status` | `string` | Não | Situação. Valores: PENDENTE, PAGO, CANCELADO, ATRASADO, A_RECEBER. Padrão: "PENDENTE". |
| `descricao` | `string` | Sim | Descrição original. |
| `valor` | `number` | Não | Valor positivo; opcional quando itens é informado. |
| `dataVencimento` | `string (date)` | Não | Vencimento. |
| `dataPagamento` | `string (date)` | Não | Pagamento. |
| `irmaoId` | `string (UUID)` | Não | Irmão relacionado. |
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `contaBancariaId` | `string (UUID)` | Sim | Conta bancária. |
| `observacoes` | `string` | Não | Observações. |
| `mensalidadeIrmaoId` | `string (UUID)` | Não | Rateio relacionado. |
| `tituloAlternativo` | `string` | Não | Título exibido no lugar da descrição. |
| `tagIds` | `string[]` | Não | Tags vinculadas. |
| `itens` | `array` | Não | Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto. |

### GET /api/v1/financeiro/:id

Obter lançamento.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### PUT /api/v1/financeiro/:id

Atualizar lançamento.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `tipo` | `string` | Sim | Tipo do lançamento. Valores: RECEITA, DESPESA, DOACAO. |
| `status` | `string` | Não | Situação. Valores: PENDENTE, PAGO, CANCELADO, ATRASADO, A_RECEBER. Padrão: "PENDENTE". |
| `descricao` | `string` | Sim | Descrição original. |
| `valor` | `number` | Não | Valor positivo; opcional quando itens é informado. |
| `dataVencimento` | `string (date)` | Não | Vencimento. |
| `dataPagamento` | `string (date)` | Não | Pagamento. |
| `irmaoId` | `string (UUID)` | Não | Irmão relacionado. |
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `contaBancariaId` | `string (UUID)` | Sim | Conta bancária. |
| `observacoes` | `string` | Não | Observações. |
| `mensalidadeIrmaoId` | `string (UUID)` | Não | Rateio relacionado. |
| `tituloAlternativo` | `string` | Não | Título exibido no lugar da descrição. |
| `tagIds` | `string[]` | Não | Tags vinculadas. |
| `itens` | `array` | Não | Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto. |

### DELETE /api/v1/financeiro/:id

Excluir lançamento.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### POST /api/v1/financeiro/import-ofx

Importar OFX; duplicados por FITID são ignorados.

- Autenticação: Bearer token
- Permissão: administrador
- Content-Type: `multipart/form-data`

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `file` | `File (.ofx)` | Sim | Arquivo OFX. |
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `contaBancariaId` | `string (UUID)` | Sim | Conta. |

### GET /api/v1/financeiro/relatorio

Relatório filtrado do caixa com insights.

- Autenticação: Bearer token

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `dataInicio` | `string (YYYY-MM-DD)` | Não | Início. |
| `dataFim` | `string (YYYY-MM-DD)` | Não | Fim. |
| `tagIds` | `string` | Não | UUIDs de tags separados por vírgula. |
| `irmaoId` | `string (UUID)` | Não | Irmão. |
| `tipo` | `string` | Não | Tipo. |
| `status` | `string` | Não | Status. |
| `contaBancariaId` | `string (UUID)` | Não | Conta. |
| `search` | `string` | Não | Busca. |

#### Notas

- Exige pelo menos um filtro além de lojaId.

### POST /api/v1/financeiro/:id/converter-especie

Depositar dinheiro em conta corrente.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `financeiroBancoId` | `string (UUID)` | Não | Lançamento bancário existente. |
| `contaBancariaId` | `string (UUID)` | Não | Conta para gerar o crédito. |

### DELETE /api/v1/financeiro/:id/converter-especie

Desfazer depósito.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### GET /api/v1/doacoes

Listar doações em banco e espécie.

- Autenticação: Bearer token

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |
| `lojaId` | `string (UUID)` | Não | Loja. |
| `irmaoId` | `string (UUID)` | Não | Irmão. |
| `dataInicio` | `string (YYYY-MM-DD)` | Não | Início. |
| `dataFim` | `string (YYYY-MM-DD)` | Não | Fim. |
| `tagIds` | `string` | Não | UUIDs de tags separados por vírgula. |

### GET /api/v1/contas-bancarias

Listar contas.

- Autenticação: Bearer token
- Tool MCP equivalente: `listar_contas_bancarias`

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |
| `lojaId` | `string (UUID)` | Não | Loja. |
| `ativa` | `boolean` | Não | Status. |
| `incluirEspecie` | `boolean` | Não | Incluir conta virtual de espécie. Padrão: false. |

### POST /api/v1/contas-bancarias

Criar conta.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `banco` | `string` | Sim | Banco. |
| `agencia` | `string` | Sim | Agência. |
| `conta` | `string` | Sim | Conta. |
| `tipoConta` | `string` | Não | Tipo. Valores: CORRENTE, POUPANCA, INVESTIMENTO, OUTRO. Padrão: "CORRENTE". |
| `titular` | `string` | Não | Titular. |
| `chavePix` | `string` | Não | Chave Pix. |
| `descricao` | `string` | Não | Descrição. |
| `ativa` | `boolean` | Não | Ativa. Padrão: true. |
| `lojaId` | `string (UUID)` | Sim | Loja. |

### GET /api/v1/contas-bancarias/:id

Obter conta.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### PUT /api/v1/contas-bancarias/:id

Atualizar conta.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `banco` | `string` | Sim | Banco. |
| `agencia` | `string` | Sim | Agência. |
| `conta` | `string` | Sim | Conta. |
| `tipoConta` | `string` | Não | Tipo. Valores: CORRENTE, POUPANCA, INVESTIMENTO, OUTRO. Padrão: "CORRENTE". |
| `titular` | `string` | Não | Titular. |
| `chavePix` | `string` | Não | Chave Pix. |
| `descricao` | `string` | Não | Descrição. |
| `ativa` | `boolean` | Não | Ativa. Padrão: true. |
| `lojaId` | `string (UUID)` | Sim | Loja. |

### DELETE /api/v1/contas-bancarias/:id

Excluir conta sem vínculos.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

# Cobranças, créditos e débitos

Mensalidades, rateios, créditos, débitos e abatimentos.

### GET /api/v1/mensalidades

Listar cobranças.

- Autenticação: Bearer token
- Tool MCP equivalente: `listar_mensalidades`

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |
| `lojaId` | `string (UUID)` | Não | Loja. |
| `potenciaId` | `string (UUID)` | Não | Potência. |
| `tipo` | `string` | Não | Tipo. Valores: MENSALIDADE, OUTROS. |
| `tagIds` | `string` | Não | UUIDs de tags separados por vírgula. |

### POST /api/v1/mensalidades

Criar cobrança.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome da cobrança. |
| `descricao` | `string` | Não | Descrição. |
| `tipo` | `string` | Não | Tipo da cobrança. Valores: MENSALIDADE, OUTROS. Padrão: "MENSALIDADE". |
| `dataVencimento` | `string (date)` | Sim | Vencimento. |
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `ativa` | `boolean` | Não | Cobrança ativa. Padrão: true. |
| `itens` | `array` | Sim | Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto. |
| `tagIds` | `string[]` | Não | Tags vinculadas. |

### GET /api/v1/mensalidades/:id

Obter cobrança.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### PUT /api/v1/mensalidades/:id

Atualizar cobrança.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome da cobrança. |
| `descricao` | `string` | Não | Descrição. |
| `tipo` | `string` | Não | Tipo da cobrança. Valores: MENSALIDADE, OUTROS. Padrão: "MENSALIDADE". |
| `dataVencimento` | `string (date)` | Sim | Vencimento. |
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `ativa` | `boolean` | Não | Cobrança ativa. Padrão: true. |
| `itens` | `array` | Sim | Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto. |
| `tagIds` | `string[]` | Não | Tags vinculadas. |

### DELETE /api/v1/mensalidades/:id

Excluir cobrança.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### POST /api/v1/mensalidades/:id/irmaos

Vincular irmãos à cobrança.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `irmaoIds` | `string[]` | Sim | Irmãos. |
| `contaBancariaId` | `string (UUID)` | Sim | Conta para pagamentos. |

### DELETE /api/v1/mensalidades/:id/irmaos

Desvincular irmãos.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `irmaoId` | `string (UUID)` | Sim | Irmão a desvincular. |

### PUT /api/v1/mensalidades/:id/irmaos/:irmaoId/itens

Personalizar itens do rateio.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |
| `irmaoId` | `string (UUID)` | Sim | Irmão. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `itens` | `array` | Sim | Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto. |

### DELETE /api/v1/mensalidades/:id/irmaos/:irmaoId/itens

Restaurar itens padrão.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |
| `irmaoId` | `string (UUID)` | Sim | Irmão. |

### GET /api/v1/mensalidades/relatorio

Relatório de mensalidades por período.

- Autenticação: Bearer token
- Tool MCP equivalente: `consultar_mensalidades_irmao`

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `irmaoId` | `string (UUID)` | Não | Irmão. |
| `dataInicio` | `string (YYYY-MM-DD)` | Não | Início. |
| `dataFim` | `string (YYYY-MM-DD)` | Não | Fim. |

### GET /api/v1/mensalidades/situacoes

Listar situações dos irmãos na loja.

- Autenticação: Bearer token

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string (UUID)` | Sim | Loja. |

### GET /api/v1/mensalidades/cruzamento

Consultar cruzamento de cobranças e créditos.

- Autenticação: Bearer token

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `dataInicio` | `string (YYYY-MM-DD)` | Não | Início. |
| `dataFim` | `string (YYYY-MM-DD)` | Não | Fim. |

### POST /api/v1/mensalidades/cruzamento

Vincular crédito/rateio.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `financeiroId` | `string (UUID)` | Sim | Crédito financeiro. |
| `irmaoId` | `string (UUID)` | Sim | Irmão. |
| `mensalidadeIrmaoId` | `string (UUID)` | Não | Rateio. |
| `creditoOutroFim` | `boolean` | Não | Destinar para outro fim. |
| `descricaoOutroFim` | `string` | Não | Motivo quando créditoOutroFim for true. |
| `destinoOutroFim` | `string` | Não | Destino. Valores: OUTRO, DOACAO, DEBITO. |
| `debitoId` | `string (UUID)` | Não | Débito quando destino for DEBITO. |
| `items` | `array` | Não | Modo em lote: financeiroId, irmaoId, mensalidadeIrmaoId?, creditoOutroFim? e descricaoOutroFim?. |

### PATCH /api/v1/mensalidades/cruzamento

Alterar vínculo ou destino.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `financeiroId` | `string (UUID)` | Sim | Crédito financeiro. |
| `mensalidadeIrmaoId` | `string (UUID | null)` | Não | Rateio ou null. |
| `vinculadoLoja` | `boolean` | Não | Vincular ou desvincular da loja. |
| `descricaoVinculoLoja` | `string` | Não | Descrição do vínculo com a loja. |
| `creditoOutroFim` | `boolean` | Não | Marcar ou desmarcar outro fim. |
| `descricaoOutroFim` | `string` | Não | Motivo do outro fim. |

### DELETE /api/v1/mensalidades/cruzamento

Desvincular crédito.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `financeiroId` | `string (UUID)` | Sim | Crédito a desvincular. |

### GET /api/v1/creditos

Listar créditos.

- Autenticação: Bearer token
- Tool MCP equivalente: `listar_creditos_irmao`

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |
| `lojaId` | `string (UUID)` | Não | Loja. |
| `irmaoId` | `string (UUID)` | Não | Irmão. |
| `status` | `string` | Não | Status. Valores: DISPONIVEL, PARCIAL, UTILIZADO, CANCELADO. |
| `tagIds` | `string` | Não | UUIDs de tags separados por vírgula. |

### POST /api/v1/creditos

Conceder crédito.

- Autenticação: Bearer token
- Permissão: administrador
- Tool MCP equivalente: `criar_credito_irmao`

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `irmaoId` | `string (UUID)` | Sim | Irmão. |
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `valor` | `number` | Não | Valor; omita se enviar itens. |
| `data` | `string (date)` | Sim | Data. |
| `motivo` | `string` | Sim | Motivo visível no extrato. |
| `observacoes` | `string` | Não | Observações. |
| `registrarDespesa` | `boolean` | Não | Registrar despesa. Padrão: false. |
| `contaBancariaId` | `string (UUID)` | Não | Conta da despesa. |
| `tagIds` | `string[]` | Não | Tags. |
| `itens` | `array` | Não | Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto. |

### GET /api/v1/creditos/:id

Obter crédito.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### PATCH /api/v1/creditos/:id

Atualizar ou cancelar crédito.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `valor` | `number` | Não | Novo valor. |
| `data` | `string (date)` | Não | Nova data. |
| `motivo` | `string` | Não | Novo motivo. |
| `observacoes` | `string` | Não | Observações. |
| `status` | `string` | Não | Somente cancelamento. Valores: CANCELADO. |
| `tagIds` | `string[]` | Não | Tags. |
| `itens` | `array` | Não | Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto. |

### POST /api/v1/creditos/:id/aplicacoes

Aplicar crédito em uma cobrança.

- Autenticação: Bearer token
- Permissão: administrador
- Tool MCP equivalente: `aplicar_credito_irmao`

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `mensalidadeIrmaoId` | `string (UUID)` | Sim | Rateio. |
| `valor` | `number` | Sim | Valor. |

### DELETE /api/v1/creditos/:id/aplicacoes/:aplicacaoId

Estornar aplicação.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |
| `aplicacaoId` | `string (UUID)` | Sim | Aplicação. |

### GET /api/v1/debitos

Listar débitos.

- Autenticação: Bearer token
- Tool MCP equivalente: `listar_debitos_irmao`

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |
| `lojaId` | `string (UUID)` | Não | Loja. |
| `irmaoId` | `string (UUID)` | Não | Irmão. |
| `status` | `string` | Não | Status. Valores: ABERTO, QUITADO, CANCELADO. |
| `tagIds` | `string` | Não | UUIDs de tags separados por vírgula. |

### POST /api/v1/debitos

Lançar débito.

- Autenticação: Bearer token
- Permissão: administrador
- Tool MCP equivalente: `criar_debito_irmao`

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `irmaoId` | `string (UUID)` | Sim | Irmão. |
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `valor` | `number` | Não | Valor; omita se enviar itens. |
| `data` | `string (date)` | Sim | Data. |
| `titulo` | `string` | Sim | Título visível no extrato. |
| `detalhes` | `string` | Não | Detalhes. |
| `tagIds` | `string[]` | Não | Tags. |
| `itens` | `array` | Não | Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto. |

### GET /api/v1/debitos/:id

Obter débito.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### PATCH /api/v1/debitos/:id

Atualizar ou cancelar débito.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `valor` | `number` | Não | Novo valor. |
| `data` | `string (date)` | Não | Nova data. |
| `titulo` | `string` | Não | Novo título. |
| `detalhes` | `string` | Não | Detalhes. |
| `status` | `string` | Não | Somente cancelamento. Valores: CANCELADO. |
| `tagIds` | `string[]` | Não | Tags. |
| `itens` | `array` | Não | Composição: nome, valor, descrição, tipoDesconto, desconto e motivoDesconto. |

### POST /api/v1/debitos/:id/aplicacoes

Abater débito com crédito.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `creditoId` | `string (UUID)` | Sim | Crédito. |
| `valor` | `number` | Sim | Valor. |

# Tags, relatórios e auditoria

Classificação do caixa, links de relatório e trilha de auditoria.

### GET /api/v1/tags

Listar tags.

- Autenticação: Bearer token

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string (UUID)` | Não | Filtrar por loja. |
| `q` | `string` | Não | Busca typeahead. |
| `search` | `string` | Não | Alias de q. |
| `incluirOcultas` | `boolean` | Não | Incluir ocultas. Padrão: false. |
| `comUsos` | `boolean` | Não | Incluir contagem de usos. Padrão: false. |

### POST /api/v1/tags

Criar tag.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome. |
| `lojaId` | `string (UUID)` | Sim | Loja. |

### PATCH /api/v1/tags/:id

Renomear ou ocultar tag.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Não | Novo nome. |
| `oculta` | `boolean` | Não | Ocultar ou exibir. |

### DELETE /api/v1/tags/:id

Excluir tag e vínculos.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### POST /api/v1/tags/:id/substituir

Migrar vínculos e apagar tag de origem.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `tagDestinoId` | `string (UUID)` | Sim | Tag destino. |

### GET /api/v1/relatorios-caixa

Listar links de relatório.

- Autenticação: Bearer token

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `lojaId` | `string (UUID)` | Sim | Loja. |

### POST /api/v1/relatorios-caixa

Criar link temporário de relatório.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `titulo` | `string` | Sim | Título. |
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `filtros` | `object` | Sim | Filtros do relatório. |
| `dias` | `integer (1-60)` | Sim | Validade em dias. |

### PATCH /api/v1/relatorios-caixa/:id

Renovar validade.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `dias` | `integer (1-60)` | Sim | Nova validade. |

### DELETE /api/v1/relatorios-caixa/:id

Excluir link.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### GET /api/v1/tesouraria-log

Consultar trilha de auditoria.

- Autenticação: Bearer token

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |
| `lojaId` | `string (UUID)` | Não | Loja. |
| `acao` | `string` | Não | Ação. |
| `entidade` | `string` | Não | Entidade. |
| `dataInicio` | `string (YYYY-MM-DD)` | Não | Início. |
| `dataFim` | `string (YYYY-MM-DD)` | Não | Fim. |

### GET /api/v1/chamadas

Histórico de chamadas da API e do MCP.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |
| `origem` | `string` | Não | API ou MCP. Valores: API, MCP. |
| `metodo` | `string` | Não | Método HTTP. Valores: GET, POST, PUT, PATCH, DELETE. |
| `dataInicio` | `string (YYYY-MM-DD)` | Não | Início. |
| `dataFim` | `string (YYYY-MM-DD)` | Não | Fim. |

#### Notas

- 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.

# Mensagens, e-mail e atendimento

Templates, envios, inbox e integração WhatsApp.

### GET /api/v1/contato/desafio

Gerar desafio HMAC do formulário público.

- Autenticação: pública

### POST /api/v1/contato

Enviar contato público.

- Autenticação: pública
- Content-Type: `multipart/form-data`

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `tipo` | `string` | Sim | Tipo. Valores: SUPORTE, DUVIDA, PAGAMENTOS, OUTROS, SOLICITAR_EXTRATO. |
| `cim` | `string (1-7 dígitos)` | Sim | CIM. |
| `descricao` | `string` | Não | Descrição; dispensada ao solicitar extrato. |
| `valor` | `number` | Não | Obrigatório para PAGAMENTOS. |
| `desafio` | `string` | Sim | Desafio HMAC. |
| `anexos` | `File[]` | Não | Até 5 arquivos de 10 MB. |
| `website` | `string` | Não | Honeypot; deixe vazio. |
| `company` | `string` | Não | Honeypot; deixe vazio. |

### GET /api/v1/contato

Listar inbox.

- Autenticação: Bearer token

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |
| `tipo` | `string` | Não | Tipo. |
| `status` | `string` | Não | Status. Valores: NAO_LIDA, LIDA. |

### GET /api/v1/contato/:id

Obter mensagem.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### PATCH /api/v1/contato/:id

Alterar status.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `status` | `string` | Sim | Status. Valores: NAO_LIDA, LIDA. |

### DELETE /api/v1/contato/:id

Excluir mensagem.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### POST /api/v1/atendimentos

Criar atendimento por telefone.

- Autenticação: Bearer token
- Tool MCP equivalente: `criar_atendimento`

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `telefone` | `string` | Sim | Telefone WhatsApp. |
| `texto` | `string` | Sim | Texto com 10 a 4000 caracteres. |
| `tipo` | `string` | Não | Tipo. Padrão: "OUTROS". |

### POST /api/v1/whatsapp/validar-telefone

Identificar irmão ativo por telefone.

- Autenticação: Bearer token
- Tool MCP equivalente: `identificar_irmao`

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `telefone` | `string` | Sim | Telefone sem + (DDI + DDD + número, com ou sem 9º dígito) ou JID Baileys. Ex.: 556788776655. Exemplo: "556788776655". |
| `plataforma` | `string` | Não | Origem. Valores: meta, baileys. |

### POST /api/v1/whatsapp/cobrancas/gerar-link

Gerar link temporário da tabela de cobranças.

- Autenticação: Bearer token

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `irmaoId` | `string (UUID)` | Sim | Irmão. |
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `expiracaoMinutos` | `integer` | Não | Validade em minutos. |
| `expiracaoDias` | `integer` | Não | Validade em dias. |

#### Notas

- Informe expiracaoMinutos ou expiracaoDias; expiracaoDias tem prioridade.

### GET /api/v1/whatsapp/historico

Listar histórico de envios.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |
| `irmaoId` | `string (UUID)` | Não | Irmão. |
| `templateId` | `string (UUID)` | Não | Template WhatsApp. |
| `emailTemplateId` | `string (UUID)` | Não | Template de e-mail. |
| `canal` | `string` | Não | Canal. Valores: WHATSAPP, EMAIL. |
| `sucesso` | `boolean` | Não | Filtrar sucesso. |

### GET /api/v1/whatsapp/variaveis

Listar variáveis permitidas em templates.

- Autenticação: Bearer token
- Permissão: administrador

### POST /api/v1/whatsapp/enviar

Enviar template WhatsApp.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `templateId` | `string (UUID)` | Sim | Template. |
| `irmaoId` | `string (UUID)` | Não | Irmão. |
| `irmaoIds` | `string[]` | Não | Irmãos. |
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `enviarParaTodos` | `boolean` | Não | Enviar para todos. Padrão: false. |

### GET /api/v1/whatsapp/templates

Listar templates WhatsApp.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |

### POST /api/v1/whatsapp/templates

Criar template WhatsApp.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome do template. |
| `conteudo` | `string` | Sim | Conteúdo. |
| `descricao` | `string` | Não | Descrição. |
| `ativo` | `boolean` | Não | Template ativo. Padrão: true. |

### GET /api/v1/whatsapp/templates/:id

Obter template WhatsApp.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### PUT /api/v1/whatsapp/templates/:id

Atualizar template.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome do template. |
| `conteudo` | `string` | Sim | Conteúdo. |
| `descricao` | `string` | Não | Descrição. |
| `ativo` | `boolean` | Não | Template ativo. Padrão: true. |

### DELETE /api/v1/whatsapp/templates/:id

Excluir template.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### GET /api/v1/emails/templates

Listar templates de e-mail.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `page` | `integer` | Não | Página, iniciando em 1. Padrão: 1. |
| `limit` | `integer` | Não | Itens por página (máximo 500). Padrão: 20. |
| `pageSize` | `integer` | Não | Alias de limit. Padrão: 20. |
| `search` | `string` | Não | Texto de busca. |

### POST /api/v1/emails/templates

Criar template de e-mail.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome do template. |
| `assunto` | `string` | Sim | Assunto. |
| `bodyHtml` | `string (HTML)` | Sim | Corpo HTML. |
| `headerTitle` | `string` | Não | Título do cabeçalho. |
| `ativo` | `boolean` | Não | Template ativo. Padrão: true. |

### GET /api/v1/emails/templates/:id

Obter template de e-mail.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### PUT /api/v1/emails/templates/:id

Atualizar template.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `nome` | `string` | Sim | Nome do template. |
| `assunto` | `string` | Sim | Assunto. |
| `bodyHtml` | `string (HTML)` | Sim | Corpo HTML. |
| `headerTitle` | `string` | Não | Título do cabeçalho. |
| `ativo` | `boolean` | Não | Template ativo. Padrão: true. |

### DELETE /api/v1/emails/templates/:id

Excluir template.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### POST /api/v1/emails/enviar

Enviar e-mail a um irmão.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `templateId` | `string (UUID)` | Sim | Template. |
| `irmaoId` | `string (UUID)` | Sim | Irmão. |

### POST /api/v1/emails/teste

Enviar e-mail de teste.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `templateId` | `string (UUID)` | Sim | Template. |
| `lojaId` | `string (UUID)` | Sim | Loja. |
| `irmaoId` | `string (UUID)` | Não | Irmão; informe irmão ou e-mail. |
| `email` | `string (email)` | Não | Destinatário; informe irmão ou e-mail. |

### POST /api/v1/emails/preview

Gerar prévia renderizada.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `bodyHtml` | `string (HTML)` | Sim | Corpo HTML. |
| `assunto` | `string` | Não | Assunto. Padrão: "". |
| `headerTitle` | `string` | Não | Título do cabeçalho. |
| `lojaId` | `string (UUID)` | Não | Loja. |
| `irmaoId` | `string (UUID)` | Não | Irmão. |

### POST /api/v1/emails/validar

Validar HTML com IA quando configurada.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `content` | `string (HTML)` | Sim | HTML para validar. |

# Configuração, anexos e dashboard

Configuração da loja, arquivos e estatísticas.

### GET /api/v1/configuracoes

Obter configuração.

- Autenticação: Bearer token

### PUT /api/v1/configuracoes

Atualizar padrões e contatos notificados.

- Autenticação: Bearer token
- Permissão: administrador

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `potenciaId` | `string (UUID)` | Não | Potência padrão. |
| `lojaId` | `string (UUID)` | Não | Loja padrão. |
| `contatoNotificarIrmaoIds` | `string[]` | Não | Irmãos notificados. |

### GET /api/v1/dashboard

Obter estatísticas gerais.

- Autenticação: Bearer token
- Tool MCP equivalente: `estatisticas_dashboard`

### GET /api/v1/anexos

Listar anexos de uma entidade.

- Autenticação: Bearer token

#### Parâmetros de query

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `entidade` | `string` | Sim | Tipo da entidade. |
| `entidadeId` | `string (UUID)` | Sim | Entidade. |

### POST /api/v1/anexos

Enviar anexo.

- Autenticação: Bearer token
- Permissão: administrador
- Content-Type: `multipart/form-data`

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `file` | `File` | Sim | Arquivo. |
| `entidade` | `string` | Sim | Tipo da entidade. |
| `entidadeId` | `string (UUID)` | Sim | Entidade. |

### GET /api/v1/anexos/:id/download

Baixar anexo.

- Autenticação: Bearer token

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

### DELETE /api/v1/anexos/:id

Excluir anexo.

- Autenticação: Bearer token
- Permissão: administrador

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `id` | `string (UUID)` | Sim | Identificador do recurso. |

# MCP e documentação

Descoberta e chamada das ferramentas de IA.

### POST /api/v1/mcp

Streamable HTTP (JSON-RPC) ou REST de compatibilidade ({ tool, arguments }).

- Autenticação: Bearer token

#### Corpo

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `jsonrpc` | `string` | Não | Versão JSON-RPC (clientes MCP). Exemplo: "2.0". |
| `method` | `string` | Não | Método MCP, por exemplo tools/call. |
| `tool` | `string` | Não | Nome da tool (somente modo REST). |
| `arguments` | `object` | Não | Argumentos da tool (modo REST). Padrão: {}. |

#### Notas

- Clientes MCP enviam JSON-RPC 2.0 (initialize, tools/list, tools/call).
- Body { tool, arguments } continua suportado para agentes HTTP simples.

### GET /api/v1/mcp

GET Streamable HTTP (sessões/SSE). Em modo stateless costuma responder 405.

- Autenticação: Bearer token

### DELETE /api/v1/mcp

Encerrar sessão Streamable HTTP, se o cliente usar sessão.

- Autenticação: Bearer token

### GET /api/v1/docs

Catálogo completo em envelope ApiResponse.

- Autenticação: pública

# Links públicos

Leituras por token, sem autenticação de usuário.

### GET /api/v1/extrato-publico/:token

Extrato temporário do irmão.

- Autenticação: pública

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `token` | `string` | Sim | Token público presente no link. |

### GET /api/v1/cobrancas-publico/:token

Tabela pública temporária de cobranças.

- Autenticação: pública

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `token` | `string` | Sim | Token público presente no link. |

### GET /api/v1/mensalidade-publica/:token

Última mensalidade em link permanente.

- Autenticação: pública

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `token` | `string` | Sim | Token público presente no link. |

#### Notas

- O token é criado pela tool MCP gerar_link_mensalidade; não há rota REST de criação.

### GET /api/v1/relatorios-caixa-publico/:token

Relatório do caixa ao vivo; 410 se expirado.

- Autenticação: pública

#### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `token` | `string` | Sim | Token público presente no link. |