# MANUAL TÉCNICO - API E INTEGRAÇÕES - ZAMMAD

**Código:** ITGENG 0002/26 | **Classificação:** INTERNO
**Responsável:** João Pedro Toledo Gonçalves | **Data:** {{DATA_ATUAL}}

## 1. HISTÓRICO DE REVISÃO

| Data | Versão | Descrição | Autor |
| :--- | :--- | :--- | :--- |
| {{DATA_ATUAL}} | 1.0 | Criação Inicial | João Pedro Toledo Gonçalves |

## 2. OBJETIVO
Utilizar a REST API do Zammad para integrações com sistemas externos (CRM, ERP) e configurar Webhooks de saída.

## 3. PRÉ-REQUISITOS
*   [ ] Token de Acesso (Gerado no Perfil do Usuário).
*   [ ] Conhecimento de JSON/HTTP ou `curl`.

## 4. PASSO A PASSO (EXECUÇÃO)

### Etapa 1: Gerar Token de Acesso
1.  Clique no seu Avatar > **Perfil** > **Token de Acesso**.
2.  Clique em **Criar Token**.
3.  Nome: `Integracao ERP`.
4.  Permissões: Marque apenas o necessário (ex: `ticket.create`, `user.check`).
5.  **Copie o Token agora.** Ele não será mostrado novamente.

### Etapa 2: Usar a API (Exemplos)

**Endpoint Base:** `https://seu-zammad.com/api/v1`

**A. Criar um Ticket (CURL)**
```bash
curl -X POST -H "Authorization: Token token=SEU_TOKEN" \
-H "Content-Type: application/json" \
--data '{
  "title": "Ajuda com Impressora",
  "group": "Service Desk",
  "customer": "email@cliente.com",
  "article": {
    "subject": "Socorro",
    "body": "Impressora pegou fogo",
    "type": "note",
    "internal": false
  }
}' \
https://zammad.local/api/v1/tickets
```

**B. Buscar Usuário por Email**
```bash
curl -H "Authorization: Token token=SEU_TOKEN" \
https://zammad.local/api/v1/users/search?query=email:joao@itguys.com
```

### Etapa 3: Webhooks (Saída)
Notificar sistema externo (ex: Slack, Discord, n8n) quando algo acontece no Zammad.

1.  Acesse **Admin** > **Gerenciar** > **Gatilhos**.
2.  Crie um novo Gatilho.
3.  **Condição:** (ex: Ticket Priority mudou para 3 High).
4.  **Ação:** `Webhook`.
5.  **Endpoint:** URL do seu n8n/Slack.
6.  **Método:** `POST`.
7.  **Custom Payload (JSON):**
    ```json
    {
      "ticket_id": "#{ticket.id}",
      "title": "#{ticket.title}",
      "state": "#{ticket.state}"
    }
    ```

## 5. SOLUÇÃO DE PROBLEMAS (TROUBLESHOOTING)

!!! warning "Pânico: Integração Quebrou"
    Erros de Autenticação e Payload.

**Problema 1: Erro 401 Unauthorized**
*   **Causa:** Token inválido ou cabeçalho mal formatado.
*   **Solução:** O header deve ser EXATAMENTE `Authorization: Token token=XYZ`. Cuidado com espaços extras.

**Problema 2: Erro 422 Unprocessable Entity**
*   **Causa:** JSON inválido ou campo obrigatório faltando (ex: `group` incorreto).
*   **Solução:** Verifique se o nome do `group` existe exatamente como escrito.

**Problema 3: Rate Limiting**
*   **Nota:** O Zammad não documenta um rate limit fixo, mas abusos travam o Webserver. Use intervalos de 1s entre requests em scripts de lote.

## 6. DADOS TÉCNICOS

| Recurso | Info |
| :--- | :--- |
| **Doc Oficial** | `docs.zammad.org/en/latest/api/intro.html` |
| **Auth** | Bearer Token ou HTTP Basic (User/Pass). |
| **Paginação** | Parâmetros `?page=1&per_page=10`. |

## 7. VALIDAÇÃO FINAL
- [ ] O comando CURL de teste criou um ticket?
- [ ] O Webhook disparou para o endpoint de teste (Use `webhook.site` para testar)?