# API Zapini — Funções de IA

Gerencie funções de IA (ferramentas baseadas em webhook) que seu agente de IA pode chamar durante conversas. Crie, configure, teste e monitore funções personalizadas que ampliam as capacidades do seu agente de IA.

**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 | `/ai-functions` | Listar todas as funções de IA |
| POST | `/ai-functions` | Criar uma nova função de IA |
| GET | `/ai-functions/executions/{uuid}` | Obter detalhes da execução |
| GET | `/ai-functions/{uuid}` | Obter detalhes da função de IA |
| PUT | `/ai-functions/{uuid}` | Atualizar função de IA |
| DELETE | `/ai-functions/{uuid}` | Excluir função de IA |
| POST | `/ai-functions/{uuid}/toggle` | Ativar/desativar função |
| POST | `/ai-functions/{uuid}/test` | Testar execução da função |
| GET | `/ai-functions/{uuid}/executions` | Listar execuções da função |

---

## Listar Funções de IA

```
GET /api/v1/ai-functions
```

**Parâmetros de Consulta:**

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `integration_uuid` | string | Filtrar por UUID da integração |
| `type` | string | Filtrar por tipo: `fetch_data`, `collect_submit`, `action` |
| `enabled` | boolean | Filtrar por status de ativação |
| `search` | string | Buscar por nome 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/ai-functions?type=fetch_data&enabled=true" \
  -H "Authorization: Bearer {token}"
```

---

## Criar Função de IA

```
POST /api/v1/ai-functions
```

**Parâmetros do Corpo:**

| Parâmetro | Obrigatório | Tipo | Descrição |
|-----------|-------------|------|-----------|
| `integration_uuid` | Sim | string | UUID da integração do Agente de IA |
| `name` | Sim | string | Nome da função (minúsculas, apenas underscores) |
| `display_name` | Sim | string | Nome de exibição amigável |
| `description` | Sim | string | Descrição exibida ao agente de IA |
| `type` | Sim | string | `fetch_data`, `collect_submit` ou `action` |
| `endpoint_url` | Não | string | URL do webhook a ser chamado |
| `http_method` | Não | string | GET, POST, PUT, PATCH, DELETE |
| `auth_type` | Não | string | none, bearer, basic, api_key, custom |
| `auth_config` | Não | object | Credenciais de autenticação |
| `headers` | Não | object | Cabeçalhos HTTP personalizados |
| `request_body_template` | Não | object | Modelo do corpo da requisição |
| `response_mapping` | Não | object | Mapeamento de campos da resposta |
| `success_message` | Não | string | Mensagem em caso de sucesso |
| `error_message` | Não | string | Mensagem em caso de erro |
| `requires_confirmation` | Não | boolean | Pedir confirmação ao usuário antes de executar |
| `timeout` | Não | integer | Tempo limite em segundos (1-120) |
| `max_retries` | Não | integer | Máximo de tentativas (0-5) |
| `is_enabled` | Não | boolean | Se a função está ativa |
| `priority` | Não | integer | Prioridade de execução (0-100) |
| `parameters` | Não | array | Array de parâmetros da função |

**Objeto de Parâmetro:**

| Campo | Obrigatório | Tipo | Descrição |
|-------|-------------|------|-----------|
| `name` | Sim | string | Nome do parâmetro |
| `display_name` | Sim | string | Nome de exibição |
| `description` | Não | string | Descrição para a IA |
| `type` | Sim | string | string, number, integer, boolean, email, phone, cpf, cnpj, date, datetime, select, multi_select |
| `is_required` | Não | boolean | Se é obrigatório |
| `options` | Não | array | Opções para tipos select |
| `collect_from_user` | Não | boolean | Coletar do usuário no chat |
| `collect_from_context` | Não | boolean | Extrair do contexto |

**Exemplo:**

```bash
curl -X POST "https://zapini.app/api/v1/ai-functions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_uuid": "abc-123-def",
    "name": "check_order_status",
    "display_name": "Check Order Status",
    "description": "Checks the status of a customer order by order number",
    "type": "fetch_data",
    "endpoint_url": "https://api.myshop.com/orders/status",
    "http_method": "GET",
    "auth_type": "bearer",
    "auth_config": {"token": "my-shop-api-key"},
    "parameters": [
      {
        "name": "order_number",
        "display_name": "Order Number",
        "description": "The customer order number",
        "type": "string",
        "is_required": true,
        "collect_from_user": true
      }
    ]
  }'
```

---

## Obter Função de IA

```
GET /api/v1/ai-functions/{uuid}
```

Retorna os detalhes da função com parâmetros e estatísticas de execução (contagem de execuções, última execução, taxa de sucesso dos últimos 30 dias).

---

## Atualizar Função de IA

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

Mesmos parâmetros da criação. Se o array `parameters` for fornecido, todos os parâmetros existentes serão substituídos.

---

## Excluir Função de IA

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

Falha com `409 ACTIVE_EXECUTIONS` se houver execuções ativas em andamento.

---

## Ativar/Desativar Função de IA

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

Alterna o estado `is_enabled`.

---

## Testar Função de IA

```
POST /api/v1/ai-functions/{uuid}/test
```

**Corpo:**

```json
{
  "parameters": {
    "order_number": "ORD-12345"
  }
}
```

Executa uma chamada de teste ao endpoint da função e retorna o resultado.

---

## Listar Execuções

```
GET /api/v1/ai-functions/{uuid}/executions
```

**Parâmetros de Consulta:**

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `status` | string | Filtrar: pending, collecting, executing, completed, failed, timeout |
| `per_page` | integer | Resultados por página (máx. 100, padrão 20) |

---

## Obter Detalhes da Execução

```
GET /api/v1/ai-functions/executions/{uuid}
```

Retorna os detalhes completos da execução, incluindo dados de requisição/resposta, parâmetros coletados e informações de tempo.

---

## Códigos de Erro

| Código | HTTP | Descrição |
|--------|------|-----------|
| `AI_AGENT_NOT_ENABLED` | 403 | Nenhuma integração de Agente de IA ativa |
| `DUPLICATE_NAME` | 422 | Nome da função já existe na integração |
| `ACTIVE_EXECUTIONS` | 409 | Não é possível excluir enquanto há execuções em andamento |
| `INVALID_INTEGRATION_TYPE` | 422 | A integração não é do tipo Agente de IA |
| `TEST_FAILED` | 500 | A execução de teste falhou |