# API di LinkedIn e assistenti AI (MCP)

Tutto ciò che fai sulle pagine di LinkedIn può essere eseguito anche da uno script o da un assistente AI: i tuoi lead, la coda delle richieste di collegamento, le tue regole ICP (inclusi i paesi che accetti e quanto deve essere grande la rete di un lead), la tua posta in arrivo, i tuoi agenti AI e le tue impostazioni.

Non c'è nulla di nuovo da configurare. Utilizza la **stessa chiave API del resto di <span data-t="appName">DM Champ</span>**, quindi se chiami già la nostra API o hai un assistente AI connesso, sei pronto.

## Dove trovare la tua chiave

Impostazioni → Integrazioni → Chiave API. Se non ne hai ancora una, fai clic su **Genera chiave API**. I passaggi completi sono disponibili in [Accesso API](api-access.md).

Non esiste una chiave LinkedIn separata da creare, ruotare o revocare. La chiave agisce come te, con le stesse autorizzazioni che hai nell'app, quindi trattala come una password. Revocarla nelle Impostazioni interrompe istantaneamente ogni script e assistente connesso.

## Chiamare l'API direttamente

- **URL di base:** `https://app.sdrpilot.ai/api/v1`
- **Intestazione:** `X-API-Key: YOUR_API_KEY`
- **Descrizione leggibile dalla macchina:** `https://app.sdrpilot.ai/api/v1/docs/openapi.yaml`
  (disponibile anche come `.json`)

Il documento OpenAPI è pubblico e descrive ogni percorso, quindi la maggior parte degli strumenti API e dei generatori di codice può importarlo direttamente senza una chiave.

Anche `Authorization: Bearer YOUR_API_KEY` funziona. Ciò che non puoi fare è inviare una chiave errata sperando che venga accettata per qualcos'altro: una volta presentata una chiave, la risposta si basa su quella chiave.

Cosa viene restituito quando qualcosa non va:

| Risposta | Cosa significa |
|---|---|
| `401` | La chiave manca, è malformata o non è accettata. |
| `403` | La chiave è valida, ma quell'account non ha uno spazio di lavoro LinkedIn o non è ancora autorizzato. |
| `429` | Troppi tentativi rifiutati in un minuto per quella chiave. Rallenta. |
| `502` `dmchamp_unreachable` | Non siamo riusciti a verificare la tua chiave in quel momento. Non viene mai trattata come un accesso consentito. Riprova. |

## Connettere un assistente AI

Gli strumenti di LinkedIn risiedono sullo stesso endpoint MCP di <span data-t="appName">DM Champ</span>, con la stessa chiave API, quindi un assistente che hai già connesso li rileva automaticamente. Se non ne hai ancora connesso uno, segui [Connetti assistenti AI (MCP)](connect-ai-clients.md) e utilizza l'endpoint ivi elencato.

::: master-only
L'endpoint è `https://mcp.youraiconnector.com/mcp`, autenticato con l'intestazione `X-API-Key`, esattamente come descritto in Connetti assistenti AI (MCP).
:::

Gli strumenti LinkedIn hanno tutti il prefisso **`linkedin_`**, quindi sono facili da individuare nell'elenco degli strumenti del tuo assistente e facili da richiedere per nome ("usa gli strumenti LinkedIn per mostrarmi cosa c'è in coda"). Non ci sono autorizzazioni per singolo strumento: uno strumento può fare tutto ciò che puoi fare tu nell'app.

## Esempio 1 — accetta lead solo da determinati paesi

Il tuo profilo ICP contiene le regole che i lead devono superare. Questo imposta una lista consentita per Paesi Bassi e Belgio. I codici paese sono di due lettere, in maiuscolo.

```bash
curl -X PUT https://app.sdrpilot.ai/api/v1/icp/YOUR_ICP_ID/filters \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"countries":{"mode":"allow","codes":["NL","BE"]}}'
```

Due cose da sapere. Il corpo è l'insieme **completo** di regole, non una patch: una regola che ometti viene disattivata. E la risposta include un blocco `impact_on_queue` che ti dice quante richieste di connessione già in coda non supererebbero le nuove regole, ad esempio `{"examined": 389, "would_withdraw": 155}`.
Salvare le regole non ritira nulla di per sé.

In un assistente diresti semplicemente: "Imposta il mio ICP per accettare solo Paesi Bassi e Belgio e dimmi cosa comporterebbe per la mia coda."

## Esempio 2 — vedere cosa c'è in coda

Richieste di connessione che sono state approvate ma non ancora inviate:

```bash
curl -s "https://app.sdrpilot.ai/api/v1/connections/queue?status=queued&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"
```

Ogni riga riporta il nome della persona, il titolo, l'azienda, la posizione, il paese, il numero di collegamenti e follower e il punteggio. Puoi restringere l'elenco con `country`, `min_score`, `max_score` e `source` e scorrere le pagine con `limit` e `cursor`. Qui appaiono solo le richieste in coda e in attesa di approvazione. Le richieste già inviate sono cronologia e non possono essere modificate.

## Esempio 3 — ritirare tutti coloro che si trovano al di fuori dei tuoi paesi

Dopo aver modificato le regole, ricontrolla la coda in base ad esse. Senza `apply=true` questa è un'anteprima e non cambia nulla:

```bash
curl -X POST "https://app.sdrpilot.ai/api/v1/connections/queue/rescreen" \
  -H "X-API-Key: YOUR_API_KEY"
```

Riceverai informazioni su quanti sono stati esaminati, quanti verrebbero ritirati e una suddivisione per regola, come `country` e `network_too_small` (la rete del lead era più piccola del tuo minimo). Soddisfatto? Eseguilo di nuovo con `?apply=true` e quelle richieste verranno ritirate.

```bash
curl -X POST "https://app.sdrpilot.ai/api/v1/connections/queue/rescreen?apply=true" \
  -H "X-API-Key: YOUR_API_KEY"
```

Se preferisci ritirare un set specifico, pubblica invece gli ID o un filtro come `{"filter":{"status":"queued","country":"NG"}}` per svuotare tutto ciò che corrisponde. Invia ID o un filtro, non entrambi.

## Risoluzione dei problemi

- **`401` su ogni chiamata** — la chiave manca o è errata. Copiala di nuovo da Impostazioni → Integrazioni → Chiave API.
- **`403` anche se la chiave funziona altrove** — quell'account non è collegato a uno spazio di lavoro LinkedIn, o LinkedIn non è ancora abilitato per esso.
- **`502 dmchamp_unreachable`** — un intoppo temporaneo durante il controllo della chiave. Nulla è stato lasciato passare; riprova.
- **Una regola non corrisponde a nulla** — i codici paese devono essere nel formato a due lettere maiuscole (`NL`, non `Netherlands` o `nl`), e i codici lingua devono essere in minuscolo.
- **L'assistente non mostra strumenti LinkedIn** — riconnettilo in modo che ricarichi l'elenco degli strumenti e controlla che tu stia utilizzando la stessa chiave API.

---

## Prossimi passi

- [Connetti assistenti AI (MCP)](connect-ai-clients.md) — configura Claude, ChatGPT o Cursor con la tua chiave.
- [Accesso API](api-access.md) — genera o ruota la chiave utilizzata da questo.