Hiter začetek

1. Ustvarite račun na app.maticna.si/sign-up. Brezplačni paket Hobi vključuje 100 enot na mesec (največ 20 na dan), brez kartice.

2. Ustvarite ključ na strani Ključi. Obstaja ena vrsta skrivnega ključa mk_…, ki vedno vrača prave podatke; brez ločenega testnega okolja. Ključ je prikazan samo enkrat; shranite ga v spremenljivko okolja:

   export MATICNA_KEY="mk_…"

3. Pokličite API. Klic vrne pravi zapis iz registra FURS in porabi 1 enoto paketa Hobi. Če želite le preizkusiti zahteve, uporabite preizkuševalnik API-ja v nadzorni plošči: ne porablja enot.

   curl

   curl https://api.maticna.si/v1/entities/80267432 \
     -H "Authorization: Bearer $MATICNA_KEY"

   JavaScript

   const res = await fetch('https://api.maticna.si/v1/entities/80267432', {
     headers: { Authorization: `Bearer ${process.env.MATICNA_KEY}` },
   });
   if (!res.ok) {
     const problem = await res.json(); // application/problem+json
     throw new Error(`${problem.code}: ${problem.detail ?? problem.title}`);
   }
   const entity = await res.json();
   console.log(entity.name, entity.vat.registered);

   PHP

   <?php
   $ch = curl_init('https://api.maticna.si/v1/entities/80267432');
   curl_setopt_array($ch, [
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('MATICNA_KEY')],
   ]);
   $entity = json_decode(curl_exec($ch), true);
   $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
   echo $status === 200 ? $entity['name'] : $entity['code'];

   Python

   import os, requests
   
   r = requests.get(
       "https://api.maticna.si/v1/entities/80267432",
       headers={"Authorization": f"Bearer {os.environ['MATICNA_KEY']}"},
       timeout=5,
   )
   if r.ok:
       entity = r.json()
       print(entity["name"], entity["vat"]["registered"])
   else:
       print(r.json()["code"])

   C#

   using System.Net.Http.Headers;
   using System.Text.Json;
   
   using var http = new HttpClient { BaseAddress = new Uri("https://api.maticna.si/v1/") };
   http.DefaultRequestHeaders.Authorization =
       new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MATICNA_KEY"));
   
   var res = await http.GetAsync("entities/80267432");
   using var doc = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
   Console.WriteLine(res.IsSuccessStatusCode
       ? doc.RootElement.GetProperty("name").GetString()
       : doc.RootElement.GetProperty("code").GetString());

4. Preberite odgovor. Dobite objekt entity z naslovom, dejavnostjo, statusom DDV in virom:

   {
     "object": "entity",
     "tax_number": "80267432",
     "vat_id": "SI80267432",
     "type": "legal_entity",
     "status": "active",
     "name": "PETROL, SLOVENSKA ENERGETSKA DRUŽBA, D.D., LJUBLJANA",
     "legal_form": "d.d.",
     "vat": { "registered": true, "registered_on": "1999-07-01", "scope_code": null, "group_id": null, "source": "furs_po" },
     "source": { "dataset": "furs_po", "as_of": "2026-10-19", "attribution": "Vir: FURS" }
   }

Naslednji koraki

• Iskanje po imenu in samodokončanje: Iskanje.

• Paketno preverjanje (paket Starter in višji): POST /v1/entities/lookup z do 100 ID-ji:

  curl https://api.maticna.si/v1/entities/lookup \
    -H "Authorization: Bearer $MATICNA_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{"ids": ["80267432", "SI80267432", "5025796000"]}'

• Napake obravnavajte po code, ne po besedilu: Napake.

• Pred produkcijo preberite Omejitve in kvote in Obračunske enote.