3.2 KiB

Raw Blame History

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

Clique no seu Avatar > Perfil > Token de Acesso.
Clique em Criar Token.
Nome: Integracao ERP.
Permissões: Marque apenas o necessário (ex: ticket.create, user.check).
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)

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

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.

Acesse Admin > Gerenciar > Gatilhos.
Crie um novo Gatilho.
Condição: (ex: Ticket Priority mudou para 3 High).
Ação: Webhook.
Endpoint: URL do seu n8n/Slack.
Método: POST.

Custom Payload (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)?

3.2 KiB Raw Blame History