SudReg API Documentation

Complete technical guide for Croatian company registry data access

SudReg API Dokumentacija

Tehnički vodič za pristup podacima Sudskog registra Hrvatske

Pogledaj na GitHubu

Getting Started (For Beginners)

✨

New to APIs?

An API (Application Programming Interface) is like a digital waiter. You "order" data (like company info), and the API "fetches" it from the database for you.

Key Concepts

  • HTTP: The language of the web. We use GET to read data and POST to send/receive secure info.
  • JSON: The format of the data. It looks like a simple list of key-value pairs.
  • Endpoint: A specific web address that returns specific data.

Početni koraci (Za početnike)

✨

Prvi put koristite API?

API (Application Programming Interface) je poput digitalnog konobara. Vi "naručite" podatke (npr. info o tvrtki), a API ih "donese" iz baze podataka za vas.

Osnovni pojmovi

  • HTTP: Jezik weba. Koristimo GET za čitanje podataka i POST za slanje sigurnih informacija.
  • JSON: Format podataka. Izgleda kao jednostavna lista ključ-vrijednost parova.
  • Endpoint (Krajnja točka): Specifična web adresa koja vraća točno određene podatke.

Overview

The SudReg API provides high-performance access to the official Croatian Court Registry database. This guide covers everything from authentication to production-ready implementation examples.

Data Coverage

  • Legal entity identifiers (OIB, MBS)
  • Registered addresses and contact info
  • Primary and secondary activities (NKD)
  • Registration timeline and status history

Pregled

SudReg API omogućuje brz i pouzdan pristup podacima iz službenog Sudskog registra Hrvatske. Ovaj vodič pokriva sve od autentifikacije do primjera implementacije spremnih za produkciju.

Obuhvat podataka

  • Identifikatori pravnih osoba (OIB, MBS)
  • Adrese sjedišta i kontakt podaci
  • Djelatnosti po NKD klasifikaciji
  • Povijest upisa i statusi subjekata

Authentication

The API uses OAuth2 Client Credentials Flow. Secure your credentials and never expose them in client-side code.

1. Obtain Credentials

Register at sudreg-data.gov.hr to receive your CLIENT_ID and CLIENT_SECRET.

2. Exchange for Access Token

Autentifikacija

API koristi OAuth2 Client Credentials Flow. Osigurajte svoje pristupne podatke i nikada ih ne izlažite u klijentskom kodu.

1. Dobivanje vjerodajnica

Registrirajte se na sudreg-data.gov.hr kako biste dobili svoj CLIENT_ID i CLIENT_SECRET.

2. Razmjena za Access Token

POST https://sudreg-data.gov.hr/api/oauth/token
Authorization: Basic base64(CLIENT_ID:CLIENT_SECRET)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
Important: Tokens expire after 6 hours. Implement a caching layer to reuse tokens until they expire. Važno: Tokeni istječu nakon 6 sati. Implementirajte predmemoriju (cache) kako biste ponovno koristili tokene dok ne isteknu.

API Methods

API Metode

1. Get Subject Details by OIB

Endpoint: GET /detalji_subjekta?oib={OIB}

Fetches full data about a company using its 11-digit OIB.

1. Dohvat detalja subjekta po OIB-u

Krajnja točka: GET /detalji_subjekta?oib={OIB}

Dohvaća potpune podatke o tvrtki koristeći njezin 11-znamenkasti OIB.

GET /detalji_subjekta?oib=12345678901
Authorization: Bearer {access_token}

2. Search by MBS

Endpoint: GET /detalji_subjekta?mbs={MBS}

Search using the Court Registry Number (MBS).

2. Pretraga po MBS-u

Krajnja točka: GET /detalji_subjekta?mbs={MBS}

Pretraga koristeći Matični broj subjekta (MBS).

GET /detalji_subjekta?mbs=080123456
Authorization: Bearer {access_token}

3. Ukupan broj subjekata

Endpoint: GET /broj_subjekata

Returns the total number of companies in the registry.

3. Ukupan broj subjekata

Krajnja točka: GET /broj_subjekata

Vraća ukupan broj tvrtki u registru.

GET /broj_subjekata
Authorization: Bearer {access_token}

4. Get Latest Snapshot

Endpoint: GET /zadnji_snapshot

Get information about the most recent data export.

4. Zadnji snapshot

Krajnja točka: GET /zadnji_snapshot

Dohvatite informacije o najnovijem izvozu podataka.

GET /zadnji_snapshot
Authorization: Bearer {access_token}

Implementation Examples

Primjeri implementacije

// lib/sudreg.ts
export class SudregClient {
  private async getToken() {
    const creds = btoa(`${process.env.SUDREG_ID}:${process.env.SUDREG_SECRET}`);
    const res = await fetch('https://sudreg-data.gov.hr/api/oauth/token', {
      method: 'POST',
      headers: { 'Authorization': `Basic ${creds}` },
      body: 'grant_type=client_credentials'
    });
    return res.json();
  }
}
<?php
$ch = curl_init("https://sudreg-data.gov.hr/api/oauth/token");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, "grant_type=client_credentials");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Basic ' . base64_encode($id . ":" . $secret)
]);
$token = json_decode(curl_exec($ch))->access_token;
const axios = require('axios');

async function getCompany(oib) {
  const tokenRes = await axios.post(tokenUrl, 'grant_type=client_credentials', {
    headers: { Authorization: `Basic ${base64Creds}` }
  });
  
  return axios.get(`${baseUrl}/detalji_subjekta?oib=${oib}`, {
    headers: { Authorization: `Bearer ${tokenRes.data.access_token}` }
  });
}
@Injectable()
export class SudregService {
  constructor(private http: HttpClient) {}

  getSubject(oib: string) {
    return this.http.get(`${this.apiUrl}/detalji_subjekta`, {
      params: { oib }
    });
  }
}

Best Practices

Najbolje prakse

Rate Limiting & Caching

Ograničenje broja zahtjeva i Cache

Implement exponential backoff for retries and cache subject data for at least 24 hours to reduce load on the government server.

Implementirajte 'exponential backoff' za ponovne pokušaje i predmemorirajte podatke o subjektima na barem 24 sata kako biste smanjili opterećenje državnog poslužitelja.

Error Handling

Rukovanje greškama

Always check for 404 (subject not found) and 401 (token expired) responses as part of your core integration logic.

Uvijek provjeravajte 404 (subjekt nije pronađen) i 401 (token istekao) odgovore kao dio vaše osnovne logike integracije.

Additional Resources

Dodatni resursi