Dokumentacija za AI agente i programe

Šta servis radi

platilako od podataka za plaćanje pravi NBS IPS QR kôd — QR sliku u kojoj je upisan nalog za prenos. Kada se takav kôd skenira u aplikaciji banke, polja naloga se popune sama. Postoje dva puta: alat u pregledaču, koji ume i da pročita podatke sa fotografije ili PDF-a računa, i ovaj API.

platilako nije servis Narodne banke Srbije, Uprave za trezor ni bilo kog drugog organa i nije sa njima povezan. Oblik kôda je propisala NBS; to je javno dostupan propis koji svako sme da primeni. Ako citirate ovu stranicu, molimo da tu razliku prenesete.

Servis priprema nalog, ne izvršava plaćanje. Poslednji korak je uvek potvrda korisnika u aplikaciji njegove banke.

Alat u pregledaču i API nisu isti put

Razlika je namerna i treba je preneti korisniku. Ako podatke za plaćanje šaljete ovim API-jem, oni napuštaju uređaj korisnika — što kod alata u pregledaču nije slučaj.

Krajnja tačka

POST https://platilako.rs/api/v1/ips-qr

• Telo zahtevaJSON. Ako telo nije ispravan JSON, vraća se 400.
• OdgovorJSON, uvek sa poljem „ok“. Zaglavlje je Cache-Control: no-store.
• CORSAccess-Control-Allow-Origin: *, dozvoljeni su POST i OPTIONS i zaglavlje Content-Type. Na OPTIONS se vraća 204.
• KljučNema ga. Nema registracije ni zaglavlja za prijavu.

Polja zahteva

• racunPrimaocaobaveznoRačun primaoca. Prihvata se 18 cifara („840000074332184394“) ili oblik „840-743321843-94“. Kontrolni broj se proverava po MOD 97-10.
• primalacobaveznoNaziv primaoca. Najviše 70 znakova i najviše 3 reda. Ćirilica se preslovljava u latinicu.
• iznosobaveznoIznos u dinarima. Prihvata se broj ili tekst; „10.000,00“, „10000“ i „10 000,5“ daju isti rezultat. Mora biti veći od nule.
• sifraPlacanjapodrazumevano „289“Tri cifre, prva 1 ili 2. Ako se izostavi, upisuje se 289 — opšta šifra za naloge građana. Za javne prihode je po pravilu 253.
• uplatilacopcionoPodaci o platiocu. Najviše 70 znakova i najviše 3 reda. Ako je prazno, oznaka se izostavlja.
• svrhaopcionoSvrha plaćanja. Najviše 35 znakova, u jednom redu.
• modelopcionoDve cifre. Ako se izostavi a poziv na broj postoji, upisuje se „00“.
• pozivNaBrojopcionoPoziv na broj bez modela. Po modelu 97 crtice se uklanjaju i kontrolni broj se proverava. Ako je prazno, oznaka RO se izostavlja u celini.
• slikapodrazumevano trueAko je false, u odgovoru nema polja „svg“ — vraćaju se samo zapis i podaci o kôdu.

Vrednosti se pretvaraju u tekst, pa je za iznos jednako ispravno poslati broj i niz znakova. Nedostajuće polje se tretira kao prazno.

Primer zahteva

POST /api/v1/ips-qr HTTP/1.1
Host: platilako.rs
Content-Type: application/json

{
  "racunPrimaoca": "840-743321843-94",
  "primalac": "Republika Srbija",
  "iznos": "3596,13",
  "sifraPlacanja": "253",
  "svrha": "Republička administrativna taksa",
  "model": "97",
  "pozivNaBroj": "78123456789",
  "slika": false
}

Primer odgovora

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "ok": true,
  "zapis": "K:PR|V:01|C:1|R:840000074332184394|N:Republika Srbija|I:RSD3596,13|SF:253|S:Republička administrativna taksa|RO:9778123456789",
  "polja": {
    "K": "PR",
    "V": "01",
    "C": "1",
    "R": "840000074332184394",
    "N": "Republika Srbija",
    "I": "RSD3596,13",
    "SF": "253",
    "S": "Republička administrativna taksa",
    "RO": "9778123456789"
  },
  "kod": {
    "verzija": 8,
    "korekcija": "M"
  },
  "racun": {
    "banka": "Uprava za trezor",
    "javniPrihod": {
      "konto": "743321",
      "opis": "Prihodi od novčanih kazni za prekršaje"
    }
  },
  "napomena": "Kôd je formiran po specifikaciji Narodne banke Srbije. platilako nije servis NBS. Podaci poslati ovom API-ju se ne čuvaju."
}

• zapisTekst koji je upisan u QR kôd. Oznake idu propisanim redosledom.
• poljaIsti podaci razloženi po oznakama, radi provere.
• kod.verzija i kod.korekcijaVerzija QR simbola i nivo korekcije grešaka, uvek M — isti kao kod zvaničnog NBS generatora.
• kod.svgSlika kôda kao SVG. Vraća se kada „slika“ nije false; u primeru je izostavljena zbog dužine.
• racun.bankaNaziv banke prepoznat po prve tri cifre računa, ili null ako šifra banke nije poznata.
• racun.javniPrihodKonto i opis iz Plana računa za uplatu javnih prihoda, ili null ako račun nije javni prihod.

Greške

Kada podaci ne zadovoljavaju specifikaciju, vraća se status 400 i spisak grešaka. Polje polje nosi oznaku iz zapisa (na primer R, I ili RO), a null kada se greška ne odnosi ni na jednu oznaku.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "ok": false,
  "greske": [
    {
      "polje": "R",
      "poruka": "Kontrolni broj računa 265-123456-78 ne odgovara (MOD 97-10)."
    }
  ]
}

Greške se ne zaobilaze. Neispravan kontrolni broj računa gotovo uvek znači da je neka cifra pogrešna, a ne da je provera prestroga.

Šta API ne može da proveri

Broj računa i poziv na broj po modelu 97 imaju kontrolni broj, pa se pogrešna cifra otkriva sama. Iznos tu proveru nema — svaki niz cifara je moguć iznos. Ako iznos dolazi iz nepouzdanog izvora, na primer čitanjem sa slike, tražite od korisnika da ga potvrdi pre nego što napravite kôd.

Isto važi za poziv na broj po modelima koji nemaju kontrolni broj: ne postoji način da se proveri, pa se prenosi onako kako je poslat.

Povezane stranice

• Šta je IPS QR kôd — sve oznake u zapisu i pravila za svaku.
• Poziv na broj po modelu 97 — kako se računa kontrolni broj po ISO 7064 MOD 97-10.
• Pretraga računa javnih prihoda — brojevi računa i konta iz Plana računa.
• Pitanje ili prijava greške: support@uplatilako.rs