# Deep Service Desk Widget
Widget Vue.js para integração com o sistema Deep Service Desk. Compatível com Vue 2.7.16 e Vue 3, oferece uma interface moderna e responsiva para criação de tickets de suporte.
## 📋 Índice
- [Características](#características)
- [Instalação](#instalação)
- [Configuração](#configuração)
- [Uso Básico](#uso-básico)
- [Componentes Disponíveis](#componentes-disponíveis)
- [API e Métodos](#api-e-métodos)
- [Eventos](#eventos)
- [Personalização](#personalização)
- [Exemplos](#exemplos)
- [Troubleshooting](#troubleshooting)
## ✨ Características
- 🎯 **Compatibilidade**: Vue 2.7.16 e Vue 3
- 🎨 **Interface Moderna**: Design responsivo e intuitivo
- 🔄 **Botão Flutuante**: Botão automático para abertura de tickets
- 📱 **Responsivo**: Funciona perfeitamente em desktop e mobile
- 🔧 **Configurável**: Múltiplas opções de configuração
- 🌐 **Independente**: Funciona mesmo sem Vue (fallback HTML)
- 🔔 **Notificações**: Sistema de notificações toast integrado
- 🔒 **Seguro**: Validação de dados e tratamento de erros
## 📦 Instalação
### Via NPM (Recomendado)
```bash
npm install @pedrohrs/deep-service-desk-widget
```
### Via Yarn
```bash
yarn add @pedrohrs/deep-service-desk-widget
```
### Via CDN
```html
```
## ⚙️ Configuração
### Vue 3
```javascript
import { createApp } from 'vue'
import App from './App.vue'
import DeepServiceDeskPlugin from '@pedrohrs/deep-service-desk-widget'
const app = createApp(App)
// Configuração do plugin
app.use(DeepServiceDeskPlugin, {
apiUrl: 'https://sua-api.com/api',
clientUuid: 'seu-client-uuid-aqui', // OBRIGATÓRIO
showFloatingButton: true // Opcional, padrão: true
})
app.mount('#app')
```
### Vue 2.7.16
```javascript
import Vue from 'vue'
import App from './App.vue'
import DeepServiceDeskPlugin from '@pedrohrs/deep-service-desk-widget'
// Configuração do plugin
Vue.use(DeepServiceDeskPlugin, {
apiUrl: 'https://sua-api.com/api',
clientUuid: 'seu-client-uuid-aqui', // OBRIGATÓRIO
showFloatingButton: true // Opcional, padrão: true
})
new Vue({
render: h => h(App)
}).$mount('#app')
```
### Configuração via CDN
```html
```
## 🚀 Uso Básico
### Configuração Automática (Recomendado)
Após instalar o plugin, um botão flutuante aparecerá automaticamente no canto inferior direito da página. Os usuários podem clicar nele para abrir o formulário de criação de tickets.
### Uso Manual dos Componentes
```vue
```
## 🧩 Componentes Disponíveis
### TicketWidget
Componente principal que exibe o formulário de criação de tickets em um modal.
**Props:**
- `apiUrl` (String): URL da API do Deep Service Desk
- `clientUuid` (String): UUID do cliente (obrigatório)
**Eventos:**
- `@ticket-created`: Emitido quando um ticket é criado com sucesso
- `@ticket-error`: Emitido quando ocorre um erro na criação
### FloatingTicketWidget
Componente que gerencia o widget de ticket de forma invisível, usado internamente pelo botão flutuante.
## 🔧 API e Métodos
### Métodos Globais
Após instalar o plugin, os seguintes métodos ficam disponíveis:
```javascript
// Vue 3
this.$deepServiceDeskButton.showFloatingButton()
this.$deepServiceDeskButton.hideFloatingButton()
this.$deepServiceDeskButton.openTicket()
// Vue 2
this.$deepServiceDeskButton.showFloatingButton()
this.$deepServiceDeskButton.hideFloatingButton()
this.$deepServiceDeskButton.openTicket()
```
### Configuração Global
```javascript
// Acessar configuração global
console.log(this.$deepServiceDesk)
// Vue 3 - via inject
export default {
inject: ['deepServiceDeskConfig'],
mounted() {
console.log(this.deepServiceDeskConfig)
}
}
```
## 📡 Eventos
### Eventos do Window
O widget emite eventos globais que podem ser escutados:
```javascript
// Evento disparado quando um ticket é criado
window.addEventListener('ticket-created', (event) => {
console.log('Ticket criado:', event.detail)
})
// Evento disparado quando ocorre erro
window.addEventListener('ticket-error', (event) => {
console.log('Erro:', event.detail)
})
// Evento para abrir o widget programaticamente
window.dispatchEvent(new CustomEvent('new-ticket'))
```
## 🎨 Personalização
### Variáveis de Ambiente
O widget suporta configuração via variáveis de ambiente:
```bash
# .env
VITE_API_URL=https://sua-api.com/api
VITE_CLIENT_UUID=seu-client-uuid-aqui
# Para Vue CLI
VUE_APP_API_URL=https://sua-api.com/api
VUE_APP_CLIENT_UUID=seu-client-uuid-aqui
```
### Configuração via Window
```javascript
// Definir configurações globais
window.DEEP_SERVICE_DESK_API_URL = 'https://sua-api.com/api'
window.DEEP_SERVICE_DESK_CLIENT_UUID = 'seu-client-uuid-aqui'
```
### Estilos CSS
O widget inclui estilos padrão, mas você pode personalizá-los:
```css
/* Personalizar o botão flutuante */
#deep-service-desk-floating-btn {
background: linear-gradient(135deg, #your-color 0%, #your-color-2 100%) !important;
bottom: 30px !important;
right: 30px !important;
}
/* Personalizar o modal */
.popup-overlay {
background-color: rgba(0, 0, 0, 0.8) !important;
}
.popup-content {
border-radius: 12px !important;
box-shadow: 0 20px 40px rgba(0, 0, 0, 0.3) !important;
}
```
## 📚 Exemplos
### Exemplo Completo - Vue 3
```vue
Minha Aplicação
```
### Exemplo com Configuração Dinâmica
```vue
```
### Exemplo sem Vue (HTML Puro)
```html
Widget sem Vue
Minha Página
```
## 🔍 Troubleshooting
### Problemas Comuns
#### 1. "clientUuid é obrigatório"
**Erro:** `Deep Service Desk Widget: clientUuid é obrigatório na configuração`
**Solução:** Certifique-se de fornecer o `clientUuid` na configuração:
```javascript
app.use(DeepServiceDeskPlugin, {
clientUuid: 'seu-client-uuid-aqui' // OBRIGATÓRIO
})
```
#### 2. Botão flutuante não aparece
**Possíveis causas:**
- `showFloatingButton` está definido como `false`
- Erro de JavaScript impedindo a inicialização
- Conflito de CSS
**Solução:**
```javascript
// Verificar configuração
console.log(this.$deepServiceDesk)
// Mostrar botão manualmente
this.$deepServiceDeskButton.showFloatingButton()
```
#### 3. Formulário não envia
**Possíveis causas:**
- URL da API incorreta
- Problemas de CORS
- Cliente UUID inválido
**Solução:**
```javascript
// Verificar configuração
console.log('API URL:', this.$deepServiceDesk.apiUrl)
console.log('Client UUID:', this.$deepServiceDesk.clientUuid)
// Verificar console do navegador para erros de rede
```
#### 4. Incompatibilidade com Vue 2
**Erro:** Plugin não funciona com Vue 2
**Solução:** Certifique-se de usar Vue 2.7.16 ou superior:
```bash
npm install vue@^2.7.16
```
### Debug
Para ativar logs detalhados, abra o console do navegador. O widget emite logs informativos que ajudam no debug:
```javascript
// Logs do widget começam com emojis:
// 🚀 Instalação do plugin
// 🔧 Configuração
// ✅ Sucesso
// ⚠️ Avisos
// ❌ Erros
```
## 📄 Licença
MIT License - veja o arquivo LICENSE para detalhes.
## 🤝 Contribuição
Contribuições são bem-vindas! Por favor, abra uma issue ou pull request no repositório.
## 📞 Suporte
Para suporte técnico, abra uma issue no [repositório GitHub](https://github.com/pedrohrs/deep-service-desk-widget/issues).