# 📖 Documentação da API - UtilizaAI

## Base URL

```
http://localhost/utilizaai/src/api
```

## Autenticação

Atualmente sem autenticação (APIs públicas). Em produção, implementar:
- API Keys
- OAuth 2.0
- JWT Tokens

## Endpoints de Conversão

### 1. PDF para Word

**Endpoint:** `POST /converters/pdf-to-word.php`

**Parâmetros:**
- `file` (file, obrigatório): Arquivo PDF
- `output_format` (string, opcional): `docx`, `doc`, `odt`, `rtf` (padrão: docx)
- `preserve_layout` (boolean, opcional): Preservar layout (padrão: true)

**Resposta de Sucesso (200):**
```json
{
  "success": true,
  "message": "Arquivo convertido com sucesso",
  "data": {
    "file_id": 1,
    "output_file": "word-abc123-1704067200.docx",
    "download_url": "/utilizaai/public/api/download.php?file=word-abc123-1704067200.docx",
    "conversion_time": 1.234
  }
}
```

**Resposta de Erro (400):**
```json
{
  "success": false,
  "message": "Apenas arquivos PDF são permitidos"
}
```

**Exemplo cURL:**
```bash
curl -X POST http://localhost/utilizaai/src/api/converters/pdf-to-word.php \
  -F "file=@documento.pdf" \
  -F "output_format=docx"
```

**Exemplo JavaScript:**
```javascript
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('output_format', 'docx');

fetch('/utilizaai/src/api/converters/pdf-to-word.php', {
  method: 'POST',
  body: formData
})
.then(response => response.json())
.then(data => console.log(data));
```

---

### 2. Word para PDF

**Endpoint:** `POST /converters/word-to-pdf.php`

**Parâmetros:**
- `file` (file, obrigatório): Arquivo Word (.doc, .docx)
- `quality` (string, opcional): `low`, `medium`, `high` (padrão: high)

**Resposta:**
Igual ao endpoint anterior

---

### 3. Excel para CSV

**Endpoint:** `POST /converters/excel-to-csv.php`

**Parâmetros:**
- `file` (file, obrigatório): Arquivo Excel (.xlsx, .xls)
- `sheet` (integer, opcional): Número da aba (padrão: 1)
- `delimiter` (string, opcional): `,`, `;`, `\t` (padrão: ,)

---

### 4. Conversor de Imagens

**Endpoint:** `POST /converters/image-converter.php`

**Parâmetros:**
- `file` (file, obrigatório): Arquivo de imagem
- `output_format` (string, obrigatório): `png`, `jpeg`, `webp`, `gif`, `bmp`
- `quality` (integer, opcional): 1-100 (padrão: 80)
- `width` (integer, opcional): Largura em pixels
- `height` (integer, opcional): Altura em pixels

---

## Endpoints de Ferramentas

### Gerador de QR Code

**Endpoint:** `POST /tools/qr-generator.php`

**Parâmetros:**
- `data` (string, obrigatório): Texto/URL para QR Code
- `size` (integer, opcional): Tamanho em pixels (padrão: 300)
- `format` (string, opcional): `png`, `svg`, `jpg` (padrão: png)
- `error_correction` (string, opcional): `L`, `M`, `Q`, `H` (padrão: M)

**Resposta:**
```json
{
  "success": true,
  "data": {
    "qr_code_url": "/utilizaai/public/uploads/qr-code-abc123.png",
    "size": 300,
    "format": "png"
  }
}
```

---

### Gerador de Senhas

**Endpoint:** `POST /tools/password-generator.php`

**Parâmetros:**
- `length` (integer, opcional): Comprimento (padrão: 16)
- `uppercase` (boolean, opcional): Incluir maiúsculas (padrão: true)
- `lowercase` (boolean, opcional): Incluir minúsculas (padrão: true)
- `numbers` (boolean, opcional): Incluir números (padrão: true)
- `symbols` (boolean, opcional): Incluir símbolos (padrão: true)
- `count` (integer, opcional): Número de senhas (padrão: 1)

**Resposta:**
```json
{
  "success": true,
  "data": {
    "passwords": [
      "aB#9xKl$mN@2pQ"
    ],
    "strength": "very_strong"
  }
}
```

---

## Endpoints de Download

### Baixar Arquivo Convertido

**Endpoint:** `GET /download.php?file=filename`

**Parâmetros:**
- `file` (string, obrigatório): Nome do arquivo

**Resposta:**
Faz download do arquivo se existir

---

## Códigos de Status HTTP

| Código | Significado |
|--------|------------|
| 200 | OK - Sucesso |
| 400 | Bad Request - Erro nos parâmetros |
| 403 | Forbidden - Acesso negado |
| 404 | Not Found - Recurso não encontrado |
| 405 | Method Not Allowed - Método HTTP não permitido |
| 413 | Payload Too Large - Arquivo muito grande |
| 500 | Internal Server Error - Erro do servidor |

---

## Rate Limiting

**Limite:** 100 requisições por hora por IP

**Headers de resposta:**
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1704072000
```

---

## Validações

### Tamanho de Arquivo
- **Máximo:** 50 MB
- **Erro:** 413 Payload Too Large

### Tipos de Arquivo Permitidos
```php
['pdf', 'docx', 'doc', 'xlsx', 'csv', 
 'jpg', 'jpeg', 'png', 'gif', 'webp']
```

### Validação MIME Type
Todos os uploads validam MIME type além da extensão

---

## CORS (Cross-Origin Resource Sharing)

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type
```

---

## Exemplo Completo de Integração

```html
<!DOCTYPE html>
<html>
<head>
    <title>Integração UtilizaAI</title>
</head>
<body>
    <input type="file" id="file" accept=".pdf">
    <button onclick="convertFile()">Converter</button>

    <script>
    async function convertFile() {
        const file = document.getElementById('file').files[0];
        const formData = new FormData();
        formData.append('file', file);
        formData.append('output_format', 'docx');

        try {
            const response = await fetch(
                'http://localhost/utilizaai/src/api/converters/pdf-to-word.php',
                {
                    method: 'POST',
                    body: formData
                }
            );

            const result = await response.json();

            if (result.success) {
                console.log('Download URL:', result.data.download_url);
                // Fazer download
                window.location.href = result.data.download_url;
            } else {
                console.error('Erro:', result.message);
            }
        } catch (error) {
            console.error('Erro na requisição:', error);
        }
    }
    </script>
</body>
</html>
```

---

## Tratamento de Erros

Sempre verificar `success` field:

```javascript
fetch(url)
  .then(r => r.json())
  .then(data => {
    if (!data.success) {
      throw new Error(data.message);
    }
    // Processar sucesso
  })
  .catch(error => {
    console.error('Erro:', error.message);
  });
```

---

## Suporte

- **Email:** api-support@utilizaai.com
- **Documentação:** https://docs.utilizaai.com
- **GitHub Issues:** https://github.com/utilizaai/issues