# ZavyCRM API Gateway

> API para automação completa do ZavyCRM. Use email/senha do ZavyCRM para gerar API Keys.

## Base URL

```
https://api.zavycrm.com
```

## Autenticação

Todas as requisições devem incluir o header `X-API-Key`.

### Gerar API Key

```
POST https://api.zavycrm.com/api/v1/auth/token
Content-Type: application/json

{
  "email": "seu@email.com",
  "password": "sua_senha"
}
```

Resposta:
```json
{
  "success": true,
  "data": {
    "api_key": "sk_abc123...",
    "conta_id": "uuid-conta"
  }
}
```

### Listar Chaves

```
GET https://api.zavycrm.com/api/v1/auth/keys
X-API-Key: sk_abc123...
```

### Revogar Chave

```
POST https://api.zavycrm.com/api/v1/auth/revoke
X-API-Key: sk_abc123...
Content-Type: application/json

{
  "key_id": "uuid-da-chave"
}
```

## Endpoints

### Leads

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | /api/v1/leads | Listar leads |
| GET | /api/v1/leads/:id | Buscar lead |
| GET | /api/v1/leads/estatisticas/:contaId | Estatísticas |
| POST | /api/v1/leads | Criar lead |
| PATCH | /api/v1/leads/:id | Atualizar lead |
| PATCH | /api/v1/leads/:id/mover | Mover entre estágios |
| DELETE | /api/v1/leads/:id | Deletar lead |

#### Listar Leads

```
GET https://api.zavycrm.com/api/v1/leads?conta_id=uuid&estagio=novo&page=1&limit=50
X-API-Key: sk_abc123...
```

Parâmetros:
- `conta_id` (UUID) - Filtrar por conta
- `estagio` (string) - Filtrar por estágio
- `status` (string) - Filtrar por status
- `search` (string) - Buscar por nome/email/empresa
- `page` (number) - Página (padrão: 1)
- `limit` (number) - Itens por página (padrão: 20, máx: 100)

#### Criar Lead

```
POST https://api.zavycrm.com/api/v1/leads
X-API-Key: sk_abc123...
Content-Type: application/json

{
  "conta_id": "uuid-conta",
  "nome": "João Silva",
  "email": "joao@empresa.com",
  "telefone": "+5511999999999",
  "estagio": "novo",
  "valor": 5000,
  "origem": "website"
}
```

#### Mover Lead

```
PATCH https://api.zavycrm.com/api/v1/leads/:id/mover
X-API-Key: sk_abc123...
Content-Type: application/json

{
  "estagio": "qualificado"
}
```

#### Estatísticas

```
GET https://api.zavycrm.com/api/v1/leads/estatisticas/:contaId
X-API-Key: sk_abc123...
```

Retorna:
```json
{
  "success": true,
  "data": {
    "total": 150,
    "por_estagio": {
      "novo": 45,
      "qualificado": 30,
      "proposta": 20,
      "fechado": 55
    },
    "valor_total": 500000
  }
}
```

### Contatos

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | /api/v1/contatos | Listar contatos |
| GET | /api/v1/contatos/:id | Buscar contato |
| POST | /api/v1/contatos | Criar contato |
| POST | /api/v1/contatos/upsert | Criar ou atualizar |
| PUT | /api/v1/contatos/:id | Atualizar contato |
| DELETE | /api/v1/contatos/:id | Deletar contato |

#### Criar Contato

```
POST https://api.zavycrm.com/api/v1/contatos
X-API-Key: sk_abc123...
Content-Type: application/json

{
  "contaId": "uuid-conta",
  "nome": "Maria Santos",
  "email": "maria@empresa.com",
  "telefone": "+5511888888888",
  "empresa": "Empresa ABC",
  "cargo": "Diretora",
  "tipo": "lead"
}
```

#### Upsert Contato

```
POST https://api.zavycrm.com/api/v1/contatos/upsert
X-API-Key: sk_abc123...
Content-Type: application/json

{
  "contaId": "uuid-conta",
  "nome": "Maria Santos",
  "telefone": "+5511888888888"
}
```

> Se o telefone já existir na conta, atualiza. Senão, cria novo.

### Contas

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | /api/v1/contas | Listar contas |
| GET | /api/v1/contas/:id | Buscar conta |
| POST | /api/v1/contas | Criar conta |
| PUT | /api/v1/contas/:id | Atualizar conta |
| DELETE | /api/v1/contas/:id | Deletar conta |

### Conversas

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | /api/v1/conversas | Listar conversas |
| GET | /api/v1/conversas/:id | Buscar conversa |
| GET | /api/v1/conversas/:id/mensagens | Buscar mensagens |
| PATCH | /api/v1/conversas/:id/status | Atualizar status |
| PATCH | /api/v1/conversas/:id/atribuir | Atribuir atendente |

### Agentes IA

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | /api/v1/agentes | Listar agentes |
| GET | /api/v1/agentes/:id | Buscar agente |
| POST | /api/v1/agentes | Criar agente |
| PATCH | /api/v1/agentes/:id | Atualizar agente |
| PATCH | /api/v1/agentes/:id/toggle | Ativar/desativar |
| DELETE | /api/v1/agentes/:id | Deletar agente |

### Webhooks

| Evento | Endpoint |
|--------|----------|
| Lead criado | POST /webhook/lead-criado |
| Lead movido | POST /webhook/lead-movido |
| Conversa atribuída | POST /webhook/conversa-atribuida |
| Atendimento finalizado | POST /webhook/atendimento-finalizado |

## Respostas

### Sucesso

```json
{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}
```

### Erro

```json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Recurso não encontrado"
  }
}
```

## Códigos de Erro

| Código | HTTP | Significado |
|--------|------|-------------|
| MISSING_API_KEY | 401 | Header X-API-Key não enviado |
| INVALID_API_KEY | 403 | API Key inválida ou revogada |
| API_KEY_EXPIRED | 403 | API Key expirada |
| VALIDATION_ERROR | 400 | Dados de entrada inválidos |
| NOT_FOUND | 404 | Recurso não encontrado |
| RATE_LIMIT_EXCEEDED | 429 | Limite de requisições atingido |

## Rate Limit

- **Limite**: 7 requisições por segundo (420/min) por API Key
- **Headers**: `x-ratelimit-limit`, `x-ratelimit-remaining`, `x-ratelimit-reset`
- **Excesso**: Retorna HTTP 429 com `retry_after`

## Exemplos

### cURL

```bash
# Gerar API Key
curl -X POST https://api.zavycrm.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@empresa.com", "password": "123456"}'

# Criar lead
curl -X POST https://api.zavycrm.com/api/v1/leads \
  -H "X-API-Key: sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"conta_id": "uuid", "nome": "Maria", "telefone": "+5511999999999"}'

# Listar leads
curl https://api.zavycrm.com/api/v1/leads?estagio=novo \
  -H "X-API-Key: sk_abc123..."
```

### Python

```python
import requests

# Gerar API Key
response = requests.post(
    "https://api.zavycrm.com/api/v1/auth/token",
    json={"email": "admin@empresa.com", "password": "123456"}
)
api_key = response.json()["data"]["api_key"]

# Usar a API
headers = {"X-API-Key": api_key}
leads = requests.get("https://api.zavycrm.com/api/v1/leads", headers=headers)
print(leads.json()["data"])
```

### JavaScript

```javascript
// Gerar API Key
const res = await fetch("https://api.zavycrm.com/api/v1/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "admin@empresa.com", password: "123456" })
});
const { api_key } = (await res.json()).data;

// Usar a API
const leads = await fetch("https://api.zavycrm.com/api/v1/leads", {
  headers: { "X-API-Key": api_key }
});
```

### n8n

```json
{
  "method": "POST",
  "url": "https://api.zavycrm.com/api/v1/leads",
  "headers": {
    "X-API-Key": "sua_api_key",
    "Content-Type": "application/json"
  },
  "body": {
    "conta_id": "={{$json.conta_id}}",
    "nome": "={{$json.nome}}",
    "telefone": "={{$json.telefone}}"
  }
}
```