novauth
PrezziDocumentazioneInizia gratis
Riferimento

Riferimento API

Riferimento completo per tutti gli endpoint di verifica Novauth. Ogni canale condivide lo stesso modello di autenticazione e URL di base — variano solo il percorso e il payload.

BASE URLhttps://api.novauth.com/api/v1/connect-hub

Autenticazione

Ogni richiesta deve includere due header. Puoi trovare le tue credenziali nella sezione Developer → API Keys della dashboard. Le credenziali vengono memorizzate nella cache lato server per 5 minuti, quindi le chiavi appena create diventano attive in pochi secondi.

x-api-keyLa tua chiave API. Trattala come una password — non esporla mai nel codice lato client.
x-account-idIl tuo identificatore account. Visualizzato nella dashboard accanto a ogni chiave API.
x-request-idID di correlazione facoltativo. Passa qualsiasi UUID; viene restituito nelle risposte di errore per la tracciatura.

Archivia le credenziali nelle variabili d'ambiente (BETATEL_API_KEY, BETATEL_ACCOUNT_ID). Non hardcodarle mai nei file sorgente.

Le chiavi con prefisso sk_test_ sono chiavi sandbox — non toccano mai i veri operatori e non comportano alcun addebito. Usale durante lo sviluppo, poi sostituiscile con la chiave BTEL_ quando vai in produzione. Modalità Sandbox →

Whitelist IP

Durante la creazione di una chiave API puoi allegare facoltativamente uno o più indirizzi IP o range CIDR. Se è configurata una whitelist IP, qualsiasi richiesta proveniente da un IP non incluso nell'elenco viene rifiutata con 401 Unauthorized, anche se la chiave API è valida. Questo ti consente di bloccare una chiave sull'IP del tuo server, in modo che non possa essere utilizzata in caso di furto.

Esempio di richiesta autenticata
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"callee": "+14155552671"}'

Verify Call

Avvia una chiamata di breve durata con squillo e chiusura. L'ID chiamante codifica l'OTP — il tuo SDK mobile legge il numero in arrivo senza che l'utente debba rispondere.

Invia una Verify Call
POST/api/v1/connect-hub/call/flash
Corpo della richiesta
calleestringobbligatorio
Telefono del destinatario in formato E.164 (es. +14155552671).
callerstring
ID chiamante in formato E.164. Il valore predefinito è il numero configurato sull'account.
max_ring_timenumber
Durata dello squillo in secondi prima della chiusura automatica. Il valore predefinito è casuale, compreso tra i tempi minimo e massimo di squillo configurati sull'account.
Risposta — 200 OK
uuidstring (ULID)
Identificatore univoco della chiamata. Conservalo — necessario per la ricerca CDR e la segnalazione webhook.
callerstring
ID chiamante effettivamente utilizzato (può differire dalla richiesta se è stato applicato il valore predefinito).
calleestring
Numero del destinatario (eco).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "callee": "+14155552671",
    "caller": "+38761000001",
    "max_ring_time": 5
  }'

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "caller": "+38761000001",
#   "callee": "+14155552671"
# }
Ottieni il registro dettagli chiamata
GET/api/v1/connect-hub/call/flash/:uuid/cdr
Risposta — 200 OK
hangup_causestring
Motivo di chiusura SIP (es. NORMAL_CLEARING, NO_ANSWER, ORIGINATOR_CANCEL).
durationnumber
Durata totale della chiamata in secondi (squillo + connessione).
billsecnumber
Durata fatturata in secondi (dalla risposta alla chiusura).
pddnumber
Ritardo post-selezione in secondi (tempo al primo squillo).
destination_countrystring
Nome del paese di destinazione risolto.
start_stampstring (ISO 8601)
Timestamp UTC di avvio della chiamata.
bash
curl https://api.novauth.com/api/v1/connect-hub/call/flash/01KAK9KATW01A437PSXS5EVDCR/cdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "caller": "+38761000001",
#   "callee": "+14155552671",
#   "hangup_cause": "NORMAL_CLEARING",
#   "duration": 6,
#   "billsec": 0,
#   "pdd": 2,
#   "start_stamp": "2024-06-01T10:30:00.000Z",
#   "destination_country": "United States",
#   "destination_country_code": "US"
# }
Elenca i registri delle chiamate
POST/api/v1/connect-hub/call/flash/cdr

Restituisce un elenco paginato di tutte le chiamate per il tuo account. Usa filter per filtrare i risultati per qualsiasi campo CDR (es. callee, hangup_cause).

Corpo della richiesta
pagenumber
Numero di pagina (min: 1, predefinito: 1).
rows_per_pagenumber
Record per pagina (1–100, predefinito: 20).
sort_bystring
Campo di ordinamento (es. start_stamp, callee).
sort_direction"ASC" | "DESC"
Ordine di ordinamento.
filterobject
Filtri chiave/valore facoltativi applicati ai campi CDR.
Risposta — 200 OK
totalnumber
Totale dei record corrispondenti al filtro.
total_pagesnumber
Numero totale di pagine.
has_next_pageboolean
Indica se esiste una pagina successiva.
has_previous_pageboolean
Indica se esiste una pagina precedente.
listCDR[]
Array dei registri dettagli chiamata per la pagina corrente.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash/cdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_by": "start_stamp",
    "sort_direction": "DESC"
  }'
Chiudi una chiamata
DELETE/api/v1/connect-hub/call/flash/:uuid

Termina una chiamata attiva prima che si concluda naturalmente. Restituisce 204 No Content in caso di successo.

bash
# Terminate an active call before it naturally ends
curl -X DELETE https://api.novauth.com/api/v1/connect-hub/call/flash/01KAK9KATW01A437PSXS5EVDCR \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Returns 204 No Content on success

SMS

Invia un messaggio di testo tramite SMPP. Tipicamente utilizzato per inviare un codice OTP numerico che l'utente digita nella tua app.

Invia un SMS
POST/api/v1/connect-hub/sms
Corpo della richiesta
tostringobbligatorio
Telefono del destinatario in formato E.164.
textstringobbligatorio
Corpo del messaggio. Fino a 4096 caratteri; i messaggi più lunghi vengono suddivisi in parti concatenate.
fromstring
ID mittente (alfanumerico o numero di telefono). Il valore predefinito è il mittente configurato sull'account.
Risposta — 200 OK
messageIdstring (UUID)
Identificatore univoco del messaggio. Conservalo — necessario per la ricerca SDR e la segnalazione webhook.
fromstring
ID mittente utilizzato.
tostring
Numero del destinatario (eco).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/sms \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "text": "Your verification code is 482910. Valid for 5 minutes.",
    "from": "Novauth"
  }'

# Response:
# {
#   "messageId": "0a62face-6d15-11f0-962f-d89d6729654c",
#   "from": "Novauth",
#   "to": "14155552671"
# }
Ottieni lo stato del messaggio
GET/api/v1/connect-hub/sms/:messageId/sdr

Recupera lo stato di consegna di un messaggio inviato. Lo stato viene aggiornato in modo asincrono all'arrivo dei rapporti di consegna (DLR) degli operatori.

Risposta — valori di stato
deliveredConsegna confermata all'handset.
sentInviato all'operatore; in attesa di DLR.
failedConsegna fallita (numero non valido, bloccato).
undeliveredOperatore accettato ma consegna non confermata.
bash
curl https://api.novauth.com/api/v1/connect-hub/sms/0a62face-6d15-11f0-962f-d89d6729654c/sdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "...",
#   "messageId": "0a62face-6d15-11f0-962f-d89d6729654c",
#   "from": "Novauth",
#   "to": "+14155552671",
#   "status": "delivered",
#   "timestamp": "2024-06-01T10:30:00.000Z"
# }
Elenca i messaggi
POST/api/v1/connect-hub/sms/sdr

Restituisce un elenco paginato di tutti i messaggi inviati. Accetta lo stesso corpo di paginazione degli altri endpoint elenco (page, rows_per_page, sort_by, filter).

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/sms/sdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

OTP Telegram

Invia un OTP numerico tramite l'API Gateway ufficiale di Telegram. Supporta controlli di raggiungibilità, validazione del codice lato server e revoca con rimborso automatico.

Invia OTP Telegram
POST/api/v1/connect-hub/telegram
Corpo della richiesta
tostringobbligatorio
Telefono del destinatario in formato E.164.
codestringobbligatorio
Codice OTP da recapitare (4–8 cifre).
ttlnumber
Validità del codice in secondi (30–3600). Predefinito: 300.
sender_usernamestring
Nome utente del canale Telegram verificato. Ometti per usare quello predefinito dell'account.
callback_urlstring
Override webhook per richiesta specifica. Telegram Gateway invierà eventi di stato direttamente a questo URL tramite POST.
Risposta — 200 OK
uuidstring (ULID)
ID di correlazione Novauth. Usalo per la segnalazione webhook.
request_idstring
ID richiesta di Telegram Gateway. Usalo per i controlli di stato e la revoca.
statusstring
Stato di consegna normalizzato (sent, delivered, …).
request_costnumber
Addebito per questa richiesta in EUR.
remaining_balancenumber
Saldo dell'account dopo l'addebito.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "code": "482910",
    "ttl": 300
  }'

# Response:
# {
#   "uuid": "01KNV9CWW9ZEYVDFBJ1N7M1DVR",
#   "request_id": "tg_req_abc123",
#   "to": "14155552671",
#   "status": "sent",
#   "request_cost": 0.05,
#   "remaining_balance": 49.95
# }
Controlla la raggiungibilità
POST/api/v1/connect-hub/telegram/check-send-ability

Verifica se il numero ha un account Telegram prima dell'invio. Se is_refunded è true, l'utente non ha un account Telegram — il costo della verifica viene rimborsato e dovresti ripiegare su SMS o Verify Call.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/check-send-ability \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155552671"}'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "phone_number": "14155552671",
#   "request_cost": 0.01,
#   "is_refunded": false,
#   "remaining_balance": 49.99,
#   "delivery_status": { "status": "sent", "updated_at": 1713350400 }
# }
Controlla lo stato della verifica
POST/api/v1/connect-hub/telegram/check-verification-status

Interroga l'esito dell'inserimento del codice per un dato request_id. Passa facoltativamente il code inserito dall'utente per la validazione lato server.

Valori di verification_status
code_validL'utente ha inserito il codice corretto.
code_invalidL'utente ha inserito un codice errato.
code_max_attempts_exceededTroppi tentativi falliti.
expiredTTL del codice scaduto prima dell'inserimento.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/check-verification-status \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "tg_req_abc123",
    "code": "482910"
  }'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "verification_status": {
#     "status": "code_valid",
#     "updated_at": 1713350400
#   }
# }
Revoca la verifica
POST/api/v1/connect-hub/telegram/revoke-verification

Annulla una richiesta OTP attiva prima che l'utente la completi. Se il messaggio non è ancora stato letto, is_refunded sarà true e l'addebito viene restituito al tuo saldo.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/revoke-verification \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "tg_req_abc123"}'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "is_refunded": true,
#   "remaining_balance": 50.0
# }
Ottieni il registro di consegna
GET/api/v1/connect-hub/telegram/:uuid/tdr

Recupera il registro di consegna Telegram completo per un dato uuid (l'ID di correlazione Novauth restituito dall'endpoint di invio). Include stato di consegna, stato di verifica, costo e paese.

bash
curl https://api.novauth.com/api/v1/connect-hub/telegram/01KNV9CWW9ZEYVDFBJ1N7M1DVR/tdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response includes full TDR:
# {
#   "uuid": "01KNV9CWW9ZEYVDFBJ1N7M1DVR",
#   "to": "+14155552671",
#   "status": "DELIVERED",
#   "delivery_status": "delivered",
#   "verification_status": "code_valid",
#   "request_cost": 0.05,
#   "country": "United States",
#   "created_at": "2024-06-01T10:30:00.000Z"
# }
Elenca i registri di consegna
POST/api/v1/connect-hub/telegram/tdr

Restituisce un elenco paginato di tutti i registri di consegna Telegram. Filtra per <code>verification_status</code>, <code>delivery_status</code> o qualsiasi altro campo TDR.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/tdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

WhatsApp

Invia un messaggio OTP tramite WhatsApp Business API. L'utente legge il codice nella conversazione WhatsApp e lo digita nella tua app.

Invia OTP WhatsApp
POST/api/v1/connect-hub/whatsapp/otp
Corpo della richiesta
tostringobbligatorio
Telefono del destinatario in formato E.164.
textstringobbligatorio
Corpo del messaggio. Includi il codice OTP e un suggerimento sulla scadenza.
Risposta — 200 OK
uuidstring (ULID)
Identificatore univoco del messaggio. Conservalo — necessario per la segnalazione webhook.
tostring
Numero del destinatario (eco).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/whatsapp/otp \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "text": "Your verification code is 482910. Valid for 5 minutes."
  }'

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "to": "+14155552671"
# }

Dopo l'invio, segnala l'esito della verifica dell'utente tramite POST /whatsapp/webhook. Vedi il riferimento Webhooks per i dettagli.

Ottieni il registro di consegna
GET/api/v1/connect-hub/whatsapp/:uuid/wdr

Recupera il registro di consegna WhatsApp per un dato uuid restituito dall'endpoint di invio.

bash
curl https://api.novauth.com/api/v1/connect-hub/whatsapp/01KAK9KATW01A437PSXS5EVDCR/wdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "to": "+14155552671",
#   "status": "DELIVERED",
#   "created_at": "2024-06-01T10:30:00.000Z"
# }
Elenca i registri di consegna
POST/api/v1/connect-hub/whatsapp/wdr

Restituisce un elenco paginato di tutti i registri di consegna WhatsApp. Supporta lo stesso corpo <code>page</code>, <code>rows_per_page</code>, <code>filter</code> di tutti gli altri endpoint elenco.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/whatsapp/wdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

Codici di errore

Tutte le risposte di errore seguono lo stesso envelope JSON. Il campo error contiene una stringa leggibile dalla macchina; fornisci il tuo x-request-id al supporto quando segnali problemi.

StatoCodiceDescrizione
400BAD_REQUESTCorpo della richiesta non valido — campo obbligatorio mancante, formato errato o numero di telefono non valido.
401UNAUTHORIZEDHeader x-api-key / x-account-id mancanti o non validi.
402PAYMENT_REQUIREDSaldo dell'account insufficiente. Ricarica il tuo account per continuare.
403FORBIDDENLa chiave API esiste ma non dispone dei permessi per questa operazione.
404NOT_FOUNDL'UUID o la risorsa richiesta non esiste.
409CONFLICTRichiesta duplicata o stato in conflitto (es. revoca di una richiesta già scaduta).
480TEMPORARY_UNAVAILABLEGateway temporaneamente non raggiungibile. Riprova con backoff esponenziale.
486BUSY_HERE(Verify Call) Il destinatario è occupato o la chiamata è stata rifiutata dalla rete.
500INTERNAL_SERVER_ERRORErrore imprevisto del server. Contatta il supporto con il tuo x-request-id.
503SERVICE_UNAVAILABLEGateway disconnesso o servizio in manutenzione. Controlla la pagina di stato.
603DECLINE(Verify Call) Il destinatario ha rifiutato esplicitamente la chiamata.

Per un elenco completo dei codici di errore con le relative fasi di rimedio suggerite, consulta la guida alla gestione degli errori.