# Zapini API — Voice & IVR

**Versão:** 1.0.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**.

---

## Voice & IVR API

**Base path:** `/api/v1/voice`

> **Permissão Necessária:** Os recursos de voz requerem que `twilio_voice_enabled` esteja ativo na sua conta de tenant. Entre em contato com seu administrador ou revendedor para habilitar este recurso.

### Modos de Atendimento

| Modo | Descrição |
|------|-----------|
| `ai_only` | IA gerencia todas as chamadas recebidas automaticamente |
| `human_only` | Chamadas são roteadas apenas para agentes humanos |
| `ai_with_handoff` | IA atende primeiro, depois transfere para humano sob demanda |
| `ivr_menu` | Menu de Resposta de Voz Interativa |

---

## Números de Telefone

### GET /voice/numbers

Listar todos os números de telefone Twilio configurados.

```bash
curl -X GET https://zapini.app/api/v1/voice/numbers \
  -H "Authorization: Bearer {token}"
```

**Resposta:**

```json
{
  "success": true,
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+5511999999999",
      "friendly_name": "Main Line",
      "status": "active",
      "connection_type": "twilio",
      "call_handling_mode": "ai_only",
      "ai_enabled": true,
      "recording_enabled": false,
      "ivr_enabled": false,
      "created_at": "2026-02-14T10:00:00Z"
    }
  ]
}
```

---

### GET /voice/numbers/{uuid}

Obter detalhes de um número de telefone específico.

---

### PATCH /voice/numbers/{uuid}

Atualizar configurações de tratamento de chamadas para um número de telefone.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| call_handling_mode | string | Não | Modo de atendimento (ai_only, human_only, ai_with_handoff, ivr_menu) |
| ai_enabled | boolean | Não | Habilitar IA para tratamento de chamadas |
| recording_enabled | boolean | Não | Habilitar gravação de chamadas |
| ai_system_prompt | string | Não | Prompt do sistema de IA |

---

## Chamadas (Voz)

### GET /voice/calls

Listar chamadas de voz.

**Parâmetros de Consulta:**

| Campo | Tipo | Descrição |
|-------|------|-----------|
| phone_number_uuid | string | Filtrar por número de telefone |
| status | string | Filtrar por status (ringing, in-progress, completed, failed) |
| direction | string | Filtrar direção (inbound, outbound) |
| from | datetime | Data de início |
| to | datetime | Data de fim |
| per_page | integer | Itens por página |

**Resposta:**

```json
{
  "success": true,
  "data": [
    {
      "uuid": "call-uuid",
      "sid": "CA...",
      "direction": "inbound",
      "from_number": "+15551234567",
      "to_number": "+5511999999999",
      "status": "completed",
      "duration": 125,
      "recording_url": null,
      "ai_handled": true,
      "started_at": "2026-02-14T10:00:00Z",
      "ended_at": "2026-02-14T10:02:05Z"
    }
  ]
}
```

---

### GET /voice/calls/{uuid}

Obter detalhes completos de uma chamada de voz específica, incluindo transcrição.

---

### POST /voice/calls/{uuid}/transfer

Transferir uma chamada ativa para outro agente ou número.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| target | string | Sim | Número de telefone alvo ou endereço SIP do agente |

---

## Menu IVR

### GET /voice/numbers/{uuid}/ivr

Obter a configuração do menu IVR para um número de telefone.

---

### PUT /voice/numbers/{uuid}/ivr

Criar ou atualizar o menu IVR.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| greeting | string | Sim | Mensagem de saudação inicial |
| options | array | Sim | Array de opções do menu |
| options[].digit | string | Sim | Tecla pressionada (0-9, *, #) |
| options[].label | string | Sim | Descrição da opção |
| options[].action | string | Sim | Tipo de ação (forward, ai, department, voicemail) |
| options[].target | string | Não | Destino para ação de encaminhamento |

**Exemplo:**

```bash
curl -X PUT https://zapini.app/api/v1/voice/numbers/uuid/ivr \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "greeting": "Thank you for calling. Press 1 for Sales, 2 for Support.",
    "options": [
      {"digit": "1", "label": "Sales", "action": "ai", "target": null},
      {"digit": "2", "label": "Support", "action": "forward", "target": "+15559876543"}
    ]
  }'
```

---

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