novauth
CijeneDokumentacijaPočnite besplatno
Referenca

API referenca

Kompletna referenca za sve Novauth endpointe za verifikaciju. Svi kanali dijele isti model autentifikacije i isti osnovni URL — razlikuju se samo putanja i payload.

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

Autentifikacija

Svaki zahtjev mora sadržavati dva zaglavlja. Svoje vjerodajnice možete pronaći u odjeljku Developer → API Keys na nadzornoj ploči. Vjerodajnice se keširaju na poslužiteljskoj strani na 5 minuta, tako da su novokreirani ključevi aktivni u roku od nekoliko sekundi.

x-api-keyVaš API ključ. Tretirajte ga kao lozinku — nikada ga ne izlažite u kodu na klijentskoj strani.
x-account-idIdentifikator vašeg računa. Prikazan je na nadzornoj ploči pored svakog API ključa.
x-request-idOpcionalni korelacijski ID. Proslijedite bilo koji UUID; vraća se u odgovorima s greškom radi praćenja.

Čuvajte vjerodajnice u varijablama okruženja (BETATEL_API_KEY, BETATEL_ACCOUNT_ID). Nikada ih ne upisujte izravno u izvorne datoteke.

Ključevi s prefiksom sk_test_ su sandbox ključevi — nikada ne dodiruju prave operatore i ne stvaraju troškove. Koristite ih tijekom razvoja, a zatim prijeđite na svoj BTEL_ ključ kada krenete u produkciju. Sandbox način rada →

Popis dopuštenih IP adresa

Prilikom kreiranja API ključa možete opcionalno priložiti jednu ili više IP adresa ili CIDR raspona. Ako je popis dopuštenih IP adresa postavljen, svaki zahtjev koji stigne s IP adrese koja nije na popisu bit će odbijen sa 401 Unauthorized, čak i ako je sam API ključ ispravan. To vam omogućuje da zaključate ključ na IP adresu svog poslužitelja, tako da se ne može koristiti ako procuri.

Primjer autentificiranog zahtjeva
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

Pokreće kratkotrajni poziv koji zazvoni i prekine se. ID pozivatelja kodira OTP — vaš mobilni SDK čita dolazni broj bez potrebe da se korisnik javi.

Pošaljite Verify Call
POST/api/v1/connect-hub/call/flash
Tijelo zahtjeva
calleestringobvezno
Telefon primatelja u E.164 formatu (npr. +14155552671).
callerstring
ID pozivatelja u E.164 formatu. Zadano se koristi broj postavljen na računu.
max_ring_timenumber
Trajanje zvonjenja u sekundama prije automatskog prekida. Zadano je nasumična vrijednost između minimalnog i maksimalnog vremena zvonjenja postavljenog na računu.
Odgovor — 200 OK
uuidstring (ULID)
Jedinstveni identifikator poziva. Spremite ga — potreban je za pretragu CDR-a i webhook izvještavanje.
callerstring
Stvarno korišteni ID pozivatelja (može se razlikovati od zahtjeva ako je upotrijebljena zadana vrijednost).
calleestring
Broj primatelja (eho).
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"
# }
Preuzmite detaljni zapis poziva
GET/api/v1/connect-hub/call/flash/:uuid/cdr
Odgovor — 200 OK
hangup_causestring
SIP razlog prekida (npr. NORMAL_CLEARING, NO_ANSWER, ORIGINATOR_CANCEL).
durationnumber
Ukupno trajanje poziva u sekundama (zvonjenje + veza).
billsecnumber
Naplaćeno trajanje u sekundama (od javljanja do prekida).
pddnumber
Kašnjenje nakon biranja u sekundama (vrijeme do prvog zvona).
destination_countrystring
Razriješeni naziv odredišne zemlje.
start_stampstring (ISO 8601)
UTC vremenska oznaka pokretanja poziva.
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"
# }
Izlistajte zapise poziva
POST/api/v1/connect-hub/call/flash/cdr

Vraća paginirani popis svih poziva za vaš račun. Koristite filter da suzite rezultate po bilo kojem CDR polju (npr. callee, hangup_cause).

Tijelo zahtjeva
pagenumber
Broj stranice (min: 1, zadano: 1).
rows_per_pagenumber
Zapisa po stranici (1–100, zadano: 20).
sort_bystring
Polje za sortiranje (npr. start_stamp, callee).
sort_direction"ASC" | "DESC"
Redoslijed sortiranja.
filterobject
Opcionalni ključ/vrijednost filteri primijenjeni na CDR polja.
Odgovor — 200 OK
totalnumber
Ukupan broj zapisa koji odgovaraju filteru.
total_pagesnumber
Ukupan broj stranica.
has_next_pageboolean
Postoji li sljedeća stranica.
has_previous_pageboolean
Postoji li prethodna stranica.
listCDR[]
Niz detaljnih zapisa poziva za trenutnu stranicu.
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"
  }'
Prekinite poziv
DELETE/api/v1/connect-hub/call/flash/:uuid

Prekida aktivan poziv prije nego što se prirodno završi. Vraća 204 No Content u slučaju uspjeha.

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

Isporučuje tekstualnu poruku putem SMPP-a. Obično se koristi za slanje numeričkog OTP koda koji korisnik unosi u vašu aplikaciju.

Pošaljite SMS
POST/api/v1/connect-hub/sms
Tijelo zahtjeva
tostringobvezno
Telefon primatelja u E.164 formatu.
textstringobvezno
Tijelo poruke. Do 4096 znakova; dulje poruke dijele se na povezane dijelove.
fromstring
ID pošiljatelja (alfanumerički ili telefonski broj). Zadano se koristi pošiljatelj postavljen na računu.
Odgovor — 200 OK
messageIdstring (UUID)
Jedinstveni identifikator poruke. Spremite ga — potreban je za pretragu SDR-a i webhook izvještavanje.
fromstring
Korišteni ID pošiljatelja.
tostring
Broj primatelja (eho).
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"
# }
Preuzmite status poruke
GET/api/v1/connect-hub/sms/:messageId/sdr

Dohvaća status isporuke poslane poruke. Status se ažurira asinkrono kako pristižu izvještaji o isporuci od operatora (DLR).

Odgovor — vrijednosti statusa
deliveredPotvrđena isporuka na uređaj.
sentProslijeđeno operatoru; čeka se DLR.
failedIsporuka nije uspjela (nevažeći broj, blokiran).
undeliveredOperator je prihvatio, ali isporuka nije potvrđena.
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"
# }
Izlistajte poruke
POST/api/v1/connect-hub/sms/sdr

Vraća paginirani popis svih poslanih poruka. Prihvaća isto paginacijsko tijelo kao i ostali endpointi za izlistavanje (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"
  }'

Telegram OTP

Šalje numerički OTP preko službenog Telegram Gateway API-ja. Podržava provjere dostupnosti, validaciju koda na poslužiteljskoj strani i opoziv s automatskim povratom sredstava.

Pošaljite Telegram OTP
POST/api/v1/connect-hub/telegram
Tijelo zahtjeva
tostringobvezno
Telefon primatelja u E.164 formatu.
codestringobvezno
OTP kod za isporuku (4–8 znamenki).
ttlnumber
Važenje koda u sekundama (30–3600). Zadano: 300.
sender_usernamestring
Korisničko ime verificiranog Telegram kanala. Izostavite da biste koristili zadanu vrijednost računa.
callback_urlstring
Webhook nadjačavanje po zahtjevu. Telegram Gateway slat će POST događaje o statusu izravno na ovaj URL.
Odgovor — 200 OK
uuidstring (ULID)
Novauth korelacijski ID. Koristite ga za webhook izvještavanje.
request_idstring
ID zahtjeva Telegram Gatewaya. Koristite ga za provjere statusa i opoziv.
statusstring
Normalizirani status isporuke (sent, delivered, …).
request_costnumber
Trošak ovog zahtjeva u EUR.
remaining_balancenumber
Stanje računa nakon naplate.
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
# }
Provjerite dostupnost
POST/api/v1/connect-hub/telegram/check-send-ability

Provjerava ima li broj Telegram račun prije slanja. Ako je is_refunded true, korisnik nema Telegram račun — trošak provjere se vraća i trebate prijeći na SMS ili 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 }
# }
Provjerite status verifikacije
POST/api/v1/connect-hub/telegram/check-verification-status

Ispituje ishod unosa koda za dani request_id. Opcionalno proslijedite code koji je korisnik unio radi validacije na poslužiteljskoj strani.

Vrijednosti verification_status
code_validKorisnik je unio ispravan kod.
code_invalidKorisnik je unio pogrešan kod.
code_max_attempts_exceededPreviše neuspješnih pokušaja.
expiredTTL koda je istekao prije unosa.
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
#   }
# }
Opozovite verifikaciju
POST/api/v1/connect-hub/telegram/revoke-verification

Otkazuje aktivan OTP zahtjev prije nego što ga korisnik dovrši. Ako poruka još nije pročitana, is_refunded bit će true i naplata se vraća na vaše stanje.

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
# }
Preuzmite zapis o isporuci
GET/api/v1/connect-hub/telegram/:uuid/tdr

Dohvaća kompletan Telegram zapis o isporuci (TDR) za dani uuid (Novauth korelacijski ID koji vraća endpoint za slanje). Uključuje status isporuke, status verifikacije, trošak i zemlju.

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"
# }
Izlistajte zapise o isporuci
POST/api/v1/connect-hub/telegram/tdr

Vraća paginirani popis svih Telegram zapisa o isporuci. Filtrirajte po <code>verification_status</code>, <code>delivery_status</code> ili bilo kojem drugom TDR polju.

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

Šalje OTP poruku preko WhatsApp Business API-ja. Korisnik čita kod u WhatsApp razgovoru i unosi ga u vašu aplikaciju.

Pošaljite WhatsApp OTP
POST/api/v1/connect-hub/whatsapp/otp
Tijelo zahtjeva
tostringobvezno
Telefon primatelja u E.164 formatu.
textstringobvezno
Tijelo poruke. Uključite OTP kod i naznaku o isteku.
Odgovor — 200 OK
uuidstring (ULID)
Jedinstveni identifikator poruke. Spremite ga — potreban je za webhook izvještavanje.
tostring
Broj primatelja (eho).
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"
# }

Nakon slanja, prijavite ishod verifikacije korisnika preko POST /whatsapp/webhook. Detalje potražite u Webhooks referenci.

Preuzmite zapis o isporuci
GET/api/v1/connect-hub/whatsapp/:uuid/wdr

Dohvaća WhatsApp zapis o isporuci (WDR) za dani uuid koji vraća endpoint za slanje.

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"
# }
Izlistajte zapise o isporuci
POST/api/v1/connect-hub/whatsapp/wdr

Vraća paginirani popis svih WhatsApp zapisa o isporuci. Podržava isto <code>page</code>, <code>rows_per_page</code>, <code>filter</code> tijelo kao i svi ostali endpointi za izlistavanje.

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"
  }'

Kodovi grešaka

Svi odgovori s greškom prate isti JSON omotač. Polje error sadrži strojno čitljiv string; proslijedite svoj x-request-id podršci kada prijavljujete probleme.

StatusKodOpis
400BAD_REQUESTNevažeće tijelo zahtjeva — nedostaje obvezno polje, pogrešan format ili nevažeći telefonski broj.
401UNAUTHORIZEDNedostajuća ili nevažeća x-api-key / x-account-id zaglavlja.
402PAYMENT_REQUIREDNedovoljno stanje na računu. Nadoplatite račun da biste nastavili.
403FORBIDDENAPI ključ postoji, ali nema dopuštenje za ovu operaciju.
404NOT_FOUNDTraženi UUID ili resurs ne postoji.
409CONFLICTDupliciran zahtjev ili konfliktno stanje (npr. opoziv već isteklog zahtjeva).
480TEMPORARY_UNAVAILABLEGateway je privremeno nedostupan. Pokušajte ponovno uz eksponencijalno odgađanje.
486BUSY_HERE(Verify Call) Primatelj je zauzet ili je mreža odbila poziv.
500INTERNAL_SERVER_ERRORNeočekivana greška poslužitelja. Kontaktirajte podršku uz svoj x-request-id.
503SERVICE_UNAVAILABLEGateway je isključen ili je servis na održavanju. Provjerite statusnu stranicu.
603DECLINE(Verify Call) Primatelj je izričito odbio poziv.

Za kompletan popis kodova grešaka s predloženim koracima za otklanjanje, pogledajte vodič za rukovanje greškama.