# Spec 044 — Sincronização Tickets: Portal ↔ Desk ↔ FOSS

**Criado:** 2026-07-01  
**Solicitado por:** Roger  
**Status:** 📋 **Especificado — implementação pendente**  
**Prioridade:** P1 (suporte unificado pós-activação)  
**Sistemas:** VM112 Portal · VM122 Desk · VM123 FOSSBilling  

---

## Resumo

Hoje existem **três filas de tickets isoladas**:

| Sistema | ID | Estado |
|---------|-----|--------|
| Portal wizard (VM112) | `OB-XXXXXXXX` | ✅ Activo — JSON local + portal cliente |
| Desk Ops (VM122) | `#N` / `CH-*` | ✅ Activo — webhook VM112 |
| FOSS Support (VM123) | `foss_ticket_id` | ❌ **Sem sync** com portal/Desk |

Esta spec define a **ponte bidireccional** Desk ↔ FOSS, preservando o portal wizard como canal de entrada do cliente e o Desk como **fonte de verdade operacional**.

**Contratos:**
- [ticket-field-mapping.md](./contracts/ticket-field-mapping.md) — chaves de correlação
- [ticket-sync-api.md](./contracts/ticket-sync-api.md) — webhooks e endpoints API

**Chat bruto:** [CHAT_BRUTO_WEBMAIL_GATE_TICKETS_SPEC043_044_20260701.txt](../../chat-bruto/CHAT_BRUTO_WEBMAIL_GATE_TICKETS_SPEC043_044_20260701.txt)

---

## Specs relacionadas

| Spec | Relação |
|------|---------|
| [001](../001-webhook-vm112-integration/spec.md) | Webhooks VM112 → Desk (base) |
| [010](../010-desk-assist-takeover/spec.md) | Escalada, ASM, `onboarding.escalated` |
| [012](../012-abandoned-onboarding-lead/spec.md) | Ticket único por jornada onboarding |
| [024](../024-openpanel-fossbilling/spec.md) | FOSS VM123, módulo Support |
| [027](../027-desk-rbac-function-matrix/contracts/vm123-product-roles.md) | `support` FOSS, roles comercial |
| [039](../039-ligbox-ops-authorization-catalog/spec.md) | `vm123_foss.support.ticket` |
| [041](../041-desk-operational-feed/spec.md) | Central Operacional — canal Tickets |
| [043](../043-desk-client-activation-sync/spec.md) | `external_customer_id` FOSS pós-activação |

---

## Arquitectura alvo

```
┌─────────────────────────────────────────────────────────────────────────┐
│ VM112 — Portal (onboard.ligbox.com.br)                                   │
│  OB-* tickets · POST /api/onboarding/support/ticket                      │
│  Cliente acompanha: GET .../support/ticket/{OB-}/public                  │
└───────────────────────────────┬─────────────────────────────────────────┘
                                │ webhook onboarding.escalated (+ started)
                                ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ VM122 — Desk (fonte de verdade ops)                                      │
│  tickets.payload: wizard_ticket_id, foss_ticket_id, external_customer_id│
│  Staff: Chamados · Serviços · Central Operacional (041)                  │
└───────────────┬───────────────────────────────┬─────────────────────────┘
                │ POST espelho (M2M)             │ webhook FOSS → Desk
                ▼                                ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ VM123 — FOSSBilling Support                                              │
│  Cliente: financeiro.ligbox.com.br/support                               │
│  Staff: /admin/support · API /api/admin/support/*                        │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## Regras de negócio

1. **Um incidente = um ticket Desk** — nunca duplicar `#N` para a mesma `session_id` ou `foss_ticket_id`.
2. **Portal OB-** continua a existir para onboarding; Desk grava `wizard_ticket_id` no payload (já parcialmente implementado na UI).
3. **FOSS espelho** só após `external_customer_id` conhecido (Spec 043) — tickets de onboarding pré-FOSS ficam só Desk + OB-.
4. **Sync bidireccional de estado:** `open` ↔ `in_progress` ↔ `resolved` ↔ `closed` (mapa em contrato).
5. **Cliente pós-activação** pode abrir ticket no FOSS client area **ou** no portal/console Ligbox; ambos convergem no Desk.

---

## Fases de implementação

| Fase | Entrega | VM |
|------|---------|-----|
| **A** | Documentação + contratos (esta spec) | CT130 |
| **B** | `foss_client.create_support_ticket()` + espelho Desk→FOSS | VM122 |
| **C** | Webhook FOSS → Desk (`POST /api/v1/webhooks/foss/support`) | VM122 + VM123 |
| **D** | UI Desk: link FOSS ticket + badge sync | VM122 |
| **E** | Portal pós-activação: criar via Desk API (propaga FOSS) | VM112 / Console |

Ver [tasks.md](./tasks.md).

---

## Fora de escopo (v1)

- OTRS (→ Spec 011)
- Sync automático e-mail inbound (→ Spec 041 fase B)
- Tickets Odoo Helpdesk

---

## Validação Roger

```bash
# 1) Cliente abre OB- no wizard → Desk #N com wizard_ticket_id
# 2) Activar conta (Spec 043) → external_customer_id preenchido
# 3) Staff responde no Desk → foss_ticket_id criado no FOSS
# 4) Cliente responde no FOSS → webhook actualiza nota no Desk #N
```