# Zapini API — Automações

**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**.

---

## Controle de Automação

Gerencie a automação de IA para conversas. Quando a automação está ativa, mensagens manuais são bloqueadas até você assumir o chat.

**Base URL:** `/api/v1/chat`

### Importante: Comportamento da Automação

- Quando a automação está **ativa**, mensagens manuais são bloqueadas para evitar conflitos com respostas da IA.
- Use **pause** para assumir o chat e enviar mensagens manualmente.
- Use **resume** para deixar a IA gerenciar a conversa novamente.
- **IMPORTANTE**: Para retomar a automação, você deve primeiro **arquivar** a conversa.

> **Segurança: Arquivamento Necessário para Retomar**
>
> A automação só pode ser retomada após arquivar a conversa. Isso garante que a sessão de atendimento manual seja encerrada corretamente antes de devolver o controle à IA. Ao retomar, a conversa será automaticamente desarquivada.

---

### POST /chat/conversations/{uuid}/pause-automation

Pausa a automação de uma conversa, permitindo mensagens manuais.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| reason | string | Não | Motivo opcional para pausar a automação |

**Exemplo de Requisição:**

```bash
curl -X POST https://zapini.app/api/v1/chat/conversations/550e8400-e29b-41d4-a716-446655440045/pause-automation \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Manual takeover for VIP client"}'
```

**Resposta:**

```json
{
  "success": true,
  "message": "Automation paused successfully.",
  "data": {
    "conversation_id": "550e8400-e29b-41d4-a716-446655440045",
    "automation_paused": true,
    "paused_at": "2025-12-20T14:30:00Z",
    "paused_by": "John Doe",
    "reason": "Manual takeover for VIP client"
  }
}
```

**Respostas de Erro:**

| Código | Erro | Descrição |
|--------|------|-----------|
| 400 | NO_ACTIVE_AUTOMATION | Conversa sem automação ativa |
| 400 | AUTOMATION_ALREADY_PAUSED | Automação já está pausada |
| 404 | NOT_FOUND | Conversa não encontrada |

---

### POST /chat/conversations/{uuid}/resume-automation

Retoma a automação de uma conversa, deixando a IA gerenciar as respostas.

> **Nota:** A conversa deve estar arquivada antes de retomar a automação.

**Exemplo de Requisição:**

```bash
curl -X POST https://zapini.app/api/v1/chat/conversations/550e8400-e29b-41d4-a716-446655440045/resume-automation \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"
```

**Resposta:**

```json
{
  "success": true,
  "message": "Automation resumed successfully.",
  "data": {
    "conversation_id": "550e8400-e29b-41d4-a716-446655440045",
    "automation_paused": false,
    "resumed_at": "2025-12-20T15:00:00Z"
  }
}
```

**Respostas de Erro:**

| Código | Erro | Descrição |
|--------|------|-----------|
| 400 | NO_ACTIVE_AUTOMATION | Conversa sem automação ativa |
| 400 | AUTOMATION_NOT_PAUSED | Automação não está pausada |
| 404 | NOT_FOUND | Conversa não encontrada |

---

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