> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syrto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contatti persona

> Leggi gli indirizzi email di lavoro e i numeri di telefono diretti disponibili per una persona, e acquistali quando non sono ancora posseduti.

Syrto può acquistare da fornitori di dati esterni gli indirizzi email di lavoro e i numeri di telefono diretti di una persona. Non fanno parte delle risultanze camerali, e per questo costano crediti.

Se ne occupano due strumenti:

| Strumento                       | Costa crediti | Che cosa fa                                                                                                          |
| ------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `syrto_get_person_contacts`     | No            | Che cosa ha trovato la ricerca del fornitore, quanto costerebbe acquistarlo e che cosa l'organizzazione possiede già |
| `syrto_request_person_contacts` | **Sì**        | Acquista i contatti                                                                                                  |

Gli ID persona provengono da [`syrto_find_person`](/it/mcp/tools/find-person), oppure dal `person_id` di un amministratore, azionista o titolare effettivo restituito da [`syrto_get_company_structure`](/it/mcp/tools/company-structure). La seconda via è la più precisa: `syrto_find_person` è una ricerca per nome, quindi può finire su un omonimo.

<Warning>
  I contatti acquistati appartengono all'**intera organizzazione**, non a chi li ha comprati. Un collega potrebbe averli già pagati: `syrto_get_person_contacts` è il modo per scoprirlo, e non costa crediti.
</Warning>

***

## `syrto_get_person_contacts`

Riporta i contatti disponibili per una persona e il costo per acquistarli. Non spende crediti contatto ed è sicuro da chiamare ripetutamente.

Usalo:

* **Prima di ogni acquisto.** Fornisce il costo da confermare con l'utente e indica se per questa persona si possa trovare qualcosa.
* **Per leggere contatti già acquistati.**
* **Per raccogliere dati ancora in arrivo.** I fornitori restituiscono prima le email e poi i numeri di telefono, quindi i contatti con stato `IN_PROGRESS` restano incompleti per un breve periodo. Richiamare questo strumento è il modo per ottenere il resto - acquistare di nuovo significherebbe pagarlo due volte.

### Argomenti

<ParamField query="person_id" type="string" required>
  L'ID della persona, da [`syrto_find_person`](/it/mcp/tools/find-person) o da un `person_id` in [`syrto_get_company_structure`](/it/mcp/tools/company-structure).
</ParamField>

<ParamField query="language" type="string">
  `"en"` per inglese (predefinito) o `"it"` per italiano.
</ParamField>

### Risposta

<ResponseField name="person" type="object">
  `id` (il `person_id` che hai passato) e `name`.
</ResponseField>

<ResponseField name="availability" type="object">
  Che cosa **si può** acquistare, non che cosa è già posseduto:

  * `has_email` - è possibile trovare un indirizzo email
  * `has_direct_phone` - è possibile trovare un numero di telefono diretto
  * `credit_cost` - quanto costerebbe acquistarlo

  Entrambi i flag `false` significa che per questa persona non si può trovare nulla, a nessun prezzo.
</ResponseField>

<ResponseField name="contacts" type="object | null">
  Ciò che l'organizzazione ha già acquistato:

  * `status` - `COMPLETED`, oppure `IN_PROGRESS` mentre altro è ancora in arrivo
  * `emails` - lista di indirizzi email
  * `phone_numbers` - lista di numeri di telefono

  Interamente omesso quando nessuno li ha ancora acquistati.
</ResponseField>

<ResponseField name="credit_balance" type="object | null">
  Crediti `available` e `reserved` dell'organizzazione. Omesso quando la credenziale non ha un'organizzazione per cui l'API possa risolvere i crediti.
</ResponseField>

***

## `syrto_request_person_contacts`

Acquista i contatti di una persona. **Questo spende i crediti dell'organizzazione.**

### Prima di acquistare

1. Chiama `syrto_get_person_contacts` per il `credit_cost` esatto, e per verificare che per questa persona si possa trovare qualcosa.
2. Comunica all'utente di chi sono i contatti e quanto costano, e ottieni il suo consenso esplicito a spenderli.
3. Passa quel costo come `expected_credit_cost`. L'acquisto viene rifiutato se il prezzo corrente è diverso, il che intercetta un prezzo ormai vecchio - non attesta che qualcuno lo abbia approvato, quindi il passo 2 resta indispensabile.

<Warning>
  I controlli su duplicati e prezzo vengono eseguiti immediatamente prima dell'acquisto, non in modo atomico con esso. L'API a monte non accetta un tetto di prezzo, quindi un prezzo che cambia tra il controllo e l'acquisto viene addebitato alla nuova cifra.
</Warning>

### Quando una ripetizione non costa nulla

Due meccanismi indipendenti determinano se una ripetizione viene addebitata:

* L'API a monte deduplica un'intenzione di acquisto già inviata - stessa persona e stesso `force_new` - per **24 ore**, restituendo il primo acquisto invece di addebitare di nuovo.
* Separatamente, questo strumento rifiuta i contatti che l'organizzazione già possiede, che quella finestra sia trascorsa o meno, **a meno che** `force_new` non sia `true`.

Quindi una ripetizione semplice resta protetta anche dopo 24 ore dalla seconda regola, mentre la ripetizione di un'intenzione che già portava `force_new: true` è protetta solo dalla prima, e acquista di nuovo una volta trascorsa la finestra.

Non usare questo strumento per raccogliere contatti ancora in arrivo. I fornitori restituiscono prima le email e poi i numeri di telefono, e `syrto_get_person_contacts` restituisce il resto senza costi una volta che è arrivato.

Se la chiamata va in timeout o fallisce, richiamala con la stessa intenzione di acquisto - stessa persona e stesso `force_new`. Aggiungere `force_new` la rende un acquisto diverso, addebitato per intero. `expected_credit_cost` e `language` non fanno parte dell'intenzione.

### Argomenti

<ParamField query="person_id" type="string" required>
  La persona di cui acquistare i contatti.
</ParamField>

<ParamField query="expected_credit_cost" type="integer" required>
  Il `credit_cost` da `syrto_get_person_contacts`, come mostrato all'utente.
</ParamField>

<ParamField query="force_new" type="boolean">
  Esegue una nuova ricerca presso il fornitore per una persona i cui contatti l'organizzazione possiede già. Addebita l'intero costo. Predefinito `false`. Non serve per raccogliere dati in corso di arrivo - quelli sono gratuiti tramite `syrto_get_person_contacts`.
</ParamField>

<ParamField query="language" type="string">
  `"en"` per inglese (predefinito) o `"it"` per italiano.
</ParamField>

### Risposta

<ResponseField name="person" type="object">
  `id` e `name`.
</ResponseField>

<ResponseField name="contacts" type="object | null">
  `status` (`COMPLETED`, oppure `IN_PROGRESS` mentre altro è in arrivo), `emails` e `phone_numbers`. Omesso quando il fornitore non ha trovato nulla.
</ResponseField>

<ResponseField name="credit_cost" type="integer">
  Il prezzo quotato per questo arricchimento, non un addebito confermato - l'API a monte non riporta quanto ha addebitato.

  `0` è l'eccezione ed è certo: un arricchimento che non trova nulla non viene addebitato affatto. Anche un valore positivo può non essere addebitato, se questa chiamata ha ripetuto un acquisto `force_new` identico entro 24 ore - cosa che viene replicata a monte e non è rilevabile qui.
</ResponseField>

<Note>
  Il fornitore può non trovare nulla. È una chiamata riuscita e non fatturata: torna senza contatti e con un `warning` che lo segnala. Significa "non è stato possibile trovare contatti", non è un errore, e ritentare non cambia il risultato.
</Note>

## Esempio

**1. Verificare che cosa è disponibile e quanto costa (gratuito):**

```json theme={null}
{
  "person_id": "cDpJVF9SU1NNUkE4MEEwMUY4MzlY"
}
```

**2. Acquistare, dopo che l'utente ha accettato il costo:**

```json theme={null}
{
  "person_id": "cDpJVF9SU1NNUkE4MEEwMUY4MzlY",
  "expected_credit_cost": 3
}
```