API di Aptiva: chiave, autenticazione e primi passi

Le API di Aptiva permettono ai tuoi sistemi di fare, senza passare dal pannello, ciò che faresti a mano: creare o aggiornare un contatto (lead), avviare una chiamata dell'agente vocale AI verso quel contatto, leggere l'esito con trascrizione e riepilogo, e configurare il trasferimento di chiamata verso gli interni del tuo centralino o verso numeri esterni. Il caso tipico è un form del sito o un CRM che, appena arriva una richiesta, fa partire la chiamata dell'agente entro pochi secondi.

Questa guida è il punto di partenza: dove prendere la chiave, come autenticarsi, quali convenzioni valgono per tutte le richieste e come leggere gli errori. Alla fine c'è il primo esempio completo con curl e la mappa delle altre due guide, una sul trasferimento di chiamata e una su lead e chiamate.

Cosa puoi fare con le API di Aptiva#

Le API di Aptiva coprono tre aree, tutte accessibili con la stessa chiave:

Gli agenti e i numeri di telefono, invece, si creano e si gestiscono dal pannello: dalle API ne usi gli identificativi.

L'indirizzo base di tutte le richieste è:

https://api.aptiva.cloud/external/api

I percorsi indicati nelle guide vanno aggiunti a questo indirizzo: per esempio POST /leads/create significa POST https://api.aptiva.cloud/external/api/leads/create. La reference interattiva generata dal servizio, con gli schemi completi di ogni endpoint, è pubblica su api.aptiva.cloud/docs.

Dove trovare la chiave API e come conservarla#

La chiave API si trova nel pannello di Aptiva, nel menu utente in basso a sinistra, alla voce «Mostra API Key». È una chiave per azienda: identifica il tuo account e dà accesso a tutti i suoi agenti, lead e chiamate.

Due cose da sapere prima di cliccare:

• La chiave viene mostrata una sola volta. Dopo la prima visualizzazione la voce del menu si disattiva. Copiala subito e salvala in un gestore di segreti (le variabili d'ambiente del tuo server, il vault del tuo hosting), non in un file condiviso né in una chat.
• Non si rigenera dal pannello. Se la perdi, o sospetti che sia finita nelle mani sbagliate, scrivici dalla pagina Contatti: la sostituiamo noi.

Trattala come una password di amministratore: chi la possiede può leggere le trascrizioni delle tue chiamate e far partire chiamate a tuo nome.

Come autenticarsi: l'header X-API-Key#

Ogni richiesta alle API di Aptiva deve contenere la chiave nell'header HTTP X-API-Key:

GET /external/api/leads?pageSize=5 HTTP/1.1
Host: api.aptiva.cloud
X-API-Key: <API_KEY>
Accept: application/json

Se la chiave manca o è sbagliata, la risposta è 401 con codice invalid_api_key:

{
  "detail": "The request lacks valid external API credentials",
  "code": "invalid_api_key"
}

Perché le chiamate vanno fatte dal server, non dal browser#

Le API di Aptiva vanno chiamate dal tuo server (o da una funzione serverless, un'automazione, un CRM), mai dal codice JavaScript che gira nel browser dei visitatori. Ci sono due motivi, e il primo basta da solo:

1. La chiave dà pieno accesso alla tua azienda. Qualunque cosa finisca in una pagina web è leggibile da chi la visita: una chiave nel browser è una chiave pubblica.
2. Il servizio blocca le richieste dal browser con le regole CORS: le uniche origini ammesse sono quelle del pannello di Aptiva. Una chiamata fetch da un sito qualunque fallisce.

Il modello corretto per un form del sito è: il visitatore compila il form, il tuo server riceve i dati, il tuo server chiama Aptiva con la chiave. Nella guida su lead e chiamate c'è l'esempio completo di questo flusso.

Le convenzioni del JSON: camelCase e campi sconosciuti#

Il JSON delle API di Aptiva usa nomi di campo in camelCase (leadId, agentId, ringTimeout, additionalInfo), sia in ingresso sia in uscita. L'header Content-Type: application/json va inviato su ogni richiesta con body.

I campi sconosciuti vengono rifiutati: se invii una proprietà che lo schema non prevede (un refuso come agentID al posto di agentId, o un campo del tuo CRM copiato per errore), la richiesta fallisce con 422 e codice validation_error, e nei dettagli trovi "type": "extra_forbidden" con il nome del campo. È una scelta voluta: un refuso viene scoperto al primo test, non dopo una settimana di dati mancanti.

Solo i campi che richiedono un testo non vuoto (per esempio externalLeadId o i messaggi del trasferimento di chiamata) vengono ripuliti dagli spazi ai bordi e rifiutano la stringa vuota con 422. I campi di testo facoltativi come name, lastName e leadCompanyName vengono salvati così come li invii, spazi inclusi, e accettano anche la stringa vuota: la pulizia dei dati del form è compito del tuo sistema.

Come sono fatti gli errori e perché ragionare sul codice#

Ogni risposta di errore delle API di Aptiva è un JSON con due campi fissi: detail, un testo leggibile in inglese, e code, un codice stabile su cui scrivere la logica del tuo programma.

{
  "detail": "lead not found",
  "code": "not_found"
}

Gli errori di validazione aggiungono un terzo campo, details, con l'elenco dei problemi (campo, tipo di errore, valore ricevuto):

{
  "detail": "Validation failed",
  "code": "validation_error",
  "details": [
    {
      "type": "extra_forbidden",
      "loc": ["body", "agentID"],
      "msg": "Extra inputs are not permitted",
      "input": 42
    }
  ]
}

La regola pratica è distinguere gli errori su code, non sullo stato HTTP. Lo stesso stato viene usato per situazioni diverse: 422 è sia un errore di validazione (validation_error) sia un errore di business con un codice specifico (per esempio OUTBOUND_CONFIG_REQUIRED quando l'agente non è un agente per chiamate in uscita); 409 è usato per i conflitti di stato (AGENT_DISABLED, SIP_CALLING_NOT_CONFIGURED). Le guide sulle singole aree elencano i codici e cosa fare per ciascuno.

Nota sul 429: viene generato dal livello di ingresso dell'infrastruttura, non dall'applicazione, quindi il corpo della risposta può non seguire il formato detail e code. Gestiscilo sullo stato HTTP.

L'header X-Request-ID per parlare con il supporto#

Ogni risposta delle API di Aptiva contiene l'header X-Request-ID, un identificativo univoco (UUID versione 4) della richiesta. Quando ci scrivi per un comportamento inatteso, allega quel valore insieme a data e ora: ci permette di ritrovare la richiesta nei nostri log in pochi secondi.

Puoi anche inviare tu un X-Request-ID in formato UUID v4: viene usato come identificativo della richiesta e restituito nella risposta, così puoi correlare i log del tuo sistema con i nostri. Se il valore inviato non è un UUID v4 valido, ne viene generato uno nuovo.

Come funziona la paginazione delle liste#

Le liste di lead (GET /leads) e di chiamate (GET /calls) sono paginate e ordinate con quattro parametri query:

L'ordinamento predefinito è per identificativo crescente, cioè dal più vecchio al più recente. Per leggere prima gli elementi più recenti usa isAscending=false.

Con orderBy puoi ordinare per uno dei campi che la lista restituisce:

• lead: id, name, lastName, email, phone, leadCompanyName;
• chiamate: id, createdAt, duration, outcome, direction.

Un campo diverso da questi risponde 422 con validation_error e il dettaglio su orderBy.

I metadati della paginazione non stanno nel corpo (che è l'array degli elementi) ma nell'header X-Pagination, un JSON con questi campi:

{
  "pageNumber": 0,
  "requestedPageSize": 50,
  "actualPageSize": 50,
  "totalCount": 1284,
  "totalFilteredCount": 1284,
  "pagesWithFilters": 26,
  "pages": 26,
  "hasNext": true
}

Per scorrere tutta una lista: parti da pageNumber=0, leggi hasNext e, finché è true, incrementa pageNumber. Per una sincronizzazione periodica conviene un pageSize fra 100 e 500: risposte più leggere e più facili da riprovare in caso di errore di rete.

Limiti di frequenza: cosa aspettarsi#

Le API di Aptiva hanno limiti di frequenza per indirizzo IP a protezione dell'infrastruttura. Un'integrazione normale (un form del sito, una sincronizzazione del CRM, un cruscotto che legge le chiamate ogni minuto) non li raggiunge mai.

Due regole di buon senso li rendono irrilevanti:

• Se ricevi 429, riprova con un'attesa crescente: per esempio 1, 2, 4, 8 secondi, con un massimo di tentativi. Non riprovare immediatamente in ciclo.
• Non inviare raffiche di richieste parallele per importare dati storici: fallo in sequenza, o con un parallelismo basso. Se devi importare decine di migliaia di contatti in una volta, scrivici prima: troviamo il modo migliore.

Dove trovare gli identificativi (agente, lead, chiamata, numero)#

Le API di Aptiva lavorano con identificativi numerici che leggi dal pannello o dalle risposte delle API stesse:

Il modo più solido per un'integrazione è non trascrivere gli ID a mano ma salvarli quando li ricevi: POST /leads/create restituisce l'ID del lead, GET /calls restituisce gli ID delle chiamate insieme all'ID del lead a cui si riferiscono.

Il primo esempio completo con curl#

Il primo test da fare è leggere gli ultimi lead della tua azienda: se funziona, chiave e indirizzo sono giusti. Da un terminale, con la chiave in una variabile d'ambiente:

export APTIVA_API_KEY="<API_KEY>"

curl -sS -D - \
  "https://api.aptiva.cloud/external/api/leads?pageNumber=0&pageSize=5&isAscending=false" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Accept: application/json"

L'opzione -D - stampa anche gli header, così vedi X-Pagination e X-Request-ID. Una risposta corretta ha stato 200 e un corpo simile a questo:

[
  {
    "id": 1284,
    "email": "mario.rossi@example.com",
    "name": "Mario",
    "lastName": "Rossi",
    "phone": "+393331234567",
    "leadCompanyName": "Rossi Srl"
  }
]

Se invece ricevi 401 con invalid_api_key, controlla che la chiave sia copiata per intero e che l'header si chiami esattamente X-API-Key. Se ricevi 422 con validation_error, controlla il nome dei parametri: sono in camelCase, per esempio pageSize e non page_size.

Un secondo test, che scrive: creare un lead con il tuo numero di telefono. Il telefono viene validato come numero italiano se non ha il prefisso internazionale, e restituito normalizzato nel formato internazionale (+39...) quando leggi il lead.

curl -sS -X POST "https://api.aptiva.cloud/external/api/leads/create" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "<IL_TUO_NUMERO_DI_PROVA>",
    "name": "Mario",
    "lastName": "Rossi",
    "email": "mario.rossi@example.com"
  }'

La risposta è 201 con {"id": 1285}: quell'id è il leadId da usare per avviare una chiamata. Se il numero esiste già fra i tuoi lead, non viene creato un duplicato: i campi inviati aggiornano il lead esistente e la risposta è comunque 201 con il suo id.

Le altre due guide#

La documentazione delle API di Aptiva è in tre guide, pensate per essere lette in quest'ordine:

1. Questa guida: chiave, autenticazione, convenzioni, errori, paginazione.
2. API: creare lead e avviare chiamate: creazione e aggiornamento dei lead con i campi liberi additionalInfo, avvio della chiamata con la cadenza dei richiami, lettura di esito, trascrizione e durate, con l'esempio completo «form del sito → lead → chiamata → esito».
3. API: configurare il trasferimento di chiamata: attivazione del trasferimento assistito di un agente, rubrica con interni e numeri, messaggi di presentazione e di mancata risposta, tempo di squillo.

Per capire che cosa fa il trasferimento assistito prima di configurarlo, leggi Trasferimento assistito: l'agente AI passa la chiamata. Se qualcosa non ti è chiaro o ti serve un endpoint che non trovi, scrivici dalla pagina Contatti: le API crescono con le richieste dei clienti.