# Introduzione alle API L'API REST di Your AI Connector ti consente di creare la tua integrazione personale basata sul tuo account. Puoi creare e cercare contatti, gestire campagne, FAQ, attività e appuntamenti, inviare messaggi, registrare webhook, leggere analisi e connettere canali di messaggistica: tutto ciò che fa la dashboard, guidato dal codice. Questa è la pagina principale della documentazione API. Se stai connettendo Your AI Connector a uno strumento che dispone già di un'integrazione integrata, potresti non aver bisogno dell'API. L'API è destinata a integrazioni personalizzate e all'automazione su larga scala. ::: note **Nota:** Queste pagine sono scritte per gli sviluppatori. Se non sei uno sviluppatore, condividi questa sezione con il tuo team tecnico. ::: --- ## URL di base Ogni richiesta viene inviata allo stesso indirizzo web di base e tutti i percorsi in questi documenti sono relativi ad esso: ``` https://api.youraiconnector.com/v1 ``` Quindi l'endpoint delle campagne è `https://api.youraiconnector.com/v1/campaigns`, l'endpoint dei contatti è `https://api.youraiconnector.com/v1/contacts` e così via. Tutte le richieste devono utilizzare una connessione sicura (HTTPS). Le richieste HTTP semplici vengono rifiutate. --- ## Ottenere una chiave API L'accesso all'API è una **funzionalità a pagamento**. Se il tuo piano non la include, ogni richiesta restituirà un `403` con questo corpo: ```json { "success": false, "error_code": 403, "error": "This action requires the \"api_access\" feature, which is not enabled for this account." } ``` Una volta abilitato l'accesso API sul tuo piano, genera una chiave dalla dashboard. La procedura completa passo dopo passo è disponibile in [Accesso API](../integrations/api-access.md) — in breve: vai su **Impostazioni → Integrazioni → Chiave API** per generare o rigenerare la tua chiave. La Chiave API è una sezione a sé stante sotto Integrazioni, separata dai Webhook, e appare solo quando l'accesso API è attivo sul tuo piano. Tratta la chiave come una password: garantisce l'accesso completo al tuo account. --- ## Autenticazione Puoi inviare la tua chiave API in quattro modi. Tutti funzionano su ogni endpoint che accetta l'autenticazione tramite chiave API. | Metodo | Come | Ideale per | |---|---|---| | Parametro di query | `?apiKey=YOUR_API_KEY` | Test rapidi, URL del browser, configurazioni legacy | | Header | `X-API-Key: YOUR_API_KEY` | Integrazioni di produzione | | Header Bearer | `Authorization: Bearer YOUR_API_KEY` | Integrazioni di produzione | | Token ID Firebase | `Authorization: Bearer ` | Solo sessioni di app di prima parte | Per la produzione, preferisci una delle forme di header in modo che la tua chiave non finisca mai in un log del server o nella cronologia del browser. La forma con parametro di query funziona sempre ed è la più semplice per un test occasionale. Consulta [Autenticazione](authentication.md) per un'analisi completa di ciascun metodo, con esempi e indicazioni su quando utilizzare quale. --- ## La tua prima richiesta Ecco una chiamata completa e funzionante che elenca le campagne sul tuo account. Utilizza la tua chiave API e restituisce per prime le campagne più recenti. **cURL** ```bash curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); console.log(data.campaigns); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/campaigns", params={"limit": 10}, headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() print(data["campaigns"]) ``` Una risposta corretta ha questo aspetto: ```json { "success": true, "campaigns": [ { "id": "NBCXrhqGPSFsd6MV7pRo", "name": "Inbound WhatsApp Leads", "type": "Incoming from Unknown Contacts", "status": "Live", "enabled": true, "archived": false, "created_at": 1700000000000, "ai_mode": true, "language": "en", "enabled_channels": ["whatsapp", "instagram"] } ], "next_cursor": null } ``` --- ## Risposte di successo ed errore Ogni risposta JSON contiene un flag `success` in modo da poter creare una ramificazione senza dover analizzare i codici di stato. Una risposta di successo è `success: true` più i dati per quell'endpoint (il nome del campo varia: `campaigns`, `contacts`, `data` e così via): ```json { "success": true, "campaigns": [] } ``` Una risposta fallita è `success: false` con un messaggio `error` leggibile dall'utente e un `error_code` numerico che corrisponde allo stato HTTP: ```json { "success": false, "error": "Invalid cursor", "error_code": 400 } ``` Controlla sempre `success` (o lo stato HTTP) prima di leggere i dati. Consulta [Errori e paginazione](errors-and-pagination.md) per la tabella completa dei codici di stato e per sapere come scorrere set di risultati di grandi dimensioni. --- ## Limiti di frequenza Le richieste autenticate sono limitate a **300 richieste al minuto** per chiave API. Esiste inoltre un limite massimo più ampio di **1.200 richieste al minuto per account**, che conteggia ogni richiesta autenticata effettuata per tale account. Se superi uno dei due limiti, riceverai una risposta `429`: ```json { "success": false, "error_code": 429, "error": "Rate limit exceeded. Please try again later." } ``` Attendi e riprova dopo una breve pausa. Puoi anche controllare il tuo utilizzo attuale in qualsiasi momento con `GET https://api.youraiconnector.com/v1/api-keys/usage`, che restituisce quante richieste hai utilizzato nella finestra corrente e quando si azzera: utile per creare una limitazione lato client. Consulta [Chiavi API](api-keys.md). --- ## Guide alle risorse I gruppi di risorse qui sotto hanno ciascuno la propria guida con i percorsi esatti, i campi di richiesta e le strutture di risposta. | Risorsa | Cosa copre | |---|---| | [Agenti IA](agents.md) | Crea e configura gli Agenti IA: impostazioni, orari di attività, conoscenza, regole di tagging, strumenti, media e bozze | | [Punti di ingresso](entry-points.md) | Decidi quale Agente IA risponde a una nuova conversazione: impostazioni predefinite del canale, un Agente per numero WhatsApp, parole chiave, commenti e regole per i follower | | [Broadcast](broadcasts.md) | Crea, prezza, avvia, metti in pausa e duplica invii una tantum a un elenco di contatti | | [Campagne](campaigns.md) | Crea, aggiorna, duplica, abilita, archivia e ispeziona le campagne e la loro configurazione bot | | [Contatti](contacts.md) | Crea, cerca, elenca, aggiorna, importa, tagga ed elimina contatti | | [FAQ](faqs.md) | Gestisci le voci di domande e risposte utilizzate dal tuo assistente IA e collegale alle campagne | | [Knowledge Base](knowledge-base.md) | Importa siti web e documenti nella conoscenza della tua IA e raggruppa le FAQ in gruppi | | [Attività](tasks.md) | Crea e gestisci attività CRM, fasi della bacheca e tipi di attività | | [Messaggi](messages.md) | Invia messaggi in uscita e leggi la cronologia delle conversazioni | | [Appuntamenti](appointments.md) | Prenota, riprogramma, annulla ed elimina appuntamenti | | [Canali](channels.md) | Connetti e disconnetti canali di messaggistica, acquista numeri e imposta quale Agente IA risponde alle nuove conversazioni su ciascun canale | | [Modelli](templates.md) | Crea, invia e controlla lo stato di approvazione dei modelli di messaggio WhatsApp | | [Analisi](analytics.md) | Leggi le statistiche giornaliere sugli eventi dei messaggi, l'utilizzo dei crediti e i riepiloghi dei costi dell'IA | | [Webhook](webhooks.md) | Registra endpoint per ricevere notifiche di eventi in tempo reale | | [Team](team.md) | Gestisci membri del team, inviti, ruoli, autorizzazioni e dipartimenti | | [Chiavi API](api-keys.md) | Ispeziona, ruota e revoca la tua chiave API, controlla l'utilizzo dei limiti di frequenza e crea chiavi aggiuntive con accesso limitato | ### Agenti, Punti di ingresso e Broadcast Gli Agenti IA, i Punti di ingresso e i Broadcast sono tutti presenti nella specifica OpenAPI pubblicata, quindi puoi consultare i loro campi esatti ed eseguire richieste live tramite l'[esploratore API](reference.md). Ognuno ha la sua guida dedicata: [Agenti IA](agents.md), [Punti di ingresso](entry-points.md) e [Broadcast](broadcasts.md). --- ## Leggere questa documentazione in formato Markdown Ogni pagina di questa documentazione ha un gemello in formato Markdown semplice: prendi l'indirizzo della pagina e aggiungi `/index.md` alla fine. Quindi questa pagina è disponibile anche su `https://docs.youraiconnector.com/api/getting-started/index.md` e viene restituita come testo semplice anziché come pagina web: utile quando vuoi incollare una pagina in un assistente AI o richiamarla in uno script. Per consultare l'intero set, parti da `https://docs.youraiconnector.com/sitemap.xml`, che elenca ogni pagina che pubblichiamo. Tieni presente che la documentazione è volutamente esclusa dai motori di ricerca, quindi recuperare questi indirizzi direttamente è il modo per accedervi dal codice. Non esiste ancora un endpoint di documentazione protetto da chiave né un download in blocco: i gemelli Markdown e la sitemap costituiscono l'intera interfaccia e nessuno dei due richiede una chiave API. --- ## Passaggi successivi - [Autenticazione](authentication.md) — scegli il metodo di autenticazione corretto per la tua integrazione. - [Errori e impaginazione](errors-and-pagination.md) — gestisci gli errori e scorri i risultati. - [Accesso API](../integrations/api-access.md) — genera la tua chiave e visualizza esempi pratici.