# API Zapini — Funções Externas

Gerencie funções externas — endpoints de webhook que permitem que sistemas externos acionem ações no WhatsApp (enviar mensagens, gerenciar contatos, controlar automações). Cada função recebe uma chave de API única para autenticação.

**Requisito:** Uma integração de Agente de IA ativa na sua conta.

**URL Base:** `https://zapini.app/api/v1`

**Autenticação:** `Authorization: Bearer {token}`

---

## Endpoints

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/external-functions` | Listar todas as funções externas |
| POST | `/external-functions` | Criar uma nova função externa |
| GET | `/external-functions/{uuid}` | Obter detalhes da função externa |
| PUT | `/external-functions/{uuid}` | Atualizar função externa |
| DELETE | `/external-functions/{uuid}` | Excluir função externa |
| POST | `/external-functions/{uuid}/toggle` | Ativar/desativar função |
| POST | `/external-functions/{uuid}/regenerate-key` | Regenerar chave de API |
| GET | `/external-functions/{uuid}/logs` | Listar logs de execução |

---

## Listar Funções Externas

```
GET /api/v1/external-functions
```

**Parâmetros de Consulta:**

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `instance_uuid` | string | Filtrar por UUID da instância do WhatsApp |
| `enabled` | boolean | Filtrar por status de ativação |
| `search` | string | Buscar por nome, slug ou descrição |
| `per_page` | integer | Resultados por página (máx. 100, padrão 20) |

**Exemplo:**

```bash
curl -X GET "https://zapini.app/api/v1/external-functions?enabled=true" \
  -H "Authorization: Bearer {token}"
```

---

## Criar Função Externa

```
POST /api/v1/external-functions
```

**Parâmetros do Corpo:**

| Parâmetro | Obrigatório | Tipo | Descrição |
|-----------|-------------|------|-----------|
| `instance_uuid` | Sim | string | UUID da instância do WhatsApp |
| `name` | Sim | string | Nome da função |
| `slug` | Sim | string | Slug da URL (minúsculas, apenas hífens) |
| `action_type` | Sim | string | Tipo de ação (veja abaixo) |
| `description` | Não | string | Descrição da função |
| `config` | Não | object | Configuração específica da ação |
| `rate_limit` | Não | integer | Máximo de chamadas por dia (padrão: 1000) |
| `allowed_ips` | Não | array | Endereços IP permitidos (vazio = todos) |
| `is_enabled` | Não | boolean | Se a função está ativa |

> **Importante:** A `api_key` é retornada apenas uma vez na resposta de criação. Armazene-a com segurança.

**Exemplo:**

```bash
curl -X POST "https://zapini.app/api/v1/external-functions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_uuid": "abc-123-def",
    "name": "CRM Order Notification",
    "slug": "crm-order-notify",
    "action_type": "send_message",
    "description": "Sends order status updates from CRM",
    "config": {
      "message_template": "Order {{order_id}}: {{status}}"
    },
    "rate_limit": 500,
    "allowed_ips": ["203.0.113.10"]
  }'
```

**A resposta inclui:**

```json
{
  "success": true,
  "data": {
    "uuid": "...",
    "api_key": "efk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "api_key_warning": "Store this key securely. It will not be shown again.",
    "endpoint_url": "https://zapini.app/api/v1/external/crm-order-notify",
    ...
  }
}
```

---

## Atualizar Função Externa

```
PUT /api/v1/external-functions/{uuid}
```

Mesmos parâmetros da criação (exceto `instance_uuid`, que é opcional para atualizações).

---

## Excluir Função Externa

```
DELETE /api/v1/external-functions/{uuid}
```

Exclui a função e todos os seus logs de execução.

---

## Ativar/Desativar Função Externa

```
POST /api/v1/external-functions/{uuid}/toggle
```

Alterna o estado `is_enabled`.

---

## Regenerar Chave de API

```
POST /api/v1/external-functions/{uuid}/regenerate-key
```

Gera uma nova chave de API e invalida a anterior. A nova chave é retornada apenas uma vez.

**Resposta:**

```json
{
  "success": true,
  "data": {
    "uuid": "...",
    "api_key": "efk_new_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "api_key_prefix": "efk_new_",
    "api_key_warning": "Store this key securely. It will not be shown again."
  }
}
```

---

## Listar Logs

```
GET /api/v1/external-functions/{uuid}/logs
```

**Parâmetros de Consulta:**

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `status` | string | Filtrar: success, error, unauthorized, rate_limited |
| `per_page` | integer | Resultados por página (máx. 100, padrão 20) |

---

## Tipos de Ação Disponíveis

| Ação | Descrição |
|------|-----------|
| `send_message` | Enviar uma mensagem de texto |
| `send_buttons` | Enviar uma mensagem com botões |
| `send_media` | Enviar mídia (imagem, vídeo, documento) |
| `create_contact` | Criar um novo contato |
| `update_contact` | Atualizar um contato existente |
| `create_lead` | Criar um lead no Kanban |
| `update_lead` | Atualizar um lead no Kanban |
| `pause_automation` | Pausar a automação de IA para uma conversa |
| `resume_automation` | Retomar a automação de IA para uma conversa |

---

## Códigos de Erro

| Código | HTTP | Descrição |
|--------|------|-----------|
| `AI_AGENT_NOT_ENABLED` | 403 | Nenhuma integração de Agente de IA ativa |
| `DUPLICATE_SLUG` | 422 | Slug já existe para esta conta |
| `NOT_FOUND` | 404 | Função ou instância não encontrada |