# SimpleCRM API

> SimpleCRM é uma plataforma CRM gratuita e aberta com API REST para gerenciar contatos, empresas, negócios (funil de vendas), tarefas, produtos, faturas, cotações, atividades, relatórios e webhooks.
> SimpleCRM is a free, open CRM platform with a REST API for managing contacts, companies, deals (sales pipeline), tasks, products, invoices, quotes, activities, reports, and webhooks.

- **URL Base / Base URL**: `https://crm.acessocomercial.com/api`
- **Autenticação / Authentication**: API Key via header `X-API-Key` (ou `Authorization: Bearer <key>`)
- **Rate limit**: 60 requisições/minuto por API key
- **Content-Type**: `application/json`
- **IDs**: Strings hexadecimais de 24 caracteres (MongoDB ObjectId)
- **Datas / Dates**: Formato ISO 8601 (`2026-05-07T10:00:00Z`)
- **Erros / Errors**: `{ "error": "descrição" }`
- **Paginação / Pagination**: `?page=1&limit=20` (máx 100)

---

## Autenticação / Authentication

Todas as requisições à API requerem autenticação via API Key.
All API requests require authentication via API Key.

**Opção 1 — Header customizado / Custom header:**
```
X-API-Key: crm_sk_sua_chave_aqui
```

**Opção 2 — Bearer token:**
```
Authorization: Bearer crm_sk_sua_chave_aqui
```

Crie API keys em: `https://crm.acessocomercial.com/dashboard/settings`

**Segurança:** Rotas internas (notificações, fidelidade, gerenciamento de webhooks e API keys) são bloqueadas para acesso via API key. Use a aplicação web para essas funcionalidades.

---

## Relações entre Entidades / Entity Relationships

- Um **Contato** pode pertencer a uma **Empresa** (via `companyId`)
- Um **Negócio** pode referenciar uma **Empresa** (`companyId`) e múltiplos **Contatos** (`contactIds`)
- Uma **Tarefa** pode referenciar um **Contato** (`contactId`) e/ou um **Negócio** (`dealId`)
- Uma **Fatura** referencia um **Contato** (`contactId`) e contém itens de **Produto** (`items[].productId`)
- Uma **Cotação** referencia um **Contato** (`contactId`) e contém itens de **Produto**; pode ser convertida em **Fatura**
- Uma **Atividade** referencia qualquer entidade via `relatedTo` + `relatedType` (contact, company ou deal)
- **Webhooks** disparam eventos quando entidades são criadas, atualizadas ou removidas

---

## Valores Permitidos (Enums) / Allowed Values

- **Status do negócio / Deal status**: `open`, `won`, `lost`
- **Estágios do funil / Deal stages**: `novo`, `qualificacao`, `proposta`, `negociacao`, `fechado` (personalizável)
- **Prioridade de tarefa / Task priority**: `low`, `medium`, `high`
- **Status da fatura / Invoice status**: `pending`, `paid`, `overdue`, `cancelled`
- **Status da cotação / Quote status**: `draft`, `sent`, `accepted`, `rejected`, `converted`
- **Tipo de atividade / Activity type**: `call`, `email`, `meeting`, `note`, `task`
- **Tipo de entidade / Activity relatedType**: `contact`, `company`, `deal`
- **Porte da empresa / Company size**: `1-10`, `11-50`, `51-200`, `201-1000`, `1000+`

---

## Contatos

CRUD completo para gerenciamento de contatos e leads.

### GET `/api/contacts`

**Listar Contatos** _(requer autenticação / requires authentication)_

Retorna a lista paginada de contatos do usuário. Suporta busca por nome ou email.

**Query Parameters:**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `page` | integer | Não / No | Número da página (padrão: 1) |
| `limit` | integer | Não / No | Itens por página (padrão: 20, máx: 100) |
| `search` | string | Não / No | Busca por nome ou email |

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Maria Santos",
      "email": "maria@empresa.com",
      "phone": "+5511987654321",
      "position": "Diretora Comercial",
      "companyId": "507f1f77bcf86cd799439022",
      "tags": ["vip", "recorrente"],
      "notes": "Prefere contato por WhatsApp",
      "createdAt": "2026-03-10T14:20:00Z",
      "updatedAt": "2026-04-01T09:15:00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 20
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

### POST `/api/contacts`

**Criar Contato** _(requer autenticação / requires authentication)_

Cria um novo contato vinculado ao usuário autenticado.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `name` | string | Sim / Yes | Nome completo do contato |
| `email` | string | Não / No | Email do contato |
| `phone` | string | Não / No | Telefone com DDD (+5511...) |
| `position` | string | Não / No | Cargo ou função |
| `notes` | string | Não / No | Observações livres |

**Exemplo de Requisição / Request Example:**

```json
{
  "name": "Maria Santos",
  "email": "maria@empresa.com",
  "phone": "+5511987654321",
  "position": "Diretora Comercial",
  "notes": "Prefere contato por WhatsApp"
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439011",
  "name": "Maria Santos",
  "email": "maria@empresa.com",
  "phone": "+5511987654321",
  "position": "Diretora Comercial",
  "notes": "Prefere contato por WhatsApp",
  "tags": [],
  "createdAt": "2026-05-07T10:00:00Z",
  "updatedAt": "2026-05-07T10:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `201`: Criado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado

---

### GET `/api/contacts/:id`

**Buscar Contato por ID** _(requer autenticação / requires authentication)_

Retorna os dados completos de um contato específico. Apenas o proprietário pode visualizar.

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439011",
  "name": "Maria Santos",
  "email": "maria@empresa.com",
  "phone": "+5511987654321",
  "position": "Diretora Comercial",
  "companyId": "507f1f77bcf86cd799439022",
  "tags": ["vip"],
  "notes": "Prefere contato por WhatsApp",
  "createdAt": "2026-03-10T14:20:00Z",
  "updatedAt": "2026-04-01T09:15:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Registro encontrado
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### PUT `/api/contacts/:id`

**Atualizar Contato** _(requer autenticação / requires authentication)_

Atualiza os dados de um contato existente. Envie apenas os campos que deseja modificar.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `name` | string | Não / No | Nome completo |
| `email` | string | Não / No | Email |
| `phone` | string | Não / No | Telefone |
| `position` | string | Não / No | Cargo |
| `notes` | string | Não / No | Observações |

**Exemplo de Requisição / Request Example:**

```json
{
  "position": "CEO",
  "notes": "Promovida em maio/2026"
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439011",
  "name": "Maria Santos",
  "email": "maria@empresa.com",
  "position": "CEO",
  "notes": "Promovida em maio/2026",
  "updatedAt": "2026-05-07T15:30:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Atualizado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### DELETE `/api/contacts/:id`

**Remover Contato** _(requer autenticação / requires authentication)_

Remove permanentemente um contato. Esta ação não pode ser desfeita.

**Exemplo de Resposta / Response Example:**

```json
{
  "message": "Contact deleted successfully"
}
```

**Códigos de Status / Status Codes:**

- `200`: Removido com sucesso
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

## Empresas

Gerenciamento de empresas e organizações vinculadas aos contatos.

### GET `/api/companies`

**Listar Empresas** _(requer autenticação / requires authentication)_

Retorna a lista paginada de empresas do usuário autenticado.

**Query Parameters:**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `page` | integer | Não / No | Número da página (padrão: 1) |
| `limit` | integer | Não / No | Itens por página (padrão: 20, máx: 100) |
| `search` | string | Não / No | Busca por nome ou email |

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439022",
      "name": "Tech Solutions Ltda",
      "cnpj": "12.345.678/0001-90",
      "website": "https://techsolutions.com.br",
      "industry": "Tecnologia",
      "size": "11-50",
      "notes": "Cliente desde 2024",
      "createdAt": "2026-02-20T08:00:00Z"
    }
  ],
  "total": 38,
  "page": 1,
  "limit": 20
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

### POST `/api/companies`

**Criar Empresa** _(requer autenticação / requires authentication)_

Cadastra uma nova empresa.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `name` | string | Sim / Yes | Razão social ou nome fantasia |
| `cnpj` | string | Não / No | CNPJ (formato livre, validado automaticamente) |
| `website` | string | Não / No | URL do site |
| `industry` | string | Não / No | Setor de atuação |
| `size` | string | Não / No | Porte: 1-10, 11-50, 51-200, 201-1000, 1000+ |
| `notes` | string | Não / No | Observações |

**Exemplo de Requisição / Request Example:**

```json
{
  "name": "Tech Solutions Ltda",
  "cnpj": "12.345.678/0001-90",
  "website": "https://techsolutions.com.br",
  "industry": "Tecnologia",
  "size": "11-50"
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439022",
  "name": "Tech Solutions Ltda",
  "cnpj": "12.345.678/0001-90",
  "website": "https://techsolutions.com.br",
  "industry": "Tecnologia",
  "size": "11-50",
  "createdAt": "2026-05-07T10:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `201`: Criado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado

---

### GET `/api/companies/:id`

**Buscar Empresa por ID** _(requer autenticação / requires authentication)_

Retorna os dados completos de uma empresa específica.

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439022",
  "name": "Tech Solutions Ltda",
  "cnpj": "12.345.678/0001-90",
  "website": "https://techsolutions.com.br",
  "industry": "Tecnologia",
  "size": "11-50",
  "notes": "Cliente desde 2024",
  "createdAt": "2026-02-20T08:00:00Z",
  "updatedAt": "2026-04-15T11:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Registro encontrado
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### PUT `/api/companies/:id`

**Atualizar Empresa** _(requer autenticação / requires authentication)_

Atualiza os dados de uma empresa existente. Envie apenas os campos que deseja modificar.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `name` | string | Não / No | Razão social |
| `cnpj` | string | Não / No | CNPJ |
| `website` | string | Não / No | URL do site |
| `industry` | string | Não / No | Setor de atuação |
| `size` | string | Não / No | Porte |
| `notes` | string | Não / No | Observações |

**Exemplo de Requisição / Request Example:**

```json
{
  "industry": "SaaS",
  "notes": "Renovação contrato Q3/2026"
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439022",
  "name": "Tech Solutions Ltda",
  "industry": "SaaS",
  "notes": "Renovação contrato Q3/2026",
  "updatedAt": "2026-05-07T15:30:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Atualizado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### DELETE `/api/companies/:id`

**Remover Empresa** _(requer autenticação / requires authentication)_

Remove permanentemente uma empresa. Contatos vinculados não são excluídos.

**Exemplo de Resposta / Response Example:**

```json
{
  "message": "Empresa excluída com sucesso"
}
```

**Códigos de Status / Status Codes:**

- `200`: Removido com sucesso
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

## Negócios

Funil de vendas: criação, atualização de estágio e acompanhamento de negócios.

### GET `/api/deals`

**Listar Negócios** _(requer autenticação / requires authentication)_

Retorna todos os negócios do funil de vendas do usuário, com paginação e filtros.

**Query Parameters:**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `page` | integer | Não / No | Número da página |
| `limit` | integer | Não / No | Itens por página (máx: 100) |
| `status` | string | Não / No | Filtrar por status: open, won, lost |
| `stage` | string | Não / No | Filtrar por estágio do funil |

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439033",
      "title": "Implantação ERP - Tech Solutions",
      "value": 45000.00,
      "currency": "BRL",
      "stage": "negociacao",
      "status": "open",
      "probability": 70,
      "companyId": "507f1f77bcf86cd799439022",
      "contactIds": ["507f1f77bcf86cd799439011"],
      "expectedCloseDate": "2026-06-15T00:00:00Z",
      "createdAt": "2026-04-01T10:00:00Z"
    }
  ],
  "total": 24,
  "page": 1,
  "limit": 20
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

### POST `/api/deals`

**Criar Negócio** _(requer autenticação / requires authentication)_

Cria um novo negócio no funil de vendas. O status inicial é sempre "open".

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `title` | string | Sim / Yes | Título do negócio |
| `value` | number | Sim / Yes | Valor estimado em BRL |
| `stage` | string | Não / No | Estágio inicial do funil |
| `probability` | integer | Não / No | Probabilidade de fechamento (0-100) |
| `companyId` | string | Não / No | ID da empresa relacionada |
| `contactIds` | string[] | Não / No | IDs dos contatos envolvidos |
| `expectedCloseDate` | string | Não / No | Data prevista de fechamento (ISO 8601) |

**Exemplo de Requisição / Request Example:**

```json
{
  "title": "Implantação ERP - Tech Solutions",
  "value": 45000.00,
  "stage": "novo",
  "probability": 30,
  "companyId": "507f1f77bcf86cd799439022",
  "contactIds": ["507f1f77bcf86cd799439011"],
  "expectedCloseDate": "2026-06-15T00:00:00Z"
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439033",
  "title": "Implantação ERP - Tech Solutions",
  "value": 45000.00,
  "currency": "BRL",
  "stage": "novo",
  "status": "open",
  "probability": 30,
  "createdAt": "2026-05-07T10:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `201`: Criado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado

---

### GET `/api/deals/:id`

**Buscar Negócio por ID** _(requer autenticação / requires authentication)_

Retorna os dados completos de um negócio específico.

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439033",
  "title": "Implantação ERP - Tech Solutions",
  "value": 45000.00,
  "currency": "BRL",
  "stage": "negociacao",
  "status": "open",
  "probability": 70,
  "companyId": "507f1f77bcf86cd799439022",
  "contactIds": ["507f1f77bcf86cd799439011"],
  "expectedCloseDate": "2026-06-15T00:00:00Z",
  "createdAt": "2026-04-01T10:00:00Z",
  "updatedAt": "2026-05-05T14:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Registro encontrado
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### PUT `/api/deals/:id`

**Atualizar Negócio** _(requer autenticação / requires authentication)_

Atualiza dados de um negócio. Use para mover entre estágios do funil ou alterar valores.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `title` | string | Não / No | Título |
| `value` | number | Não / No | Valor em BRL |
| `stage` | string | Não / No | Estágio do funil |
| `status` | string | Não / No | Status: open, won, lost |
| `probability` | integer | Não / No | Probabilidade (0-100) |
| `expectedCloseDate` | string | Não / No | Data prevista (ISO 8601) |

**Exemplo de Requisição / Request Example:**

```json
{
  "stage": "fechado",
  "status": "won",
  "probability": 100
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439033",
  "title": "Implantação ERP - Tech Solutions",
  "value": 45000.00,
  "stage": "fechado",
  "status": "won",
  "probability": 100,
  "updatedAt": "2026-05-07T15:30:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Atualizado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### DELETE `/api/deals/:id`

**Remover Negócio** _(requer autenticação / requires authentication)_

Remove permanentemente um negócio do funil de vendas.

**Exemplo de Resposta / Response Example:**

```json
{
  "message": "Negócio excluído com sucesso"
}
```

**Códigos de Status / Status Codes:**

- `200`: Removido com sucesso
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### GET `/api/deals/pipeline-stats`

**Estatísticas do Funil de Vendas** _(requer autenticação / requires authentication)_

Retorna estatísticas agregadas do funil de vendas: total por estágio, valores e contagens.

**Exemplo de Resposta / Response Example:**

```json
{
  "totalDeals": 24,
  "totalValue": 380000.00,
  "byStage": {
    "novo": { "count": 8, "value": 120000 },
    "negociacao": { "count": 10, "value": 180000 },
    "fechado": { "count": 6, "value": 80000 }
  },
  "wonDeals": 15,
  "lostDeals": 5,
  "conversionRate": 75.0
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

## Tarefas

Gerenciamento de tarefas, follow-ups e calendário de atividades.

### GET `/api/tasks`

**Listar Tarefas** _(requer autenticação / requires authentication)_

Retorna a lista paginada de tarefas do usuário.

**Query Parameters:**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `page` | integer | Não / No | Número da página |
| `limit` | integer | Não / No | Itens por página (máx: 100) |

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439044",
      "title": "Follow-up proposta Tech Solutions",
      "description": "Ligar para Maria sobre desconto",
      "dueDate": "2026-05-10T14:00:00Z",
      "priority": "high",
      "completed": false,
      "contactId": "507f1f77bcf86cd799439011",
      "dealId": "507f1f77bcf86cd799439033",
      "createdAt": "2026-05-07T10:00:00Z"
    }
  ],
  "total": 18,
  "page": 1,
  "limit": 20
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

### POST `/api/tasks`

**Criar Tarefa** _(requer autenticação / requires authentication)_

Cria uma nova tarefa vinculada opcionalmente a um contato ou negócio.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `title` | string | Sim / Yes | Título da tarefa |
| `description` | string | Não / No | Descrição detalhada |
| `dueDate` | string | Não / No | Data de vencimento (ISO 8601) |
| `priority` | string | Não / No | Prioridade: low, medium, high |
| `contactId` | string | Não / No | ID do contato relacionado |
| `dealId` | string | Não / No | ID do negócio relacionado |

**Exemplo de Requisição / Request Example:**

```json
{
  "title": "Follow-up proposta Tech Solutions",
  "description": "Ligar para Maria sobre desconto",
  "dueDate": "2026-05-10T14:00:00Z",
  "priority": "high",
  "contactId": "507f1f77bcf86cd799439011",
  "dealId": "507f1f77bcf86cd799439033"
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439044",
  "title": "Follow-up proposta Tech Solutions",
  "description": "Ligar para Maria sobre desconto",
  "dueDate": "2026-05-10T14:00:00Z",
  "priority": "high",
  "completed": false,
  "createdAt": "2026-05-07T10:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `201`: Criado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado

---

### GET `/api/tasks/:id`

**Buscar Tarefa por ID** _(requer autenticação / requires authentication)_

Retorna os dados completos de uma tarefa específica.

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439044",
  "title": "Follow-up proposta Tech Solutions",
  "description": "Ligar para Maria sobre desconto",
  "dueDate": "2026-05-10T14:00:00Z",
  "priority": "high",
  "completed": false,
  "contactId": "507f1f77bcf86cd799439011",
  "dealId": "507f1f77bcf86cd799439033",
  "createdAt": "2026-05-07T10:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Registro encontrado
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### PUT `/api/tasks/:id`

**Atualizar Tarefa** _(requer autenticação / requires authentication)_

Atualiza os dados de uma tarefa existente.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `title` | string | Não / No | Título |
| `description` | string | Não / No | Descrição |
| `dueDate` | string | Não / No | Data de vencimento (ISO 8601) |
| `priority` | string | Não / No | Prioridade: low, medium, high |

**Exemplo de Requisição / Request Example:**

```json
{
  "dueDate": "2026-05-12T14:00:00Z",
  "priority": "medium"
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439044",
  "title": "Follow-up proposta Tech Solutions",
  "dueDate": "2026-05-12T14:00:00Z",
  "priority": "medium",
  "updatedAt": "2026-05-07T15:30:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Atualizado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### DELETE `/api/tasks/:id`

**Remover Tarefa** _(requer autenticação / requires authentication)_

Remove permanentemente uma tarefa.

**Exemplo de Resposta / Response Example:**

```json
{
  "message": "Tarefa excluída com sucesso"
}
```

**Códigos de Status / Status Codes:**

- `200`: Removido com sucesso
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### POST `/api/tasks/:id/complete`

**Marcar como Concluída** _(requer autenticação / requires authentication)_

Marca uma tarefa como concluída. Define o campo completed como true e registra a data.

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439044",
  "title": "Follow-up proposta Tech Solutions",
  "completed": true,
  "completedAt": "2026-05-07T16:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Tarefa concluída
- `403`: Sem permissão
- `404`: Não encontrada

---

### GET `/api/tasks/overdue`

**Tarefas Atrasadas** _(requer autenticação / requires authentication)_

Retorna todas as tarefas cujo prazo já venceu e ainda não foram concluídas.

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439044",
      "title": "Enviar contrato assinado",
      "dueDate": "2026-05-01T00:00:00Z",
      "priority": "high",
      "completed": false
    }
  ],
  "total": 3
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

### GET `/api/tasks/upcoming`

**Tarefas Próximas** _(requer autenticação / requires authentication)_

Retorna as tarefas com vencimento nos próximos 7 dias.

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439045",
      "title": "Reunião cliente XYZ",
      "dueDate": "2026-05-09T10:00:00Z",
      "priority": "high",
      "completed": false
    }
  ],
  "total": 5
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

### GET `/api/tasks/calendar`

**Calendário de Tarefas** _(requer autenticação / requires authentication)_

Retorna tarefas agrupadas por data para exibição em calendário.

**Query Parameters:**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `start` | string | Não / No | Data início do período (ISO 8601) |
| `end` | string | Não / No | Data fim do período (ISO 8601) |

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439044",
      "title": "Follow-up Tech Solutions",
      "dueDate": "2026-05-10T14:00:00Z",
      "priority": "high",
      "completed": false
    }
  ]
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

## Produtos

Catálogo de produtos e serviços com preços e categorias.

### GET `/api/products`

**Listar Produtos** _(requer autenticação / requires authentication)_

Retorna a lista paginada de produtos do catálogo.

**Query Parameters:**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `page` | integer | Não / No | Número da página (padrão: 1) |
| `limit` | integer | Não / No | Itens por página (padrão: 20, máx: 100) |
| `search` | string | Não / No | Busca por nome ou email |

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439055",
      "name": "Consultoria Mensal",
      "description": "40h de consultoria comercial",
      "price": 3500.00,
      "sku": "CONS-001",
      "category": "Serviços",
      "active": true,
      "createdAt": "2026-03-01T10:00:00Z"
    }
  ],
  "total": 15,
  "page": 1,
  "limit": 20
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

### POST `/api/products`

**Criar Produto** _(requer autenticação / requires authentication)_

Adiciona um novo produto ao catálogo. Integrado com cotações e faturas.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `name` | string | Sim / Yes | Nome do produto |
| `description` | string | Não / No | Descrição |
| `price` | number | Sim / Yes | Preço unitário em BRL |
| `sku` | string | Não / No | Código SKU |
| `category` | string | Não / No | Categoria |

**Exemplo de Requisição / Request Example:**

```json
{
  "name": "Consultoria Mensal",
  "description": "40h de consultoria comercial",
  "price": 3500.00,
  "sku": "CONS-001",
  "category": "Serviços"
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439055",
  "name": "Consultoria Mensal",
  "description": "40h de consultoria comercial",
  "price": 3500.00,
  "sku": "CONS-001",
  "category": "Serviços",
  "active": true,
  "createdAt": "2026-05-07T10:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `201`: Criado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado

---

### GET `/api/products/:id`

**Buscar Produto por ID** _(requer autenticação / requires authentication)_

Retorna os dados completos de um produto específico.

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439055",
  "name": "Consultoria Mensal",
  "description": "40h de consultoria comercial",
  "price": 3500.00,
  "sku": "CONS-001",
  "category": "Serviços",
  "active": true,
  "createdAt": "2026-03-01T10:00:00Z",
  "updatedAt": "2026-04-15T11:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Registro encontrado
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### PUT `/api/products/:id`

**Atualizar Produto** _(requer autenticação / requires authentication)_

Atualiza os dados de um produto existente.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `name` | string | Não / No | Nome |
| `description` | string | Não / No | Descrição |
| `price` | number | Não / No | Preço unitário em BRL |
| `sku` | string | Não / No | Código SKU |
| `category` | string | Não / No | Categoria |
| `active` | boolean | Não / No | Se o produto está ativo |

**Exemplo de Requisição / Request Example:**

```json
{
  "price": 4000.00,
  "description": "50h de consultoria comercial"
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439055",
  "name": "Consultoria Mensal",
  "price": 4000.00,
  "description": "50h de consultoria comercial",
  "updatedAt": "2026-05-07T15:30:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Atualizado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### DELETE `/api/products/:id`

**Remover Produto** _(requer autenticação / requires authentication)_

Remove permanentemente um produto do catálogo. Faturas e cotações existentes não são afetadas.

**Exemplo de Resposta / Response Example:**

```json
{
  "message": "Produto excluído com sucesso"
}
```

**Códigos de Status / Status Codes:**

- `200`: Removido com sucesso
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

## Faturas

Criação, acompanhamento e gestão de faturas e pagamentos.

### GET `/api/invoices`

**Listar Faturas** _(requer autenticação / requires authentication)_

Retorna a lista paginada de faturas do usuário.

**Query Parameters:**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `page` | integer | Não / No | Número da página |
| `limit` | integer | Não / No | Itens por página (máx: 100) |
| `status` | string | Não / No | Filtrar por status: pending, paid, overdue, cancelled |

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439066",
      "number": "INV-2026-0042",
      "contactId": "507f1f77bcf86cd799439011",
      "total": 7000.00,
      "status": "pending",
      "dueDate": "2026-06-07T00:00:00Z",
      "createdAt": "2026-05-07T10:00:00Z"
    }
  ],
  "total": 28,
  "page": 1,
  "limit": 20
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

### POST `/api/invoices`

**Criar Fatura** _(requer autenticação / requires authentication)_

Gera uma nova fatura com itens do catálogo de produtos.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `contactId` | string | Sim / Yes | ID do contato (cliente) |
| `items` | object[] | Sim / Yes | Lista de itens: { productId, quantity, unitPrice } |
| `dueDate` | string | Sim / Yes | Data de vencimento (ISO 8601) |
| `notes` | string | Não / No | Observações |

**Exemplo de Requisição / Request Example:**

```json
{
  "contactId": "507f1f77bcf86cd799439011",
  "items": [
    {
      "productId": "507f1f77bcf86cd799439055",
      "quantity": 2,
      "unitPrice": 3500.00
    }
  ],
  "dueDate": "2026-06-07T00:00:00Z",
  "notes": "Pagamento via PIX"
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439066",
  "number": "INV-2026-0042",
  "contactId": "507f1f77bcf86cd799439011",
  "items": [
    {
      "productId": "507f1f77bcf86cd799439055",
      "name": "Consultoria Mensal",
      "quantity": 2,
      "unitPrice": 3500.00,
      "total": 7000.00
    }
  ],
  "subtotal": 7000.00,
  "total": 7000.00,
  "status": "pending",
  "dueDate": "2026-06-07T00:00:00Z",
  "createdAt": "2026-05-07T10:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `201`: Criado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado

---

### GET `/api/invoices/:id`

**Buscar Fatura por ID** _(requer autenticação / requires authentication)_

Retorna os dados completos de uma fatura específica com itens detalhados.

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439066",
  "number": "INV-2026-0042",
  "contactId": "507f1f77bcf86cd799439011",
  "items": [
    {
      "productId": "507f1f77bcf86cd799439055",
      "name": "Consultoria Mensal",
      "quantity": 2,
      "unitPrice": 3500.00,
      "total": 7000.00
    }
  ],
  "subtotal": 7000.00,
  "total": 7000.00,
  "status": "pending",
  "dueDate": "2026-06-07T00:00:00Z",
  "notes": "Pagamento via PIX",
  "createdAt": "2026-05-07T10:00:00Z",
  "updatedAt": "2026-05-07T10:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Registro encontrado
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### PUT `/api/invoices/:id`

**Atualizar Fatura** _(requer autenticação / requires authentication)_

Atualiza dados de uma fatura. Use para alterar status, itens ou data de vencimento.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `status` | string | Não / No | Status: pending, paid, overdue, cancelled |
| `dueDate` | string | Não / No | Nova data de vencimento (ISO 8601) |
| `notes` | string | Não / No | Observações |

**Exemplo de Requisição / Request Example:**

```json
{
  "status": "paid"
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439066",
  "number": "INV-2026-0042",
  "status": "paid",
  "paidAt": "2026-05-07T16:00:00Z",
  "updatedAt": "2026-05-07T16:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Atualizado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### DELETE `/api/invoices/:id`

**Remover Fatura** _(requer autenticação / requires authentication)_

Remove permanentemente uma fatura. Apenas faturas com status "pending" ou "cancelled" podem ser removidas.

**Exemplo de Resposta / Response Example:**

```json
{
  "message": "Fatura excluída com sucesso"
}
```

**Códigos de Status / Status Codes:**

- `200`: Removido com sucesso
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### GET `/api/invoices/overdue`

**Faturas Vencidas** _(requer autenticação / requires authentication)_

Retorna todas as faturas pendentes cujo prazo já expirou.

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439066",
      "number": "INV-2026-0038",
      "contactId": "507f1f77bcf86cd799439011",
      "total": 7000.00,
      "dueDate": "2026-04-30T00:00:00Z",
      "status": "pending"
    }
  ],
  "total": 5,
  "totalValue": 23500.00
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

## Cotações

Propostas comerciais com conversão direta para faturas.

### GET `/api/quotes`

**Listar Cotações** _(requer autenticação / requires authentication)_

Retorna a lista paginada de cotações do usuário.

**Query Parameters:**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `page` | integer | Não / No | Número da página |
| `limit` | integer | Não / No | Itens por página (máx: 100) |
| `status` | string | Não / No | Filtrar por status: draft, sent, accepted, rejected, converted |

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439077",
      "number": "QT-2026-0015",
      "contactId": "507f1f77bcf86cd799439011",
      "total": 9450.00,
      "status": "sent",
      "validUntil": "2026-05-30T00:00:00Z",
      "createdAt": "2026-05-07T10:00:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "limit": 20
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

### POST `/api/quotes`

**Criar Cotação** _(requer autenticação / requires authentication)_

Gera uma proposta comercial com itens do catálogo.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `contactId` | string | Sim / Yes | ID do contato |
| `items` | object[] | Sim / Yes | Itens: { productId, quantity, unitPrice, discount } |
| `validUntil` | string | Não / No | Data de validade (ISO 8601) |
| `notes` | string | Não / No | Condições comerciais |

**Exemplo de Requisição / Request Example:**

```json
{
  "contactId": "507f1f77bcf86cd799439011",
  "items": [
    {
      "productId": "507f1f77bcf86cd799439055",
      "quantity": 3,
      "unitPrice": 3500.00,
      "discount": 10
    }
  ],
  "validUntil": "2026-05-30T00:00:00Z",
  "notes": "Desconto para contrato anual"
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439077",
  "number": "QT-2026-0015",
  "contactId": "507f1f77bcf86cd799439011",
  "items": [...],
  "subtotal": 10500.00,
  "discount": 1050.00,
  "total": 9450.00,
  "status": "draft",
  "validUntil": "2026-05-30T00:00:00Z",
  "createdAt": "2026-05-07T10:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `201`: Criado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado

---

### GET `/api/quotes/:id`

**Buscar Cotação por ID** _(requer autenticação / requires authentication)_

Retorna os dados completos de uma cotação específica com itens detalhados.

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439077",
  "number": "QT-2026-0015",
  "contactId": "507f1f77bcf86cd799439011",
  "items": [
    {
      "productId": "507f1f77bcf86cd799439055",
      "name": "Consultoria Mensal",
      "quantity": 3,
      "unitPrice": 3500.00,
      "discount": 10,
      "total": 9450.00
    }
  ],
  "subtotal": 10500.00,
  "discount": 1050.00,
  "total": 9450.00,
  "status": "sent",
  "validUntil": "2026-05-30T00:00:00Z",
  "notes": "Desconto para contrato anual",
  "createdAt": "2026-05-07T10:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Registro encontrado
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### PUT `/api/quotes/:id`

**Atualizar Cotação** _(requer autenticação / requires authentication)_

Atualiza dados de uma cotação. Use para alterar status, itens ou validade.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `status` | string | Não / No | Status: draft, sent, accepted, rejected |
| `validUntil` | string | Não / No | Nova data de validade (ISO 8601) |
| `notes` | string | Não / No | Condições comerciais |

**Exemplo de Requisição / Request Example:**

```json
{
  "status": "accepted"
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439077",
  "number": "QT-2026-0015",
  "status": "accepted",
  "updatedAt": "2026-05-07T15:30:00Z"
}
```

**Códigos de Status / Status Codes:**

- `200`: Atualizado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### DELETE `/api/quotes/:id`

**Remover Cotação** _(requer autenticação / requires authentication)_

Remove permanentemente uma cotação. Apenas cotações com status "draft" podem ser removidas.

**Exemplo de Resposta / Response Example:**

```json
{
  "message": "Cotação excluída com sucesso"
}
```

**Códigos de Status / Status Codes:**

- `200`: Removido com sucesso
- `401`: Não autenticado
- `403`: Sem permissão (não é o proprietário)
- `404`: Não encontrado

---

### POST `/api/quotes/:id/convert-to-invoice`

**Converter em Fatura** _(requer autenticação / requires authentication)_

Converte uma cotação aceita em fatura. Itens, valores e condições são copiados automaticamente.

**Exemplo de Resposta / Response Example:**

```json
{
  "invoice": {
    "id": "507f1f77bcf86cd799439088",
    "number": "INV-2026-0043",
    "total": 9450.00,
    "status": "pending",
    "createdAt": "2026-05-07T12:00:00Z"
  },
  "quote": {
    "id": "507f1f77bcf86cd799439077",
    "status": "converted"
  }
}
```

**Códigos de Status / Status Codes:**

- `201`: Fatura gerada a partir da cotação
- `400`: Cotação não pode ser convertida (status inválido)
- `404`: Cotação não encontrada

---

## Atividades

Registro de atividades e timeline de interações com contatos e negócios.

### POST `/api/activities`

**Registrar Atividade** _(requer autenticação / requires authentication)_

Registra uma nova atividade vinculada a um contato, empresa ou negócio.

**Request Body (JSON):**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `type` | string | Sim / Yes | Tipo: call, email, meeting, note, task |
| `description` | string | Sim / Yes | Descrição da atividade |
| `relatedTo` | string | Sim / Yes | ID da entidade relacionada (contato, empresa ou negócio) |
| `relatedType` | string | Sim / Yes | Tipo da entidade: contact, company, deal |
| `metadata` | object | Não / No | Dados adicionais livres (ex: duração da ligação) |

**Exemplo de Requisição / Request Example:**

```json
{
  "type": "call",
  "description": "Ligação para alinhar proposta comercial",
  "relatedTo": "507f1f77bcf86cd799439011",
  "relatedType": "contact",
  "metadata": { "duration": "15min" }
}
```

**Exemplo de Resposta / Response Example:**

```json
{
  "id": "507f1f77bcf86cd799439111",
  "type": "call",
  "description": "Ligação para alinhar proposta comercial",
  "relatedTo": "507f1f77bcf86cd799439011",
  "relatedType": "contact",
  "metadata": { "duration": "15min" },
  "createdBy": "507f1f77bcf86cd799439001",
  "createdAt": "2026-05-07T10:00:00Z"
}
```

**Códigos de Status / Status Codes:**

- `201`: Criado com sucesso
- `400`: Dados inválidos
- `401`: Não autenticado

---

### GET `/api/activities/recent`

**Atividades Recentes** _(requer autenticação / requires authentication)_

Retorna as atividades mais recentes do usuário autenticado.

**Query Parameters:**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `limit` | integer | Não / No | Quantidade de atividades (padrão: 10, máx: 100) |

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439111",
      "type": "call",
      "description": "Ligação para alinhar proposta",
      "relatedTo": "507f1f77bcf86cd799439011",
      "relatedType": "contact",
      "createdAt": "2026-05-07T10:00:00Z"
    }
  ]
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

### GET `/api/activities/entity/:entityId`

**Atividades por Entidade** _(requer autenticação / requires authentication)_

Retorna todas as atividades vinculadas a um contato, empresa ou negócio específico.

**Query Parameters:**

| Campo / Field | Tipo / Type | Obrigatório / Required | Descrição / Description |
|---------------|-------------|------------------------|--------------------------|
| `page` | integer | Não / No | Número da página |
| `limit` | integer | Não / No | Itens por página (máx: 100) |

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439111",
      "type": "call",
      "description": "Ligação comercial",
      "relatedTo": "507f1f77bcf86cd799439011",
      "relatedType": "contact",
      "createdAt": "2026-05-07T10:00:00Z"
    }
  ],
  "total": 8,
  "page": 1,
  "limit": 20
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

## Relatórios

Dashboards, métricas de vendas e análises de performance.

### GET `/api/reports/dashboard`

**Dashboard Geral** _(requer autenticação / requires authentication)_

Retorna as principais métricas do CRM: contatos, negócios, receita e tarefas.

**Exemplo de Resposta / Response Example:**

```json
{
  "totalContacts": 142,
  "totalDeals": 24,
  "openDeals": 18,
  "totalRevenue": 125000.00,
  "pendingInvoices": 8,
  "overdueInvoices": 3,
  "overdueTasks": 5,
  "dealsWonThisMonth": 4,
  "revenueThisMonth": 32000.00
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

### GET `/api/reports/deal-conversion`

**Taxa de Conversão** _(requer autenticação / requires authentication)_

Retorna métricas de conversão do funil de vendas.

**Exemplo de Resposta / Response Example:**

```json
{
  "totalDeals": 50,
  "wonDeals": 18,
  "lostDeals": 12,
  "openDeals": 20,
  "conversionRate": 60.0,
  "averageTicket": 8500.00,
  "averageCycleDays": 22
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

### GET `/api/reports/task-completion`

**Conclusão de Tarefas** _(requer autenticação / requires authentication)_

Retorna métricas de conclusão de tarefas: total, concluídas, atrasadas e taxa de conclusão.

**Exemplo de Resposta / Response Example:**

```json
{
  "totalTasks": 45,
  "completedTasks": 32,
  "overdueTasks": 5,
  "pendingTasks": 8,
  "completionRate": 71.1,
  "averageCompletionDays": 3.2
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

### GET `/api/reports/pipeline`

**Relatório do Funil de Vendas** _(requer autenticação / requires authentication)_

Retorna análise detalhada do funil de vendas com métricas por estágio.

**Exemplo de Resposta / Response Example:**

```json
{
  "totalValue": 380000.00,
  "weightedValue": 245000.00,
  "stages": [
    { "name": "Prospecção", "count": 8, "value": 120000.00 },
    { "name": "Qualificação", "count": 5, "value": 85000.00 },
    { "name": "Proposta", "count": 6, "value": 95000.00 },
    { "name": "Negociação", "count": 3, "value": 60000.00 },
    { "name": "Fechamento", "count": 2, "value": 20000.00 }
  ],
  "averageDealValue": 15833.33,
  "averageCycleDays": 28
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

## Webhooks

Consulte seus webhooks configurados. Criação, edição e exclusão são feitas pela interface web.

### GET `/api/webhooks`

**Listar Webhooks** _(requer autenticação / requires authentication)_

Retorna todos os webhooks configurados pelo usuário. Para criar, editar ou remover webhooks, use a interface web do SimpleCRM.

**Exemplo de Resposta / Response Example:**

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439099",
      "url": "https://meusite.com/webhooks/crm",
      "events": ["contact.created", "deal.updated"],
      "isActive": true,
      "createdAt": "2026-05-01T10:00:00Z",
      "updatedAt": "2026-05-01T10:00:00Z"
    }
  ],
  "availableEvents": [
    "contact.created", "contact.updated", "contact.deleted",
    "company.created", "company.updated", "company.deleted",
    "deal.created", "deal.updated", "deal.deleted",
    "task.created", "task.completed", "task.deleted",
    "invoice.created", "invoice.updated", "invoice.paid",
    "quote.created", "quote.updated",
    "product.created", "product.updated", "product.deleted"
  ]
}
```

**Códigos de Status / Status Codes:**

- `200`: Lista retornada com sucesso
- `401`: Não autenticado

---

## Eventos de Webhook / Webhook Events

Webhooks enviam notificações HTTP POST em tempo real para sua URL quando eventos ocorrem.
Cada payload inclui `event` (string), `timestamp` (unix em segundos) e `data` (object).

**Verificação de assinatura:** Cada requisição inclui um header `X-Webhook-Signature`. Calcule `HMAC-SHA256(secret, rawBody)` e compare.

### Contatos

#### `contact.created`

Disparado quando um novo contato é criado.

```json
{
  "event": "contact.created",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Maria Santos",
    "email": "maria@empresa.com",
    "phone": "+5511987654321",
    "createdAt": "2026-05-07T10:00:00Z"
  }
}
```

#### `contact.updated`

Disparado quando os dados de um contato são atualizados.

```json
{
  "event": "contact.updated",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Maria Santos",
    "position": "CEO",
    "updatedAt": "2026-05-07T15:30:00Z"
  }
}
```

#### `contact.deleted`

Disparado quando um contato é removido.

```json
{
  "event": "contact.deleted",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439011"
  }
}
```

### Empresas

#### `company.created`

Disparado quando uma nova empresa é cadastrada.

```json
{
  "event": "company.created",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439022",
    "name": "Tech Solutions Ltda",
    "cnpj": "12.345.678/0001-90",
    "createdAt": "2026-05-07T10:00:00Z"
  }
}
```

#### `company.updated`

Disparado quando os dados de uma empresa são atualizados.

```json
{
  "event": "company.updated",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439022",
    "name": "Tech Solutions Ltda",
    "updatedAt": "2026-05-07T15:30:00Z"
  }
}
```

#### `company.deleted`

Disparado quando uma empresa é removida.

```json
{
  "event": "company.deleted",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439022"
  }
}
```

### Negócios

#### `deal.created`

Disparado quando um novo negócio é criado no funil de vendas.

```json
{
  "event": "deal.created",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439033",
    "title": "Implantação ERP",
    "value": 45000.00,
    "stage": "novo",
    "status": "open",
    "createdAt": "2026-05-07T10:00:00Z"
  }
}
```

#### `deal.updated`

Disparado quando um negócio é atualizado (mudança de estágio, valor, etc).

```json
{
  "event": "deal.updated",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439033",
    "title": "Implantação ERP",
    "stage": "negociacao",
    "probability": 70,
    "updatedAt": "2026-05-07T15:30:00Z"
  }
}
```

#### `deal.deleted`

Disparado quando um negócio é removido do funil de vendas.

```json
{
  "event": "deal.deleted",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439033"
  }
}
```

### Tarefas

#### `task.created`

Disparado quando uma nova tarefa é criada.

```json
{
  "event": "task.created",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439044",
    "title": "Follow-up Tech Solutions",
    "dueDate": "2026-05-10T14:00:00Z",
    "priority": "high",
    "createdAt": "2026-05-07T10:00:00Z"
  }
}
```

#### `task.completed`

Disparado quando uma tarefa é marcada como concluída.

```json
{
  "event": "task.completed",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439044",
    "title": "Follow-up Tech Solutions",
    "completedAt": "2026-05-07T16:00:00Z"
  }
}
```

#### `task.deleted`

Disparado quando uma tarefa é removida.

```json
{
  "event": "task.deleted",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439044"
  }
}
```

### Faturas

#### `invoice.created`

Disparado quando uma nova fatura é gerada.

```json
{
  "event": "invoice.created",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439066",
    "number": "INV-2026-0042",
    "total": 7000.00,
    "status": "pending",
    "dueDate": "2026-06-07T00:00:00Z",
    "createdAt": "2026-05-07T10:00:00Z"
  }
}
```

#### `invoice.updated`

Disparado quando uma fatura é atualizada.

```json
{
  "event": "invoice.updated",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439066",
    "number": "INV-2026-0042",
    "status": "pending",
    "updatedAt": "2026-05-07T15:30:00Z"
  }
}
```

#### `invoice.paid`

Disparado quando uma fatura é marcada como paga.

```json
{
  "event": "invoice.paid",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439066",
    "number": "INV-2026-0042",
    "total": 7000.00,
    "paidAt": "2026-05-07T16:00:00Z"
  }
}
```

### Cotações

#### `quote.created`

Disparado quando uma nova cotação é criada.

```json
{
  "event": "quote.created",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439077",
    "number": "QT-2026-0015",
    "total": 9450.00,
    "status": "draft",
    "createdAt": "2026-05-07T10:00:00Z"
  }
}
```

#### `quote.updated`

Disparado quando uma cotação é atualizada (status, itens, etc).

```json
{
  "event": "quote.updated",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439077",
    "number": "QT-2026-0015",
    "status": "accepted",
    "updatedAt": "2026-05-07T15:30:00Z"
  }
}
```

### Produtos

#### `product.created`

Disparado quando um novo produto é adicionado ao catálogo.

```json
{
  "event": "product.created",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439055",
    "name": "Consultoria Mensal",
    "price": 3500.00,
    "createdAt": "2026-05-07T10:00:00Z"
  }
}
```

#### `product.updated`

Disparado quando um produto é atualizado.

```json
{
  "event": "product.updated",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439055",
    "name": "Consultoria Mensal",
    "price": 4000.00,
    "updatedAt": "2026-05-07T15:30:00Z"
  }
}
```

#### `product.deleted`

Disparado quando um produto é removido do catálogo.

```json
{
  "event": "product.deleted",
  "timestamp": 1715100000,
  "data": {
    "id": "507f1f77bcf86cd799439055"
  }
}
```

---

## Eventos Disponíveis / Available Webhook Events

`contact.created`, `contact.updated`, `contact.deleted`, `company.created`, `company.updated`, `company.deleted`, `deal.created`, `deal.updated`, `deal.deleted`, `task.created`, `task.completed`, `task.deleted`, `invoice.created`, `invoice.updated`, `invoice.paid`, `quote.created`, `quote.updated`, `product.created`, `product.updated`, `product.deleted`