# Contrato — Mapeamento IDs: Portal ↔ Desk ↔ FOSS

**Spec:** [044](../spec.md)  
**Versão:** 1.0 · 2026-07-01 · Roger  
**Status:** Fonte única para correlação de tickets  

---

## 1. Identificadores

| Campo | Formato | Sistema dono | Persistência Desk |
|-------|---------|--------------|-------------------|
| `wizard_ticket_id` | `OB-[A-F0-9]{8}` | VM112 portal | `tickets.payload.wizard_ticket_id` |
| `desk_ticket_id` | inteiro `#N` | VM122 Desk | `tickets.id` |
| `foss_ticket_id` | inteiro FOSS | VM123 FOSS | `tickets.payload.foss_ticket_id` |
| `external_customer_id` | inteiro FOSS client | VM123 FOSS | `billing_accounts.external_customer_id` |
| `session_id` | UUID wizard | VM112 | `tickets.session_id` |
| `domain` | FQDN | — | `tickets.payload.domain` |

---

## 2. Chaves de idempotência

| Operação | Chave única | Comportamento se duplicado |
|----------|-------------|----------------------------|
| Portal → Desk | `event + session_id + domain` | Actualizar ticket existente (Spec 001 FR-012) |
| Desk → FOSS espelho | `desk_ticket_id` | Retornar `foss_ticket_id` existente |
| FOSS → Desk webhook | `foss_ticket_id + event_type` | Append nota, não criar ticket novo |
| Cliente FOSS novo | `foss_ticket_id` | Lookup Desk; criar só se ausente |

---

## 3. Mapa de estados

| Desk `status` | Portal OB- `status` | FOSS Support |
|---------------|---------------------|--------------|
| `open` | `open` | `open` |
| `escalated` | `in_review` | `open` |
| `assisting` | `in_progress` | `on hold` |
| `resolved` | `resolved` | `closed` (resolvido) |
| `closed` | `closed` | `closed` |

**Regra:** Desk é master para ops; FOSS é master para visibilidade cliente billing.

---

## 4. Payload Desk (`tickets.payload` — extensão Spec 044)

```json
{
  "event": "onboarding.escalated",
  "domain": "empresa.com.br",
  "session_id": "331b4022-70a5-4a9d-ba3e-08aaa06cb4f4",
  "data": {
    "wizard_ticket_id": "OB-D424843A",
    "client_note": "DNS não propaga",
    "reason": "client_support_request"
  },
  "foss_sync": {
    "foss_ticket_id": 42,
    "external_customer_id": 17,
    "synced_at": "2026-07-01T18:00:00Z",
    "last_foss_event": "ticket.reply",
    "foss_url": "https://financeiro.ligbox.com.br/admin/support/ticket/42"
  }
}
```

---

## 5. Pré-requisitos para espelho FOSS

| Condição | Obrigatório |
|----------|-------------|
| `billing_accounts.external_customer_id` | Sim (Spec 043) |
| Ticket Desk com `domain` | Sim |
| Role staff a criar espelho | `sales_admin`, `sales_support`, `technician`, `ops_lead` |
| Onboarding puro (sem FOSS client) | Espelho **adiado** até Activar conta |

---

## 6. URLs deep-link

| Destino | URL |
|---------|-----|
| Desk ticket | `https://desk.ligbox.com.br/#ticket/{desk_ticket_id}` |
| Portal OB- tracking | `https://onboard.ligbox.com.br/onboard?session={session_id}&ticket={wizard_ticket_id}` |
| FOSS admin ticket | `https://financeiro.ligbox.com.br/admin/support/ticket/{foss_ticket_id}` |
| FOSS client ticket | `https://financeiro.ligbox.com.br/support/ticket/{foss_ticket_id}` |

---

## Histórico

| Versão | Data | Autor | Notas |
|--------|------|-------|-------|
| 1.0 | 2026-07-01 | Roger / Cursor | Documento inicial Spec 044 |