Začetek z API-jem

Uvod

Dobrodošli v mDocs+ API dokumentacijo! Ta odsek vas bo vodil skozi začetne korake, potrebne za uporabo našega API-ja.

Predpogoji

Preden začnete, poskrbite, da imate naslednje:

Aktiven račun: Če še niste, poskrbite, da je bil za vas ustvarjen račun.
API ključ: Vaš API ključ lahko najdete na profilu pod zavihkom API.

HTTP zaglavja (headers)

Izboljšajte svojo interakcijo z API-jem z uporabo posebnih funkcij, ki so na voljo na določenih končnih točkah. Do teh funkcij lahko dostopate z dodajanjem parametrov v zaglavje zahteve.

Zaglavja (Headers)

Polje	Tip	Opis	Privzeta vrednost	Obvezno
Authorization	Bearer Token	Žeton za avtentikacijo		✔️
expand	string	Razširjena polja
fields	string	Polja, ki jih vrne zahtevek
href	boolean	(true\|false) Vrne URL od posameznega dokumenta	false
dateFormat	string	Format datuma za časovna polja	php:d.m.Y H:i:s
dateFields	string	Polja, za katera se uporabi oblika datuma nastavljenega z dateFormat
ignoreMissingReference	boolean	(true\|false) Uporabljeno pri referenčnem nastavljanju polj	false
ignoreDuplicateReference	boolean	(true\|false) Uporabljeno pri referenčnem nastavljanju polj	true
fillPlaceholders	boolean	Pri nalaganju .docx datotek, samodejno poizkusi izpolniti 'placeholder' polja.	false
removeUnfiledPlaceholders	boolean	Pri nalaganju .docx datotek, skrije vsa 'placeholder' polja, ki niso bila samodejno izpolnjena.	false

Primer

{
  "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

Zaglavje "Authorization" je ključna komponenta za varovanje dostopa do strežniških virov, saj služi kot ključ za overjanje uporabnikov ali aplikacij, ki pošiljajo zahteve. Mora biti vključeno v vsako API zahtevo, ker zagotavlja, da je dostop dovoljen le pooblaščenim osebam.

API_KEY ključ najdete na vašem profilu, pod zavihkom API.

Fields

Zaglavje "Fields" omogoča selektivno pridobivanje podatkov, ko v zaglavje navedete željena polja, strežnik vključi samo navedena polja. Funkcionalnost omogoča, da prejmete le informacije, ki jih potrebujete, kar optimizira prenos podatkov in poenostavi obdelavo odgovora.

Z navedbo id, created_at in created_by v parametru "fields", se zahteva prilagodi tako, da odgovori samo s temi bistvenimi informacijami.

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

Expand

Zaglavje "Expand" je funkcionalnost, ki izboljša iskanje podatkov, saj omogoča vključitev podrobnih informacij iz povezanih polj (šifrantov).

Na primer, če podatkovna zbirka hrani referenco, kot je created_by ta običajno kaže na uporabnika (na njegov id). Sama referenca ne zagotavlja zadostnega konteksta. Z uporabo tega zaglavja lahko določite dodatne atribute, kot je npr. createdBy.id, createdBy.username in tako obogatite odgovor z bolj smiselnimi podatki.

Ta funkcija omogoča vključitev imena uporabnika neposredno v odgovor, kar omogoča jasnejše razumevanje izvora dokumenta.

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

Href

Zaglavje "Href" je funkcionalnost, ki v odgovor poda URL na dobljeni dokument.

DateFormat

Zaglavje "DateFormat" je funkcionalnost, ki vam omogoča formatiranje datumskih polj. Z določitvijo željene oblike v glavi zahteve lahko zagotovite, da se podatki o datumu in času vrnejo v strukturi, ki vam najbolj ustreza.

Formatiranje

Spodaj so specifikacije formatov, ki jih lahko uporabite z glavo DateFormat, vključno z opisi in primeri:

Privzeta vrednost

Vzorec formata: php:d.m.Y H:i:s
Opis: Privzeta vrednost, ki se uporabi v primeru, da dateFormat ni nastavljen.
Primer: 15.02.2024 12:11:31

ISO 8601 Date and Time

Vzorec formata: php:Y-m-d\TH:i:s\Z
Opis: Oblikuje datum in čas v skladu s standardom ISO 8601, ki se pogosto uporablja za internacionalizacijo.
Primer: 2024-02-15T12:11:31Z

Short Date

Vzorec formata: php:d/m/Y
Opis: Zagotavlja jedrnat prikaz datuma brez časa, kar je idealno za preproste prikaze datuma.
Primer: 15/02/2024

Long Date with Textual Month

Vzorec formata: php:d F Y
Opis: Prikaže datum s celotnim imenom meseca, kar omogoča bolj berljivo obliko za aplikacije, osredotočene na vsebino.
Primer: 15 February 2024

Full DateTime with Day Name

Vzorec formata: php:l, d F Y H:i:s
Opis: Vključuje celoten datum in uro z dnevom v tednu, kar zagotavlja izčrpne časovne informacije.
Primer: Friday, 15 February 2024 12:11:31

DateFields

Zaglavje "dateFields" je funkcionalnost, ki omogoča formatiranje samo določenih polj v formatu, ki je naveden v "dateFormat" zaglavju.

Query parametri

Nekatere GET zahteve omogočajo filtriranje podatkov z dodajanjem parametrov poizvedb na podlagi imen polj.

Če na primer kot parameter poizvedbe uporabite ?country=slovenia, bodo vrnjeni vsi uporabniki iz Slovenije. Lahko tudi povečate natančnost poizvedbe tako, da dodate več parametrov, vendar pa morate za pravilno dodajanje več filtrov namesto ponavljajočega ? uporabiti simbol &.

Na primer, ?country=slovenia&full_name=janez, bo vrnil uporabnike iz "Slovenije" in z imenom "janez".

Poleg filtriranja zahtevka po imenih polj, lahko tudi prilagodite paginacijo: Paginacija je privzeto nastavljena, da vrne prvih 20 rezultatov. Z parametrom page določite katero stran naj API vrne, parameter per-page pa določa koliko rezultatov se prikaže na posamezni strani

Primer: page=2&per-page=5 bo vrnil 5 rezultatov iz druge strani.

Šifranti

Mnogi zapisi imajo kot polje lahko shranjen šifrant iz drugega zapisa.

Polje ki predstavlja šifrant lahko prepoznamo po imenu, in sicer v veliki večini primerov se ime polja zaključi z _id, npr: document_type_id ali pa classification_code_id. Izjema sta polji created_by in updated_by.

Ker tovrstna polja hranijo le referenco (id) do drugega zapisa, si lahko pri pridobivanju podatkov pomagamo z zaglavjem Expand. Pri kreiranju/posodabljanju zapisa pa si lahko pomagamo z referenčnim nastavljanjem polj.

Referenčno nastavljanje polj

Pod referenčnimi polji so vedno shranjeni identifikatorji od povezanih zapisov, zato moramo pri delu s povezanimi polji vedno uporabljati identifikatorje.

Npr. pod povezano polje document_type_id želimo nastaviti sledeč šifrant:

// get document-type/

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

Če poznamo ID od šifranta ga seveda lahko nastavimo direktno, lahko pa ga nastavimo preko reference s sledečim formatom:

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

Podatke o [mdocs_model_class] lahko pridobimo z info klicom, opisanem tukaj.

// 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"
},

V zgornjem primeru vsi načini dosežejo enak rezultat. Pri prvem nastavimo polje direktno, pri drugih dveh pa preko reference;

Pri drugem načinu API-ju sporočimo, da želimo ustvariti zapis za document, pri katerem naj bo v polju document_type_id shranjen tisti document-type, ki ima v polju name = 'certifikat'.

Referenčna zaglavja

Pri referenčnem nastavljanju polja lahko uporabimo dva dodatna zaglavja:

ignoreMissingReference

Po privzetem false

V primeru, da document-type ki naj bi imel name = 'certifikat' ne obstaja, API klic ne bo uspešen. Z uporabo zaglavja ignoreMissingReference lahko to napako ignoriramo - polje bo nastavljeno na null

ignoreDuplicateReference

Po privzetem true

V primeru, da imamo dva zapisa, ki imata vrednost name = 'certifikat', se bo uporabilo zapis z večjo identifikacijsko številko (id = 3 pri spodnjem primeru).

Z uporabo zaglavja ignoreDuplicateReference = false, API klic v primeru podvojenih zapisov ne bo uspešen.

fillPlaceholders

Po privzetem false

Pri nalaganju .docx datotek, samodejno poizkusi izpolniti 'placeholder' polja.

removeUnfiledPlaceholders

Po privzetem false

Pri nalaganju .docx datotek, skrije vsa 'placeholder' polja, ki niso bila samodejno izpolnjena.

// get document-type/

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

Uvod​

Predpogoji​

HTTP zaglavja (headers)​

Zaglavja (Headers)

Authorization​

Fields​

Expand​

Href​

DateFormat​

Formatiranje​

Privzeta vrednost​

ISO 8601 Date and Time​

Short Date​

Long Date with Textual Month​

Full DateTime with Day Name​

DateFields​

Query parametri​

Šifranti​

Referenčno nastavljanje polj​

Referenčna zaglavja​

ignoreMissingReference​

ignoreDuplicateReference​

fillPlaceholders​

removeUnfiledPlaceholders​

Uvod

Predpogoji

HTTP zaglavja (headers)

Authorization

Fields

Expand

Href

DateFormat

Formatiranje

Privzeta vrednost

ISO 8601 Date and Time

Short Date

Long Date with Textual Month

Full DateTime with Day Name

DateFields

Query parametri

Šifranti

Referenčno nastavljanje polj

Referenčna zaglavja

ignoreMissingReference

ignoreDuplicateReference

fillPlaceholders

removeUnfiledPlaceholders