Opazovani subjekti

Opazovani subjekti (monitorji) so seznam davčnih številk, za katere vas obvestimo o vsaki spremembi na seznamih FURS. Obvestila pošiljamo po e-pošti in na vaše webhooke. Opazovanje je na voljo od paketa Starter naprej. Upravljanje seznama je brezplačno (0 enot); število mest je odvisno od paketa:

Paket	Hobi	Starter	Growth	Custom
Opazovani subjekti	—	50	500	po dogovoru

Ključ potrebuje obseg monitors (novi ključi ga imajo privzeto). Organizacija ima en seznam, skupen vsem ključem in nadzorni plošči.

Paket Hobi opazovanja ne vključuje: dodajanje (POST /v1/monitors ali add v /v1/monitors/bulk) vrne 403 plan_upgrade_required, zato na paketu Hobi tudi ni obvestil po e-pošti. Seznam (GET) in odstranjevanje delujeta v vseh paketih. Vse spremembe opazovanih subjektov so tudi na nadzorni plošči (stran Spremembe).

Dodajanje

curl -X POST https://api.maticna.si/v1/monitors \
  -H "Authorization: Bearer $MATICNA_KEY" -H "Content-Type: application/json" \
  -d '{"tax_number": "SI19000013", "label": "Dobavitelj 123"}'

Vrne 201 (dodano) ali 200 (že na seznamu). Sprejmemo vsako pravilno oblikovano davčno številko, tudi takšno, ki je na seznamih FURS še ni: ko se pojavi, dobite dogodek entity.created. Odgovor ne vsebuje podatkov o zavezancu; te dobite v dogodkih ali z vpogledom. Ko so vsa mesta zasedena, dobite 403 monitor_limit_reached; na paketu Hobi 403 plan_upgrade_required.

Seznam, odstranjevanje, paketno

curl "https://api.maticna.si/v1/monitors?limit=100" -H "Authorization: Bearer $MATICNA_KEY"
curl -X DELETE https://api.maticna.si/v1/monitors/19000013 -H "Authorization: Bearer $MATICNA_KEY"
curl -X POST https://api.maticna.si/v1/monitors/bulk -H "Authorization: Bearer $MATICNA_KEY" \
  -H "Content-Type: application/json" -d '{"add": ["19000013", "SI 1900 0004"], "remove": ["19000021"]}'

• Seznam je urejen po davčni številki, slots pove zasedena in dovoljena mesta, next_cursor pa naslednjo stran.
• POST /v1/monitors/bulk sprejme do 1.000 davčnih številk v add in remove. Najprej odstrani, nato doda; dodajanje je vse ali nič glede na število mest. Za vsak vnos dobite result: added, exists, removed, not_monitored ali invalid.

Obvestila po e-pošti

Na nadzorni plošči (Spremljanje → Obvestila po e-pošti) izberete, kako vas obveščamo o spremembah opazovanih subjektov:

• Takoj po osvežitvi podatkov: eno sporočilo na organizacijo ob vsaki osvežitvi podatkov FURS (običajno enkrat na delovni dan) s seznamom vseh sprememb. Privzeto vklopljeno.
• Tedenski povzetek: v ponedeljek zjutraj (po slovenskem času) povzetek preteklega tedna, od ponedeljka do nedelje. Tedni brez sprememb ne pošljejo ničesar.
• Vrste sprememb: samo izbrane vrste (npr. odvzem ID za DDV, izbris iz registra); brez izbire dobite vse.

Prejemniki so člani organizacije s potrjenim e-naslovom. Lastniki in skrbniki obvestila prejemajo privzeto, ostali člani se prijavijo sami; vsak izbere tudi jezik (slovenščina ali angleščina). Vsako sporočilo ima povezavo za odjavo z enim klikom (tudi glava List-Unsubscribe) in povezavo na stran Spremembe.

Pravila so ista kot pri webhookih: sporočimo le spremembe, zaznane po tem, ko ste subjekt dodali na seznam; za skrite subjekte brez imen in vrednosti; podatki o samostojnih podjetnikih štejejo v dnevno omejitev fizičnih oseb vašega paketa (nad njo so prikriti). Po prehodu na manjši paket obveščamo le o toliko najstarejših opazovanih subjektih, kolikor mest ima paket; po prehodu na Hobi ostanejo na seznamu (lahko jih odstranite), obvestil o njih pa ne pošiljamo. Na organizacijo pošljemo največ 12 takojšnjih sporočil v 24 urah in največ 100 sprememb na sporočilo (ostale so na nadzorni plošči).