101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
# 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)?
|