Početak rada sa API-jem

Uvod

Dobrodošli u mDocs+ API dokumentaciju! Ovaj odjeljak će vas provesti kroz osnovne korake potrebne za korištenje našeg API-ja.

Preduslovi

Prije nego što počnete, provjerite da imate sljedeće:

Aktivan nalog: Ako ga još nemate, provjerite da li je za vas kreiran nalog.
API ključ: Vaš API ključ možete pronaći na profilu, u kartici API.

HTTP zaglavlja (headeri)

Poboljšajte svoju interakciju sa API-jem korištenjem posebnih funkcija koje su dostupne na određenim krajnjim tačkama (endpoint-ima). Ovim funkcijama pristupate dodavanjem parametara u zaglavlje zahtjeva.

Zaglavlja (Headeri)

Polje	Tip	Opis	Zadana vrijednost	Obavezno
Authorization	Bearer Token	Token za autentifikaciju		✔️
expand	string	Proširena polja
fields	string	Polja koja vraća zahtjev
href	boolean	Vraća URL pojedinačnog dokumenta	false
dateFormat	string	Formatira polja datuma i vremena	php:d.m.Y H:i:s
dateFields	string	Formatira samo određena polja
ignoreMissingReference	boolean	(true\|false) Koristi se uz referentnom postavljanju polja	false
ignoreDuplicateReference	boolean	(true\|false) Koristi se uz referentnom postavljanju polja	true
fillPlaceholders	boolean	Prilikom učitavanja .docx datoteka, automatski pokušava popuniti 'placeholder' polja.	false
removeUnfiledPlaceholders	boolean	Prilikom učitavanja .docx datoteka, skriva sva 'placeholder' polja koja nisu automatski popunjena.	false

Primjer

{
  "Authorization": "xfWuluzj...",
  "expand": "documentType.*,createdBy.name",
  "fields": "id,subject",
  "href": "true",
  "dateFormat": "php:d/m/Y",
  "dateFields": "created_at,updated_at",
  "ignoreMissingReference": "true",
  "ignoreDuplicateReference": "false",
  "fillPlaceholders": "false",
  "removeUnfiledPlaceholders": "false"
}

Authorization

Zaglavlje "Authorization" je ključna komponenta za zaštitu pristupa resursima na serveru, jer služi za autentifikaciju korisnika ili aplikacija koje šalju zahtjeve. Mora biti uključeno u svaki API zahtjev, jer osigurava da je pristup dozvoljen samo ovlaštenim licima.

API_KEY ključ možete pronaći na svom profilu, u kartici API.

Fields

Zaglavlje "Fields" omogućava selektivno dobavljanje podataka — kada u zaglavlju navedete željena polja, server u odgovor uključi samo ta polja. Ova funkcionalnost omogućava da dobijete samo informacije koje su vam potrebne, čime se optimizira prenos podataka i pojednostavljuje obrada odgovora.

Navođenjem id, created_at i created_by u parametru "fields", zahtjev se prilagođava tako da odgovor sadrži samo ove osnovne informacije.

{
  "id": 5,
  "created_at": "14.11.2025 10:11:31",
  "created_by": 13
}

Expand

Zaglavlje "Expand" je funkcionalnost koja poboljšava dobavljanje podataka, jer omogućava uključivanje detaljnih informacija iz povezanih polja (šifarnika).

Na primjer, ako zapis sadrži referencu poput created_by, ona obično upućuje na korisnika (na njegov id). Sama referenca ne pruža dovoljno konteksta. Korištenjem ovog zaglavlja možete odrediti dodatne atribute, kao što je createdBy.id, createdBy.username, i tako obogatiti odgovor smislenijim podacima.

Ova funkcija omogućava da se korisničko ime uključi direktno u odgovor, čime se jasnije razumije porijeklo dokumenta.

{
  "id": 5,
  "created_at": "14.11.2025 10:11:31"
  "createdBy": {
    "id": 13,
    "username": "superadmin"
  }
}

Href

Zaglavlje "Href" je funkcionalnost koja u odgovor dodaje URL do dobijenog dokumenta.

DateFormat

Zaglavlje "DateFormat" je funkcionalnost koja vam omogućava formatiranje datumskih polja. Navođenjem željenog formata u zaglavlju zahtjeva možete osigurati da se podaci o datumu i vremenu vrate u strukturi koja vam najviše odgovara.

Formatiranje

Ispod se nalaze specifikacije formata koje možete koristiti sa zaglavljem DateFormat, uključujući opise i primjere:

Podrazumijevana vrijednost

Format: php:d.m.Y H:i:s
Opis: Podrazumijevana vrijednost koja se koristi kada dateFormat nije postavljen.
Primjer: 15.02.2024 12:11:31

ISO 8601 Date and Time

Format: php:Y-m-d\TH:i:s\Z
Opis: Formatira datum i vrijeme u skladu sa standardom ISO 8601, koji se često koristi za internacionalizaciju.
Primjer: 2024-02-15T12:11:31Z

Short Date

Format: php:d/m/Y
Opis: Pruža sažet prikaz datuma bez vremena, idealan za jednostavne prikaze datuma.
Primjer: 15/02/2024

Long Date with Textual Month

Format: php:d F Y
Opis: Prikazuje datum sa punim nazivom mjeseca, što omogućava čitljiviji format za aplikacije usmjerene na sadržaj.
Primjer: 15 February 2024

Full DateTime with Day Name

Format: php:l, d F Y H:i:s
Opis: Uključuje puni datum i vrijeme zajedno sa danom u sedmici, čime se dobijaju sveobuhvatne informacije o vremenu.
Primjer: Friday, 15 February 2024 12:11:31

DateFields

Zaglavlje "dateFields" je funkcionalnost koja omogućava formatiranje samo određenih polja, u formatu navedenom u zaglavlju "dateFormat".

Parametri upita

Neki GET zahtjevi omogućavaju filtriranje podataka dodavanjem parametara upita na osnovu naziva polja.

Ako, na primjer, kao parametar upita koristite ?country=slovenia, vratit će se svi korisnici iz Slovenije. Preciznost upita možete povećati i dodavanjem više parametara, ali za ispravno dodavanje više filtera morate koristiti znak & umjesto ponavljanja ?.

Na primjer, ?country=slovenia&full_name=janez će vratiti korisnike iz "Slovenije" sa imenom "janez".

Osim filtriranja zahtjeva po nazivima polja, možete prilagoditi i paginaciju: Paginacija je podrazumijevano postavljena tako da vraća prvih 20 rezultata. Parametrom page određujete koju stranicu API treba vratiti, dok parametar per-page određuje koliko se rezultata prikazuje po stranici.

Primjer: page=2&per-page=5 će vratiti 5 rezultata sa druge stranice.

Referencirana polja

Mnogi zapisi mogu imati polje koje čuva referencu na drugi zapis.

Polje koje predstavlja referencu obično prepoznajemo po nazivu — u većini slučajeva naziv polja se završava sa _id, npr. document_type_id ili classification_code_id. Izuzetak su polja created_by i updated_by.

Budući da ovakva polja čuvaju samo referencu (id) na drugi zapis, pri dobavljanju podataka možete koristiti zaglavlje Expand. Pri kreiranju/ažuriranju zapisa možete koristiti referentno postavljanje polja.

Referentno postavljanje polja

Referentna polja uvijek čuvaju identifikatore povezanih zapisa, pa pri radu sa povezanim poljima uvijek moramo koristiti identifikatore.

Npr. na povezano polje document_type_id želimo postaviti sljedeći zapis iz šifarnika:

// get document-type/

{
  "id": 2,
  "uuid": "6be1...V98",
  "name": "Certifikat",
  "description": "Certifikat xyz"
},

Ako znamo ID zapisa iz šifarnika, možemo ga naravno postaviti direktno, a možemo ga postaviti i putem reference, koristeći sljedeći format:

"$ref.[polje]": "[mdocs_model_class];[polje_za_iskanje];[iskan_niz]"

Podatak o [mdocs_model_class] možemo dobiti pozivom info, opisanim ovdje.

// create document/

{
  "document_type_id": 2
  // ali
  "$ref.document_type_id": "mikrografija.mdocs.document.models.DocumentType;name;certifikat"
  // ali
  "$ref.document_type_id": "mikrografija\\mdocs\\document\\models\\DocumentType;name;certifikat"
},

U gornjem primjeru svi načini daju isti rezultat. Kod prvog polje postavljamo direktno, a kod druga dva putem reference.

Kod drugog načina API-ju saopćavamo da želimo kreirati zapis za document, kod kojeg u polju document_type_id treba biti sačuvan onaj document-type koji u polju name ima vrijednost 'certifikat'.

Referentna zaglavlja

Pri referentnom postavljanju polja možemo koristiti dva dodatna zaglavlja:

ignoreMissingReference

Podrazumijevano false

Ako document-type sa name = 'certifikat' ne postoji, API poziv neće biti uspješan. Korištenjem zaglavlja ignoreMissingReference možemo zanemariti ovu grešku — polje će biti postavljeno na null.

ignoreDuplicateReference

Podrazumijevano true

Ako imamo dva zapisa koja imaju vrijednost name = 'certifikat', koristit će se zapis sa većim identifikacionim brojem (id = 3 u primjeru ispod).

Korištenjem zaglavlja ignoreDuplicateReference = false, API poziv neće biti uspješan u slučaju dupliciranih zapisa.

fillPlaceholders

Podrazumijevano false

Prilikom učitavanja .docx datoteka, automatski pokušava popuniti 'placeholder' polja.

removeUnfiledPlaceholders

Podrazumijevano false

Prilikom učitavanja .docx datoteka, skriva sva 'placeholder' polja koja nisu automatski popunjena.

// get document-type/

{
  "id": 2,
  "uuid": "6be1...V98",
  "name": "Certifikat",
  "description": "Certifikat xyz"
},
{
  "id": 3,
  "uuid": "asg4...G3D",
  "name": "Certifikat",
  "description": "Certifikat 123"
},

Uvod​

Preduslovi​

HTTP zaglavlja (headeri)​

Zaglavlja (Headeri)

Authorization​

Fields​

Expand​

Href​

DateFormat​

Formatiranje​

Podrazumijevana vrijednost​

ISO 8601 Date and Time​

Short Date​

Long Date with Textual Month​

Full DateTime with Day Name​

DateFields​

Parametri upita​

Referencirana polja​

Referentno postavljanje polja​

Referentna zaglavlja​

ignoreMissingReference​

ignoreDuplicateReference​

fillPlaceholders​

removeUnfiledPlaceholders​

Uvod

Preduslovi

HTTP zaglavlja (headeri)

Authorization

Fields

Expand

Href

DateFormat

Formatiranje

Podrazumijevana vrijednost

ISO 8601 Date and Time

Short Date

Long Date with Textual Month

Full DateTime with Day Name

DateFields

Parametri upita

Referencirana polja

Referentno postavljanje polja

Referentna zaglavlja

ignoreMissingReference

ignoreDuplicateReference

fillPlaceholders

removeUnfiledPlaceholders