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 da sadrži dva zaglavlja. Svoje kredencijale možete pronaći u odjeljku 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. Proslijedite bilo koji UUID; vraća se u odgovorima sa greškom radi praćenja.

Čuvajte kredencijale u promjenljivama 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 zahtjev koji stigne sa IP adrese koja nije na listi bit ć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.

Primjer autentifikovanog 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 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

Tijelo zahtjeva

calleestringobavezno

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

callerstring

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

max_ring_timenumber

Trajanje zvonjenja u sekundama prije automatskog prekida. Podrazumijevano je nasumična vrijednost 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 izvještavanje.

callerstring

Stvarno korišteni ID pozivaoca (može se razlikovati od zahtjeva ako je upotrebljena podrazumijevana vrijednost).

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

Tijelo zahtjeva

pagenumber

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

rows_per_pagenumber

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

sort_bystring

Polje za sortiranje (npr. start_stamp, callee).

sort_direction"ASC" | "DESC"

Redoslijed sortiranja.

filterobject

Opcioni 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

Da li postoji sljedeć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 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

tostringobavezno

Telefon primaoca u E.164 formatu.

textstringobavezno

Tijelo poruke. Do 4096 karaktera; duže poruke se dijele na povezane dijelove.

fromstring

ID pošiljaoca (alfanumerički ili telefonski broj). Podrazumijevano 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 izvještavanje.

fromstring

Korišteni 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 izvještaji o isporuci od operatera (DLR).

Odgovor — vrijednosti statusa

deliveredPotvrđena isporuka na uređaj.

sentProslijeđeno operateru; čeka se DLR.

failedIsporuka nije uspjela (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 tijelo 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 provjere dostupnosti, validaciju koda na serverskoj strani i opoziv sa automatskim povraćajem sredstava.

Pošaljite Telegram OTP

POST/api/v1/connect-hub/telegram

Tijelo zahtjeva

tostringobavezno

Telefon primaoca u E.164 formatu.

codestringobavezno

OTP kod za isporuku (4–8 cifara).

ttlnumber

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

sender_usernamestring

Korisničko ime verifikovanog Telegram kanala. Izostavite da biste koristili podrazumijevanu vrijednost naloga.

callback_urlstring

Webhook nadjačavanje po zahtjevu. 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 izvještavanje.

request_idstring

ID zahtjeva Telegram Gateway-a. Koristite ga za provjere statusa i opoziv.

statusstring

Normalizovani status isporuke (sent, delivered, …).

request_costnumber

Trošak ovog zahtjeva 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
# }

Provjerite dostupnost

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

Provjerava da li broj ima Telegram nalog prije slanja. Ako je is_refunded true, korisnik nema Telegram nalog — trošak provjere 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 }
# }

Provjerite status verifikacije

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

Ispituje ishod unosa koda za dati request_id. Opciono proslijedite code koji je korisnik unio radi validacije na serverskoj 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 ć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

Tijelo zahtjeva

tostringobavezno

Telefon primaoca u E.164 formatu.

textstringobavezno

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

Odgovor — 200 OK

uuidstring (ULID)

Jedinstveni identifikator poruke. Sačuvajte ga — potreban je za webhook izvješ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> tijelo 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; proslijedite svoj x-request-id podršci kada prijavljujete probleme.

Status	Kod	Opis
400	BAD_REQUEST	Nevažeće tijelo zahtjeva — 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 zahtjev ili konfliktno stanje (npr. opoziv već isteklog zahtjeva).
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. Provjerite 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.