# Modelos de Dados do SimpleCRM / SimpleCRM Data Models

> Schemas de cada entidade, relações entre elas e valores permitidos para campos enum.

---

## 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+`

---

## Schemas das Entidades

Os campos abaixo são derivados dos endpoints de criação (POST) e das respostas (GET) de cada entidade.

### Contatos

CRUD completo para gerenciamento de contatos e leads.

**Campos para criação / Creation fields:**

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

**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
}
```

### Empresas

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

**Campos para criação / Creation fields:**

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

**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
}
```

### Negócios

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

**Campos para criação / Creation fields:**

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

**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
}
```

### Tarefas

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

**Campos para criação / Creation fields:**

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

**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
}
```

### Produtos

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

**Campos para criação / Creation fields:**

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

**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
}
```

### Faturas

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

**Campos para criação / Creation fields:**

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

**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
}
```

### Cotações

Propostas comerciais com conversão direta para faturas.

**Campos para criação / Creation fields:**

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

**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
}
```

### Atividades

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

**Campos para criação / Creation fields:**

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

**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"
    }
  ]
}
```

### Relatórios

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

**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
}
```

### Webhooks

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

**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"
  ]
}
```