# Casi di attivazione dei tuoi clienti e «Gestito»

`GET /v1/onboarding-cases`

Quando un cliente di uno dei tuoi link si blocca e scrive nella schermata di attivazione, nasce un **caso** (`A-<n>`, lo stesso `data.caseId` di `onboarding.help_requested`). Contiene ciò che ha scritto così com'è, il codice di Meta, la diagnosi (dal catalogo o con IA, con la sua affidabilità) e se ha caricato uno screenshot.

**Elencarli.** `GET /v1/onboarding-cases?status=open` (predefinito), `acked` o `all`; il più recente per primo.

**Segnarlo gestito.** `POST /v1/onboarding-cases/{id}/ack`, quando l'hai risolto. È idempotente. Una consegna 2xx del webhook **non** conta come gestito.

**Nel pannello.** **Attivazioni dei tuoi clienti** (compare nel menu quando hai creato link): una riga per link con il suo stato (in attesa, non riuscita, collegato, scaduto), i tentativi, l'ultimo motivo, la diagnosi, il testo e lo screenshot, il pulsante «Gestito» e, se è scaduto, «Genera un nuovo link». Filtri: Da gestire (predefinito), Tutte, Collegate.

## Esempi

### cURL

```bash
# 1) the open cases (default status=open; also acked | all)
curl "https://api.waiaconnect.com/v1/onboarding-cases?status=open" -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# → { "cases": [ { "id": "A-41", "status": "open", "externalId": "pharmacy-42",
#       "clientText": "…", "metaErrorCode": 3441060, "diagnosis": { "title": "…", "responsible": "client", … } } ] }

# 2) once you sorted it out: mark it handled (idempotent)
curl -X POST https://api.waiaconnect.com/v1/onboarding-cases/A-41/ack -H "Authorization: Bearer wc_live_YOUR_API_KEY"
```

### Node.js

```javascript
const H = { "Authorization": "Bearer wc_live_YOUR_API_KEY" };
const { cases } = await (await fetch("https://api.waiaconnect.com/v1/onboarding-cases?status=open", { headers: H })).json();
for (const c of cases) {
  console.log(c.id, c.externalId, c.diagnosis?.title, c.clientText);
  // … after you helped your customer:
  await fetch(`https://api.waiaconnect.com/v1/onboarding-cases/${c.id}/ack`, { method: "POST", headers: H });
}
```

### PHP

```php
<?php
$h = ["Authorization: Bearer wc_live_YOUR_API_KEY"];
$ch = curl_init("https://api.waiaconnect.com/v1/onboarding-cases?status=open");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $h]);
$cases = json_decode(curl_exec($ch), true)["cases"];
foreach ($cases as $c) {
  $ack = curl_init("https://api.waiaconnect.com/v1/onboarding-cases/" . $c["id"] . "/ack");
  curl_setopt_array($ack, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => $h]);
  curl_exec($ack);
}
```

### Python

```python
import requests
H = {"Authorization": "Bearer wc_live_YOUR_API_KEY"}
cases = requests.get("https://api.waiaconnect.com/v1/onboarding-cases", headers=H, params={"status": "open"}).json()["cases"]
for c in cases:
    print(c["id"], c["externalId"], (c["diagnosis"] or {}).get("title"), c["clientText"])
    requests.post(f"https://api.waiaconnect.com/v1/onboarding-cases/{c['id']}/ack", headers=H)  # after you helped them
```

## Note

- Un caso di un altro account restituisce lo stesso `404 ONBOARDING_CASE_NOT_FOUND` di uno che non esiste.
- Uno `status` diverso da `open`, `acked` o `all` restituisce `400 ONBOARDING_CASE_STATUS_INVALID`.
- `?lang=es|en|pt|it` sceglie la lingua della diagnosi dal catalogo (predefinita: quella del link).