Preskoči na glavni sadržaj

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)

PoljeTipOpisZadana vrijednostObavezno
AuthorizationBearer TokenToken za autentifikaciju✔️
expandstringProširena polja
fieldsstringPolja koja vraća zahtjev
hrefbooleanVraća URL pojedinačnog dokumentafalse
dateFormatstringFormatira polja datuma i vremenaphp:d.m.Y H:i:s
dateFieldsstringFormatira samo određena polja
ignoreMissingReferenceboolean(true|false) Koristi se uz referentnom postavljanju poljafalse
ignoreDuplicateReferenceboolean(true|false) Koristi se uz referentnom postavljanju poljatrue
fillPlaceholdersbooleanPrilikom učitavanja .docx datoteka, automatski pokušava popuniti 'placeholder' polja.false
removeUnfiledPlaceholdersbooleanPrilikom 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"
},