Dobrodošli na službenu API dokumentaciju platforme Poziv.net. Ovaj vodič omogućuje programerima i klijentima brzu, stabilnu i sigurnu integraciju vlastitih softverskih rješenja (CRM, web trgovine, ERP sustavi) s našom platformom za slanje transakcijskih i marketinških SMS poruka.

Naš API koristi standardni REST protokol s podacima u JSON formatu, pružajući visoku propusnost i maksimalnu pouzdanost isporuke.

 

🔒 1. Autentifikacija i sigurnost

Svaki zahtjev prema Poziv.net API-ju mora biti autentificiran pomoću Vašeg unikatnog API ključa.

  • Svoj API ključ možete sami generirati, pregledavati ili obrisati unutar korisničkog dashboarda pod tabom “API”.

  • Ključ možete poslati na dva načina: unutar JSON tijela zahtjeva (parametar apikey) ili kao HTTP zaglavlje (apikey: Vaš_Ključ).

 

🚀 2. Osnovne postavke rute (Endpoint)

  • HTTP Metoda: POST

  • URL rute: https://poziv.net/wp-json/bulksms/v1/send

  • Format zaglavlja: Content-Type: application/json

 
📋 3. Parametri zahtjeva (Payload)

Sustav podržava standardni (kompatibilni) format kao i proširene opcije za napredno upravljanje kampanjama.

ParametarTip podatakaObaveznoOpis
apikeyStringDaVaš tajni klijentski API ključ generiran na dashboardu.
toString / ArrayDaPrimatelj ili popis primatelja poruke (npr. "0957508253" ili u međunarodnom formatu "385914244102"). Može se poslati kao pojedinačni string, niz odvojen zarezom ili JSON polje (Array).
textStringDaSender ID (Ime pošiljatelja). Tekstualni naziv tvrtke/brenda (maksimalno 11 znakova, podržava razmake) ili brojčani format (maksimalno 18 znamenki).
messageStringDaCjelokupni sadržaj tekstualne poruke koja se šalje.
campaign_nameStringNeDodatni naziv kampanje radi lakšeg praćenja unutar Vaših izvještaja na dashboardu.
is_gsmBooleanNetrue (default) primjenjuje standardne GSM znakove i optimizira potrošnju kredita. false omogućuje Unicode/Emoji znakove (smanjuje kapacitet po SMS segmentu).
enable_gdprBooleanNetrue automatski dodaje jedinstvenu i sigurnu poveznicu za odjavu primatelja na kraj SMS-a sukladno GDPR regulativi. Default je false.

 

🚦 4. Ograničenja i limiti (Rate Limiting)

Radi očuvanja stabilnosti sustava i zaštite od zlonamjernog spama, na API ruti se primjenjuju sljedeća automatska pravila:

  1. Rate Limit: Maksimalno je dopušteno 30 API zahtjeva u minuti (60 sekundi) po pojedinom ključu/IP adresi. Prekoračenjem ovog limita sustav privremeno odbija zahtjeve s HTTP statusom 429.

  2. Maksimalni broj primatelja: U jednom HTTP zahtjevu možete poslati maksimalno 1000 telefonskih brojeva. Ako Vaša baza broji više korisnika, preporučuje se slanje u paketima (batching) kroz više uzastopnih poziva.

 
💻 5. Primjer testnog poziva (cURL)

Sljedeću naredbu možete kopirati izravno u Vaš terminal ili razvojno okruženje kako biste testirali integraciju:

Bash

 
curl -X POST https://poziv.net/wp-json/bulksms/v1/send \
     -H "Content-Type: application/json" \
     -d '{
       "apikey": "Vaš API ključ",
       "to": "0957508253",
       "text": "Sender ID",
       "message": "Testna poruka preko rute."
     }'

 

📥 6. Odgovori poslužitelja (Responses)

Poziv.net API uvijek vraća strukturirani JSON odgovor zajedno s odgovarajućim HTTP statusnim kodom.

Uspješan odgovor (HTTP 200 OK)

Ukoliko su svi parametri ispravni i sustav ima dovoljno kredita, kampanja se trenutačno prosljeđuje na isporuku:

JSON

 
{
    "success": true,
    "message": "Kampanja uspješno završena. Poslano poruka: 1."
}
Odgovori s pogreškom (HTTP 400 / 401 / 403 / 429)

  • HTTP 401 Unauthorized (Nedostaje ključ):

    JSON

     
    {
    "code": "rest_forbidden",
    "message": "Pristup odbijen. Nedostaje API ključ.",
    "data": {"status": 401}
}

  • HTTP 403 Forbidden (Nevaljan ključ):

    JSON

     
    {
    "code": "rest_forbidden",
    "message": "Pristup odbijen. Nevaljan API ključ.",
    "data": {"status": 403}
}

  • HTTP 429 Too Many Requests (Rate Limit):

    JSON

     
    {
    "code": "rest_rate_limited",
    "message": "Previše zahtjeva. Pokušajte ponovno za minutu.",
    "data": {"status": 429}
}

  • HTTP 400 Bad Request (Logička pogreška – npr. Neispravan Sender ID):

    JSON

     
    {
    "success": false,
    "error": "Neispravan ili predugačak sender ID (maksimalno 11 alfanumeričkih znakova, uključujući razmake)."
}

 

📊 7. Statusi isporuke poruka

U Vašim izvještajima unutar korisničkog sučelja na platformi Poziv.net, svaka poslana kampanja i poruka proći će kroz neke od sljedećih statusa isporuke:

  • Delivered (Isporučeno): Poruka je uspješno dostavljena na mobilni uređaj krajnjeg korisnika.

  • Pending (Na čekanju): Poruka je zaprimljena u sustav i čeka trenutak slanja (kod zakazanih kampanja).

  • Expired (Isteklo): Poruka nije mogla biti isporučena unutar zadanog vremenskog okvira (npr. uređaj primatelja je ugašen dulje od 48 sati).

  • Rejected / Undelivered (Odbijeno / Neisporučeno): Slanje je odbijeno zbog nepostojećeg broja, nedostatka sredstava na računu klijenta ili operaterske blokade.

Za sva dodatna pitanja, prilagođene integracije ili tehničku podršku, slobodno se obratite našem timu putem korisničke podrške na Poziv.net!