# Collegare Zapier a GenderAPI.io V2

> Collega Zapier 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/zapier-gender-api-integration

Last reviewed: 2026-09-28

## Scegli la connessione Zapier 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.

Zapier offre azioni GenderAPI.io per determinare il genere da un nome o da un indirizzo email. La pagina pubblica non indica né la versione dell'endpoint né il contratto della risposta V2. Prima di modificare le mappature nei passaggi successivi, verifica l'output delle azioni native esistenti.

La configurazione V2 qui sotto usa Webhooks by Zapier con una richiesta POST strutturata. Webhooks by Zapier richiede un piano Zapier a pagamento. Il saldo dell'account GenderAPI e le attività consumate in Zapier vengono addebitati separatamente.

- [App GenderAPI.io su Zapier](https://zapier.com/apps/gender-api/integrations)
- [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 dall'indirizzo email. 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 Zapier

- Parti da un trigger Mailchimp che fornisca il record corretto dell'iscritto. Salva l'ID del pubblico (Audience) e del contatto e aggiungi prima dell'azione HTTP un filtro che salti gli indirizzi email vuoti.
- Scegli Webhooks by Zapier e l'azione POST. Inserisci l'URL qui sotto e Payload Type: JSON. Aggiungi i campi dati type = email, value = indirizzo email mappato dell'iscritto e options__ai_mode = off.
- In Zapier la notazione con doppio trattino basso annida options__ai_mode come options.ai_mode nel corpo JSON. Il blocco di codice qui sotto mostra il corpo che l'API riceve; non è un quarto campo da aggiungere all'azione.
- Nella sezione Headers aggiungi Authorization con il valore Bearer YOUR_API_KEY. Usa application/json come Content-Type. Non scrivere la chiave nei campi del trigger, nella stringa di query o nelle risposte di esempio.

| 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 Zapier**

```json
{
  "type": "email",
  "value": "alex@example.com",
  "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

Le intestazioni del webhook non sono un campo dedicato ai segreti: chi può modificare lo Zap le vede. Limita l'accesso e non condividere lo Zap, schermate o esportazioni che contengono credenziali. Zapier offre anche API by Zapier con credenziali salvate, ma lì la configurazione del corpo della richiesta è diversa da questa ricetta POST strutturata.

Non incapsulare il corpo: invia un solo oggetto, non un elenco né un array. Scegli l'azione JSON strutturata per i dati dei clienti mappati; Custom Request invia testo grezzo e non esegue automaticamente l'escape dei caratteri speciali nei valori inseriti.

- [Richieste webhook strutturate e JSON annidato in Zapier](https://help.zapier.com/hc/en-us/articles/8496326446989-Send-webhooks-in-Zap-workflows)
- [Connessioni con credenziali in API by Zapier](https://help.zapier.com/hc/en-us/articles/44391660158733-How-to-get-started-with-API-by-Zapier)
- [Comportamento della ripetizione (Replay) in Zapier](https://help.zapier.com/hc/en-us/articles/19220226086797-What-is-replay)

## 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

Esamina la risposta analizzata dell'azione di prova e scegli i campi per data.gender, data.result_status e gli altri percorsi V2 indicati sopra. Il selettore dei campi di Zapier può appiattire le etichette annidate: basati sul valore osservato e sul percorso padre invece di presupporre il vecchio campo probability del connettore nativo. Aggiorna solo l'iscritto Mailchimp il cui ID è stato salvato.

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

Prima di attivare lo Zap verifica in Zapier le impostazioni di Autoreplay e della ripetizione manuale (Replay). Ripetere un'azione webhook non riuscita invia una nuova richiesta; non ripetere una richiesta riuscita solo per correggere un passaggio Mailchimp successivo. Salva insieme l'ID originale dell'iscritto e il risultato della 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)

## Perché la configurazione di Zapier usa options__ai_mode?

L'azione POST strutturata di Webhooks usa un doppio trattino basso per creare JSON annidato. L'API riceve options: {ai_mode: off}, dove off è una stringa. Non riceve un campo letterale options__ai_mode al primo livello.

## 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

- [App GenderAPI.io su Zapier](https://zapier.com/apps/gender-api/integrations)
- [Richieste webhook strutturate e JSON annidato in Zapier](https://help.zapier.com/hc/en-us/articles/8496326446989-Send-webhooks-in-Zap-workflows)
- [Connessioni con credenziali in API by Zapier](https://help.zapier.com/hc/en-us/articles/44391660158733-How-to-get-started-with-API-by-Zapier)
- [Comportamento della ripetizione (Replay) in Zapier](https://help.zapier.com/hc/en-us/articles/19220226086797-What-is-replay)
- [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)