# Zapini API — Contatos e Mensagens Agendadas

**Versão:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Autenticação

Todos os endpoints requerem um Bearer Token:

```
Authorization: Bearer {your_token}
Accept: application/json
Content-Type: application/json
```

Gere tokens de API no painel admin em **API Docs → Gerenciar Tokens**.

---

## Contatos

### GET /contacts

Listar contatos.

**Parâmetros de Consulta:**

| Campo | Tipo | Descrição |
|-------|------|-----------|
| instance_id | string | UUID da instância |
| search | string | Pesquisar por nome, número, e-mail ou empresa |
| is_group | boolean | Filtrar grupos |
| sort | string | Campo de ordenação |
| dir | string | Direção (asc, desc) |
| per_page | integer | Itens por página |

---

### POST /contacts

Criar novo contato.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| instance_id | string | Sim | UUID da instância |
| phone_number | string | Sim | Número de telefone |
| first_name | string | Não | Primeiro nome |
| last_name | string | Não | Sobrenome |
| display_name | string | Não | Nome de exibição |
| email | string | Não | E-mail |
| company | string | Não | Empresa |
| job_title | string | Não | Cargo |
| notes | string | Não | Observações |
| custom_fields | object | Não | Campos personalizados |

---

### POST /contacts/import

Importar contatos em massa.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| instance_id | string | Sim | UUID da instância |
| contacts | array | Sim | Lista de contatos (máx. 1000) |

**Exemplo:**

```bash
curl -X POST https://zapini.app/api/v1/contacts/import \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "550e8400-e29b-41d4-a716-446655440000",
    "contacts": [
      {
        "phone_number": "+15551234567",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com"
      },
      {
        "phone_number": "+15559876543",
        "first_name": "Jane",
        "company": "XYZ Corp"
      }
    ]
  }'
```

---

### GET /contacts/{uuid}

Retorna detalhes do contato.

---

### PATCH /contacts/{uuid}

Atualizar um contato.

---

### DELETE /contacts/{uuid}

Excluir um contato.

---

### GET /contacts/{uuid}/messages

Listar mensagens trocadas com um contato.

---

## Mensagens Agendadas

### GET /scheduled

Listar mensagens agendadas.

**Parâmetros de Consulta:**

| Campo | Tipo | Descrição |
|-------|------|-----------|
| instance_id | string | UUID da instância |
| from | datetime | Data de início |
| to | datetime | Data de fim |
| per_page | integer | Itens por página |

---

### POST /scheduled

Agendar nova mensagem.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| instance_id | string | Sim | UUID da instância |
| recipient | string | Sim* | Número do destinatário |
| contact_id | string | Sim* | UUID do contato (alternativa ao recipient) |
| message | string | Sim | Conteúdo da mensagem |
| scheduled_at | datetime | Sim | Data/hora de envio |
| media_url | string | Não | URL da mídia |
| media_type | string | Não | Tipo de mídia |

*Um dos dois é obrigatório: recipient ou contact_id

---

### GET /scheduled/{uuid}

Retorna detalhes da mensagem agendada.

---

### PATCH /scheduled/{uuid}

Atualizar mensagem agendada pendente.

---

### DELETE /scheduled/{uuid}

Cancelar mensagem agendada.

---

### POST /scheduled/{uuid}/send-now

Enviar a mensagem agendada imediatamente.

---

*Gerado por Zapini — https://zapini.app*