# Collegare Integrately a GenderAPI.io V2

> Collega Integrately a GenderAPI.io V2 per i record di Mailchimp. Scegli il connettore giusto, invia type e value e poi gestisci data, meta, crediti ed errori.

Canonical HTML: https://www.genderapi.io/it/blog/integrately-gender-api-integration

Last reviewed: 2026-09-28

## Scegli la connessione Integrately adatta al tuo contratto API

La ricetta HTTP di questa guida chiama GenderAPI.io V2 su https://api.genderapi.io/api/v2/gender. Invia type e value nel corpo JSON; la previsione si legge in data, mentre i dati della richiesta e dell'addebito si trovano in meta. I connettori nativi hanno contratti propri, descritti qui sotto.

La pagina GenderAPI.io su Integrately rimanda a genderapi.io e offre azioni per nomi, indirizzi email e per estrarre il nome da un indirizzo email. Non indica né la versione dell'API sottostante né lo schema completo dell'output; i nomi delle azioni non bastano da soli a confermare la compatibilità con V2.

Integrately documenta Webhook/API come azione POST in uscita. I suoi attuali controlli per le intestazioni e l'editor JSON non sono stati verificati in modo indipendente per questa guida. Applica il contratto HTTP V2 qui sotto solo dopo aver confermato che la tua azione può inviare un'intestazione Authorization e un corpo JSON annidato. Le azioni native esistenti mantengono il proprio contratto dei campi.

- [Pagina GenderAPI.io su Integrately](https://integrately.com/integrations/genderapi-io)
- [Documentazione V1 esistente](https://www.genderapi.io/it/api-documentation/v1)

## Prepara l'account e il record di origine

Questo esempio arricchisce i record di Mailchimp a partire dal nome. Ti servono l'accesso all'applicazione di origine e a quella di destinazione, una chiave dell'account GenderAPI.io e le funzioni della piattaforma usate dall'azione HTTP. Questa guida non contiene credenziali funzionanti né account collegati.

V1 e V2 usano la stessa chiave dell'account e lo stesso saldo. Prima di configurare una richiesta a pagamento, verifica la chiave con GET /api/v2/usage e controlla che nella risposta di questo endpoint meta.access.mode abbia il valore api_key. Una chiave mancante o non riconosciuta può far passare alla prova IP condivisa; un'automazione in produzione non dovrebbe dipenderne a tua insaputa.

Tieni il flusso di lavoro disattivato mentre lo configuri. Una previsione di prova consuma crediti normali. Queste guide sono state verificate sulla documentazione pubblica e sul contratto V2; per questa pubblicazione non è stato eseguito da inizio a fine alcun flusso di lavoro autenticato su nessuna piattaforma.

- [Autenticazione e controllo gratuito dell'utilizzo](https://www.genderapi.io/it/docs/v2/authentication#environment-setup)

## Configura la richiesta GenderAPI.io V2 in Integrately

- Scegli un trigger Mailchimp per gli iscritti e verifica un record di prova. Salva l'ID del pubblico (Audience) e dell'iscritto per l'aggiornamento, scegli il campo effettivo del nome e salta i record senza nome.
- Individua Webhook/API e l'azione corrispondente per inviare dati a un URL. Verifica la configurazione disponibile prima di proseguire: il contratto qui sotto richiede intestazioni autenticate e un corpo JSON annidato, e i controlli attuali dell'editor non sono stati verificati qui in modo indipendente.
- Se l'azione soddisfa questi requisiti, scegli POST e l'endpoint V2 qui sotto. Con i controlli disponibili nel tuo account assicurati che la richiesta in uscita contenga Authorization: Bearer YOUR_API_KEY e Content-Type: application/json.
- Crea un corpo JSON con type = name, value = nome mappato e options con ai_mode = off. Controlla l'anteprima della richiesta per l'azione scelta: un payload di modulo piatto non è un corpo JSON V2, anche se l'intestazione Content-Type è impostata.
- Per nomi dinamici usa i controlli di mappatura o di serializzazione JSON della piattaforma. Se l'azione scelta non può mantenere JSON annidato o intestazioni autenticate, usa un passaggio con supporto HTTP invece di scrivere la chiave o il JSON nei parametri di query.

| Impostazione HTTP | Valore | Scopo |
| --- | --- | --- |
| `Method` | `POST` | Invia una singola richiesta di previsione. |
| `URL` | `https://api.genderapi.io/api/v2/gender` | Endpoint V2 di GenderAPI.io per le previsioni singole. |
| `Authorization` | `Bearer YOUR_API_KEY` | Sostituisci il segnaposto tramite le impostazioni di autenticazione o delle intestazioni della piattaforma. |
| `Content-Type` | `application/json` | Invia un oggetto con un oggetto options annidato, non campi di un modulo. |
| `options.ai_mode` | `off` | Primo test deliberato solo con il set di dati: addebito normale di 1 credito, anche se il risultato è unknown. |

## Controlla il corpo JSON prima dell'invio

Questo esempio mostra un input fisso; non è un risultato previsto. Verifica prima la struttura della richiesta, poi sostituisci value con il campo di origine mappato, usando una serializzazione JSON corretta. Non inviare all'API le espressioni di mappatura della piattaforma come testo letterale.

Per altri input imposta type su name, email o username e indica il valore corrispondente in value. Aggiungi country solo se disponi di un contesto affidabile: il campo è facoltativo e non serve a stabilire il paese di residenza.

**Richiesta JSON V2 per Integrately**

```json
{
  "type": "name",
  "value": "Alice",
  "options": {
    "ai_mode": "off"
  }
}
```

- [Campi, tipi e valori predefiniti della richiesta](https://www.genderapi.io/it/docs/v2/request-parameters)

## Verifica il passaggio HTTP prima di attivare gli aggiornamenti

Prova un'azione in modo circoscritto ed esamina il corpo restituito prima di scegliere i campi nei passaggi successivi. I passaggi nativi GenderAPI.io e i passaggi Webhook/API possono mostrare etichette dei campi diverse, anche per lo stesso cliente di origine.

Conserva la chiave nei controlli previsti per la connessione o per l'autenticazione della richiesta e limita le persone che possono vedere o condividere l'automazione. Questa guida pubblica non contiene né una chiave funzionante né una connessione esportata né un aggiornamento dei clienti preconfigurato.

- [Azioni Webhook/API in Integrately](https://integrately.com/integrations/webhook-api)
- [Documentazione di Integrately](https://integrately.com/docs)

## Gestisci separatamente i risultati identified, unknown e gli errori

Analizza il corpo della risposta prima di scegliere un aggiornamento nel sistema di destinazione. I percorsi JSON qui sotto si riferiscono al corpo della risposta V2; la tua piattaforma può incapsularlo o appiattirlo. Verifica la struttura effettivamente restituita con un test circoscritto e salva il risultato insieme all'ID del record di origine.

Una previsione non stabilisce né l'identità di una persona né il genere che la persona dichiara. Conservala separatamente dai dati forniti dalla persona stessa. Definisci i criteri di accettazione su dati rappresentativi del tuo caso d'uso e valuta separatamente la confidenza del set di dati e la confidenza dell'IA.

| Controllo | Valore o tipo atteso | Decisione nel flusso di lavoro |
| --- | --- | --- |
| `meta.access.mode` | api_key per questo flusso di lavoro con account | Interrompi il flusso di lavoro se il valore è ip_trial e correggi la chiave. Una risposta riuscita della prova IP non dimostra che l'account sia stato autenticato e potrebbe aver già consumato crediti della prova. |
| `meta.usage.billing_status` | confirmed o unconfirmed | Se il valore è unconfirmed, salva l'ID della richiesta e chiarisci l'addebito prima di un nuovo tentativo o di proseguire. |
| `data.result_status / data.gender` | identified con male o female; unknown con null | Salva i risultati identified accettati in un campo dedicato ai dati dedotti. Mantieni i risultati unknown senza assegnare una categoria predefinita. |
| `data.confidence / data.confidence_kind` | Numero da 0 a 1 o null; tipo di evidenza o null | Interpreta observed_frequency e model_reported separatamente; nessuno dei due valori garantisce un'accuratezza generale. |
| `data.source / data.sample_count` | dataset, ai o none / numero intero o null | Salva l'origine della previsione. L'IA non ha una dimensione del campione memorizzata; una dimensione del campione del set di dati non è una misura dell'accuratezza del prodotto. |
| `meta.request_id / meta.usage` | Riferimento della richiesta / oggetto di utilizzo | Salva entrambi insieme al record del flusso di lavoro e al risultato. Non scrivere chiavi API o dati personali superflui nei log ordinari. |
| `Errore HTTP / nessuna risposta` | Problem Details o nessuna risposta completa | Interrompi l'aggiornamento e verifica l'errore e lo stato dell'addebito. Un timeout non dimostra che il server non abbia elaborato nulla. |

- [Documentazione completa della risposta V2](https://www.genderapi.io/it/docs/v2/responses)
- [Errori, timeout e decisioni sui nuovi tentativi](https://www.genderapi.io/it/docs/v2/errors-and-retries)

## Aggiorna solo il record corrispondente in Mailchimp

Usa gli ID Mailchimp salvati del pubblico (Audience) e dell'iscritto per scegliere il record di destinazione. Aggiungi condizioni sullo stato del risultato e sui controlli di accesso e di addebito descritti sopra prima di scrivere i dati in un campo dedicato ai dati dedotti o in un tag approvato. Non convertire mai un genere mancante o il valore null in una categoria predefinita del contatto.

Prova i rami per un risultato identified, un risultato unknown e un errore prima di attivare gli aggiornamenti. Con risposte di esempio fittizie puoi verificare le condizioni della diramazione senza inviare una nuova previsione. L'aggiornamento nell'applicazione di destinazione deve dipendere dai controlli indicati sopra e non deve sovrascrivere campi o tag non correlati.

- [Campi della risposta e risultati sconosciuti](https://www.genderapi.io/it/docs/v2/responses)
- [Accuratezza e confidenza spiegate](https://www.genderapi.io/it/accuracy-methodology)
- [Fonti dei dati e profilo datato del database](https://www.genderapi.io/it/data-provenance)

## Controlla i nuovi tentativi e gli addebiti ripetuti

Integrately documenta nuovi tentativi automatici, comprese impostazioni valide per l'intera azienda. Verifica la policy e la cronologia delle attività prima di attivare questa automazione e valuta gli effetti sugli altri flussi di lavoro prima di modificare un'impostazione condivisa. Ogni richiesta HTTP ripetuta è una richiesta indipendente addebitata; salva gli output riusciti per poter correggere un errore successivo in Mailchimp senza un'altra richiesta.

Ogni nuova richiesta a GenderAPI è un'operazione a sé. Elimina i duplicati degli eventi di origine ripetuti nel tuo flusso di lavoro prima dell'invio, usando l'ID di origine salvato e lo stato di elaborazione. L'ID del record di origine non è una chiave che protegge dalle ripetizioni lato server.

Un risultato unknown riuscito è un risultato completo che viene addebitato. In caso di timeout o di risposta incompleta, il risultato e l'addebito possono essere sconosciuti: salva il riferimento della richiesta, se disponibile, e chiarisci l'addebito prima di inviare di nuovo la richiesta. Rispetta l'intestazione Retry-After quando accompagna una risposta di limite di richieste superato.

- [Crediti e stato dell'addebito](https://www.genderapi.io/it/docs/v2/credits-and-usage)

## Decidere quando usare l'IA

forceToGenderize è facoltativo per nomi, indirizzi email e nomi utente. Quando è attivo, ometti ai_mode o usa fallback; off e always non possono essere combinati con questa opzione e restituiscono 422. Un saldo iniziale positivo basta per avviare una richiesta, anche se l'addebito finale rende il saldo negativo.

La modalità nickname può restituire un genere insieme a name: null. Può anche dare un risultato sconosciuto. Né il normale fallback IA né l'interpretazione dei nickname garantiscono una risposta corretta o un valore diverso da null.

| Opzione della richiesta | Comportamento | Crediti per una ricerca riuscita |
| --- | --- | --- |
| options.ai_mode: off | Usa solo il set di dati. | 1, anche per un risultato sconosciuto |
| options.ai_mode: fallback | Consulta prima il set di dati e poi usa la normale IA se non viene restituito un genere. È il valore predefinito per le richieste singole. | 1 in totale, fallback IA incluso |
| options.ai_mode: always | Usa direttamente l'IA. | 2 |
| forceToGenderize: true | Consulta prima il set di dati e poi lascia che l'IA interpreti un nickname personale o un alias, anche senza un vero nome proprio. | 1 per un risultato trovato nel set di dati; 2 in totale se viene usata l'IA |

- [Opzioni IA e interpretazione dei nickname](https://www.genderapi.io/it/docs/v2/ai-options)
- [Crediti e utilizzo](https://www.genderapi.io/it/docs/v2/credits-and-usage)

## Verifica il flusso di lavoro prima di aumentare il volume

- Con un test circoscritto verifica il JSON effettivamente serializzato, i percorsi dei risultati analizzati, l'accesso con chiave API e la conferma dell'addebito. Se possibile, prova con risposte di esempio la gestione dei risultati unknown e degli errori.
- Chiarisci quali passaggi del flusso di lavoro vengono ripetuti e quali campi del cliente vengono modificati. Salva l'ID del record di origine, la risposta ricevuta e il riferimento della richiesta, così un errore successivo nel sistema di destinazione non richiede un'altra richiesta.
- Attiva prima un'esecuzione piccola e controllata e verificane record e crediti prima di aumentare il parallelismo. I crediti GenderAPI e le attività o operazioni addebitate dalla piattaforma di automazione sono costi separati.
- Per i batch usa POST /api/v2/gender/batch con fino a 50 elementi con accesso tramite chiave API o 10 con la prova IP. L'array items può combinare nomi, indirizzi email e nomi utente, con opzioni esplicite e un id univoco per ogni elemento. Controlla ogni risultato: una risposta HTTP 200 può contenere errori di singoli elementi. Il supporto dei batch in un connettore nativo va verificato separatamente.

- [Batch ed errori dei singoli elementi](https://www.genderapi.io/it/docs/v2/batch)
- [Guida all'implementazione in Python](https://www.genderapi.io/it/integrations/python)
- [Guida all'implementazione in Node.js](https://www.genderapi.io/it/integrations/javascript)

## Posso mappare il campo probability della vecchia azione nativa sul campo confidence di V2?

Verifica prima il contratto della risposta. Una richiesta V2 diretta restituisce data.confidence insieme a data.confidence_kind, su una scala da 0 a 1 oppure null. Nulla supporta l'ipotesi che le etichette e la scala dei campi del connettore nativo corrispondano a questi percorsi.

## L'esempio HTTP diretto consente l'uso dell'IA?

Il corpo della prima richiesta imposta options.ai_mode su off. Cambia deliberatamente il valore in fallback per usare il normale fallback IA per 1 credito in totale, oppure in always per usare direttamente l'IA per 2 crediti. forceToGenderize consulta prima il set di dati: costa 1 credito se la richiesta viene risolta lì, oppure 2 in totale se viene usata l'IA.

## Un risultato unknown è gratuito e può essere ripetuto automaticamente senza rischi?

No. Un risultato unknown riuscito è completo e viene addebitato. Un nuovo tentativo è una nuova ricerca. In caso di errore di trasporto o di addebito non confermato, controlla i dati di utilizzo restituiti e il riferimento della richiesta prima di decidere se inviarla di nuovo.

## Questo flusso di lavoro è stato eseguito con un account collegato?

No. Le istruzioni di configurazione delle piattaforme sono state verificate il 26 settembre 2026 sulla loro documentazione pubblica. Le spiegazioni sulla richiesta e sulla risposta di GenderAPI.io V2 sono state verificate il 27 settembre 2026. La revisione di questa versione italiana del 28 settembre 2026 è una verifica della traduzione e non un nuovo test con un account. Prima di attivare gli aggiornamenti in produzione, verifica con il tuo account i campi attuali dell'azione scelta, l'autenticazione, il corpo della richiesta, la risposta e i nuovi tentativi.

## Documentazione di riferimento

- [Pagina GenderAPI.io su Integrately](https://integrately.com/integrations/genderapi-io)
- [Azioni Webhook/API in Integrately](https://integrately.com/integrations/webhook-api)
- [Documentazione di Integrately](https://integrately.com/docs)
- [Contratto delle richieste di GenderAPI.io V2](https://www.genderapi.io/it/docs/v2/request-parameters)
- [Contratto delle risposte di GenderAPI.io V2](https://www.genderapi.io/it/docs/v2/responses)
- [Addebiti e crediti in GenderAPI.io V2](https://www.genderapi.io/it/docs/v2/credits-and-usage)