# API de Estabelecimentos - Documentação

## Endpoint: GET /api/establishments

### Descrição
Lista todos os estabelecimentos com suporte a paginação, pesquisa e filtros.

### Parâmetros de Query (todos opcionais)

| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|--------|-----------|
| `page` | number | 1 | Número da página (inicia em 1) |
| `limit` | number | 10 | Quantidade de itens por página |
| `search` | string | '' | Busca por nome, endereço ou telefone |
| `type` | string | null | Filtrar por tipo (ex: "Loja", "Restaurante") |
| `is_active` | boolean | null | Filtrar por status ativo (true/false) |

### Exemplos de Uso

#### 1. Listar todos os estabelecimentos (com paginação padrão)
```
GET /api/establishments
```
Retorna página 1 com 10 estabelecimentos por página.

#### 2. Listar com paginação personalizada
```
GET /api/establishments?page=2&limit=20
```
Retorna página 2 com 20 estabelecimentos por página.

#### 3. Pesquisar estabelecimentos
```
GET /api/establishments?search=Restaurante
```
Busca estabelecimentos cujo nome, endereço ou telefone contenham "Restaurante".

#### 4. Filtrar por tipo
```
GET /api/establishments?type=Loja
```
Retorna apenas estabelecimentos do tipo "Loja".

#### 5. Filtrar apenas ativos
```
GET /api/establishments?is_active=true
```
Retorna apenas estabelecimentos ativos.

#### 6. Combinação de filtros
```
GET /api/establishments?page=1&limit=15&search=Café&type=Restaurante&is_active=true
```
Combina paginação, pesquisa e filtros.

### Resposta de Sucesso

```json
{
    "success": true,
    "data": [
        {
            "id": 104,
            "name": "Academia Fitness",
            "type": "Loja",
            "image": "assets/images/loja2.jpeg",
            "imageUrl": "assets/images/loja2.jpeg",
            "address": "Avenida do Esporte, 567 - Maputo",
            "phone": "+258842345678",
            "email": "matriculas@fitness.co.mz",
            "qrCode": "MAKTUBIA_SHOP_010",
            "color": "#F44336",
            "isActive": true,
            "campaign": {
                "id": "CAMP_MAKTUBIA_SHOP_010_1761917303240_6xmsjf",
                "type": "vip_treatment",
                "description": "Assinatura anual = tratamento VIP",
                "conversionRate": 0.2,
                "minSpend": 1200,
                "bonusMultiplier": 1,
                "requiredVisits": null,
                "reward": null,
                "validUntil": "2024-12-31T00:00:00",
                "isActive": true
            },
            "campaigns": [
                {
                    "id": "CAMP_MAKTUBIA_SHOP_010_1761917303240_6xmsjf",
                    "type": "vip_treatment",
                    "description": "Assinatura anual = tratamento VIP",
                    "conversionRate": 0.2,
                    "minSpend": 1200,
                    "bonusMultiplier": 1,
                    "requiredVisits": null,
                    "reward": null,
                    "validUntil": "2024-12-31T00:00:00",
                    "isActive": true
                }
            ]
        }
    ],
    "pagination": {
        "total": 25,
        "page": 1,
        "limit": 10,
        "totalPages": 3,
        "hasNextPage": true,
        "hasPrevPage": false
    },
    "meta": {
        "showing": "1-10 de 25",
        "currentPage": 1,
        "perPage": 10
    }
}
```

### Estrutura da Resposta

#### `data` (array)
Array de estabelecimentos formatados para o app Flutter.

#### `pagination` (object)
Informações sobre paginação:
- `total`: Total de estabelecimentos encontrados
- `page`: Página atual
- `limit`: Itens por página
- `totalPages`: Total de páginas
- `hasNextPage`: Boolean indicando se há próxima página
- `hasPrevPage`: Boolean indicando se há página anterior

#### `meta` (object)
Metadados adicionais:
- `showing`: String descrevendo o intervalo exibido (ex: "1-10 de 25")
- `currentPage`: Página atual
- `perPage`: Itens por página

### Códigos de Status

| Código | Descrição |
|--------|-----------|
| 200 | Sucesso |
| 401 | Não autorizado (token inválido ou ausente) |
| 500 | Erro interno do servidor |

### Observações

1. **Paginação**: Sem parâmetros, retorna página 1 com 10 itens.
2. **Pesquisa**: Busca case-insensitive em nome, endereço e telefone.
3. **Filtros**: Podem ser combinados para refinar a busca.
4. **Campanhas**: Cada estabelecimento inclui suas campanhas ativas.
5. **QR Code**: Gerado automaticamente se não fornecido na criação.

### Exemplo de Integração (JavaScript/Flutter)

```javascript
// Buscar estabelecimentos com paginação
async function getEstablishments(page = 1, limit = 10, search = '') {
    const params = new URLSearchParams({
        page: page.toString(),
        limit: limit.toString(),
        search: search
    });
    
    const response = await fetch(`/api/establishments?${params}`, {
        headers: {
            'Authorization': `Bearer ${token}`
        }
    });
    
    const result = await response.json();
    
    if (result.success) {
        console.log(`Página ${result.pagination.page} de ${result.pagination.totalPages}`);
        console.log(`Mostrando ${result.meta.showing}`);
        console.log(`Total: ${result.pagination.total} estabelecimentos`);
        
        // Navegar para próxima página
        if (result.pagination.hasNextPage) {
            // Carregar próxima página
        }
        
        return result.data;
    }
}
```