Referenca

API referenca

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

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

Autentifikacija

Svaki zahtev mora da sadrži dva zaglavlja. Svoje kredencijale možete pronaći u odeljku Developer → API Keys na kontrolnoj tabli. Kredencijali se keširaju na serverskoj 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 naloga. Prikazan je na kontrolnoj tabli pored svakog API ključa.

x-request-idOpcioni korelacioni ID. Prosledite bilo koji UUID; vraća se u odgovorima sa greškom radi praćenja.

Čuvajte kredencijale u promenljivama okruženja (BETATEL_API_KEY, BETATEL_ACCOUNT_ID). Nikada ih ne upisujte direktno u izvorne fajlove.

Ključevi sa prefiksom sk_test_ su sandbox ključevi — nikada ne dodiruju prave operatere i ne stvaraju troškove. Koristite ih tokom razvoja, a zatim pređite na svoj BTEL_ ključ kada krenete u produkciju. Sandbox režim →

IP lista dozvoljenih adresa

Prilikom kreiranja API ključa možete opciono priložiti jednu ili više IP adresa ili CIDR opsega. Ako je IP lista dozvoljenih adresa podešena, svaki zahtev koji stigne sa IP adrese koja nije na listi biće odbijen sa 401 Unauthorized, čak i ako je sam API ključ ispravan. Ovo vam omogućava da zaključate ključ na IP adresu vašeg servera, tako da ne može da se koristi ako procuri.

Primer autentifikovanog zahteva

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

Telo zahteva

calleestringobavezno

Telefon primaoca u E.164 formatu (npr. +14155552671).

callerstring

ID pozivaoca u E.164 formatu. Podrazumevano se koristi broj podešen na nalogu.

max_ring_timenumber

Trajanje zvonjenja u sekundama pre automatskog prekida. Podrazumevano je nasumična vrednost između minimalnog i maksimalnog vremena zvonjenja podešenog na nalogu.

Odgovor — 200 OK

uuidstring (ULID)

Jedinstveni identifikator poziva. Sačuvajte ga — potreban je za pretragu CDR-a i webhook izveštavanje.

callerstring

Stvarno korišćeni ID pozivaoca (može se razlikovati od zahteva ako je upotrebljena podrazumevana vrednost).

calleestring

Broj primaoca (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 (vreme do prvog zvona).

destination_countrystring

Razreš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 paginiranu listu svih poziva za vaš nalog. Koristite filter da suzite rezultate po bilo kom CDR polju (npr. callee, hangup_cause).

Telo zahteva

pagenumber

Broj stranice (min: 1, podrazumevano: 1).

rows_per_pagenumber

Zapisa po stranici (1–100, podrazumevano: 20).

sort_bystring

Polje za sortiranje (npr. start_stamp, callee).

sort_direction"ASC" | "DESC"

Redosled sortiranja.

filterobject

Opcioni ključ/vrednost filteri primenjeni na CDR polja.

Odgovor — 200 OK

totalnumber

Ukupan broj zapisa koji odgovaraju filteru.

total_pagesnumber

Ukupan broj stranica.

has_next_pageboolean

Da li postoji sledeća stranica.

has_previous_pageboolean

Da li postoji 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 pre nego što se prirodno završi. Vraća 204 No Content u slučaju uspeha.

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

Telo zahteva

tostringobavezno

Telefon primaoca u E.164 formatu.

textstringobavezno

Telo poruke. Do 4096 karaktera; duže poruke se dele na povezane delove.

fromstring

ID pošiljaoca (alfanumerički ili telefonski broj). Podrazumevano se koristi pošiljalac podešen na nalogu.

Odgovor — 200 OK

messageIdstring (UUID)

Jedinstveni identifikator poruke. Sačuvajte ga — potreban je za pretragu SDR-a i webhook izveštavanje.

fromstring

Korišćeni ID pošiljaoca.

tostring

Broj primaoca (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

Dohvata status isporuke poslate poruke. Status se ažurira asinhrono kako pristižu izveštaji o isporuci od operatera (DLR).

Odgovor — vrednosti statusa

deliveredPotvrđena isporuka na uređaj.

sentProsleđeno operateru; čeka se DLR.

failedIsporuka nije uspela (nevažeći broj, blokiran).

undeliveredOperater 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 paginiranu listu svih poslatih poruka. Prihvata isto paginaciono telo kao i ostali endpointi za listanje (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 zvaničnog Telegram Gateway API-ja. Podržava provere dostupnosti, validaciju koda na serverskoj strani i opoziv sa automatskim povraćajem sredstava.

Pošaljite Telegram OTP

POST/api/v1/connect-hub/telegram

Telo zahteva

tostringobavezno

Telefon primaoca u E.164 formatu.

codestringobavezno

OTP kod za isporuku (4–8 cifara).

ttlnumber

Važenje koda u sekundama (30–3600). Podrazumevano: 300.

sender_usernamestring

Korisničko ime verifikovanog Telegram kanala. Izostavite da biste koristili podrazumevanu vrednost naloga.

callback_urlstring

Webhook nadjačavanje po zahtevu. Telegram Gateway će slati POST događaje o statusu direktno na ovaj URL.

Odgovor — 200 OK

uuidstring (ULID)

Novauth korelacioni ID. Koristite ga za webhook izveštavanje.

request_idstring

ID zahteva Telegram Gateway-a. Koristite ga za provere statusa i opoziv.

statusstring

Normalizovani status isporuke (sent, delivered, …).

request_costnumber

Trošak ovog zahteva u EUR.

remaining_balancenumber

Stanje naloga 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
# }

Proverite dostupnost

POST/api/v1/connect-hub/telegram/check-send-ability

Proverava da li broj ima Telegram nalog pre slanja. Ako je is_refunded true, korisnik nema Telegram nalog — trošak provere se vraća i treba da pređete 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 }
# }

Proverite status verifikacije

POST/api/v1/connect-hub/telegram/check-verification-status

Ispituje ishod unosa koda za dati request_id. Opciono prosledite code koji je korisnik uneo radi validacije na serverskoj strani.

Vrednosti verification_status

code_validKorisnik je uneo ispravan kod.

code_invalidKorisnik je uneo pogrešan kod.

code_max_attempts_exceededPreviše neuspešnih pokušaja.

expiredTTL koda je istekao pre 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 zahtev pre nego što ga korisnik dovrši. Ako poruka još nije pročitana, is_refunded će biti 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

Dohvata kompletan Telegram zapis o isporuci (TDR) za dati uuid (Novauth korelacioni 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 paginiranu listu svih Telegram zapisa o isporuci. Filtrirajte po <code>verification_status</code>, <code>delivery_status</code> ili bilo kom 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"
  }'

Š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

Telo zahteva

tostringobavezno

Telefon primaoca u E.164 formatu.

textstringobavezno

Telo poruke. Uključite OTP kod i naznaku o isteku.

Odgovor — 200 OK

uuidstring (ULID)

Jedinstveni identifikator poruke. Sačuvajte ga — potreban je za webhook izveštavanje.

tostring

Broj primaoca (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

Dohvata WhatsApp zapis o isporuci (WDR) za dati 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 paginiranu listu svih WhatsApp zapisa o isporuci. Podržava isto <code>page</code>, <code>rows_per_page</code>, <code>filter</code> telo kao i svi ostali endpointi za listanje.

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 sa greškom prate isti JSON omotač. Polje error sadrži mašinski čitljiv string; prosledite svoj x-request-id podršci kada prijavljujete probleme.

Status	Kod	Opis
400	BAD_REQUEST	Nevažeće telo zahteva — nedostaje obavezno polje, pogrešan format ili nevažeći telefonski broj.
401	UNAUTHORIZED	Nedostajuća ili nevažeća x-api-key / x-account-id zaglavlja.
402	PAYMENT_REQUIRED	Nedovoljno stanje na nalogu. Dopunite nalog da biste nastavili.
403	FORBIDDEN	API ključ postoji, ali nema dozvolu za ovu operaciju.
404	NOT_FOUND	Traženi UUID ili resurs ne postoji.
409	CONFLICT	Dupliran zahtev ili konfliktno stanje (npr. opoziv već isteklog zahteva).
480	TEMPORARY_UNAVAILABLE	Gateway je privremeno nedostupan. Pokušajte ponovo uz eksponencijalno odlaganje.
486	BUSY_HERE	(Verify Call) Primalac je zauzet ili je mreža odbila poziv.
500	INTERNAL_SERVER_ERROR	Neočekivana greška servera. Kontaktirajte podršku uz svoj x-request-id.
503	SERVICE_UNAVAILABLE	Gateway je isključen ili je servis na održavanju. Proverite statusnu stranicu.
603	DECLINE	(Verify Call) Primalac je izričito odbio poziv.

Za kompletnu listu kodova grešaka sa predloženim koracima za otklanjanje, pogledajte vodič za rukovanje greškama.