API za developere

Dokumentacija za korištenje API-ja za provjeru AMS DNS zapisa

Pregled

AMS Check API omogućava provjeru DNS NAPTR zapisa za informacijske posrednike prema tehničkoj specifikaciji eRačun. API provjerava registraciju posrednika u sustavu AMS (Adresar metapodatkovnih servisa) putem DNS upita.

Bazni URL: http://provjera-posrednika.online

Endpoint

POST /api/ams-check

Endpoint prima POST zahtjev s JSON tijelom i vraća rezultate provjere DNS NAPTR zapisa.

Zahtjev (Request)

Headers

Content-Type: application/json

Body parametri

Parametar	Tip	Obavezno	Opis
identifierType	"oib" \| "gln"	Da	Tip identifikatora: OIB ili GLN broj
identifier	string	Da	Vrijednost identifikatora (OIB ili GLN broj)
environment	"demo" \| "prod"	Da	Okolina: demo ili prod

Primjer zahtjeva

{
  "identifierType": "oib",
  "identifier": "12345678901",
  "environment": "prod"
}

Odgovor (Response)

Uspješan odgovor (200 OK)

{
  "success": true,
  "dnsName": "ABC123...XYZ.iso6523-actorid-upis.prod.ams.porezna-uprava.hr",
  "participantId": "9934:12345678901",
  "naptrRecords": [
    {
      "order": 100,
      "preference": 10,
      "flags": "U",
      "services": "ERACUN:meta",
      "regularExpression": "!^.*$!https://example.com/mps!",
      "mpsUrl": "https://example.com/mps",
      "url": "example.com",
      "isValid": true
    }
  ],
  "dnsNameDetails": {
    "canonicalId": "9934:12345678901",
    "sha256Hash": "abc123...",
    "base32Encoded": "ABC123...XYZ=",
    "base32Trimmed": "ABC123...XYZ"
  }
}

Polja odgovora

Polje	Tip	Opis
success	boolean	Uspješnost provjere
errorMessage	string?	Poruka greške (ako postoji)
dnsName	string?	Formirano DNS ime
participantId	string?	ID sudionika (npr. "9934:12345678901")
naptrRecords	array	Pronađeni NAPTR zapisi
dnsNameDetails	object?	Detalji formiranja DNS imena

NAPTR Record struktura

{
  "order": number,           // Redoslijed zapisa
  "preference": number,      // Preferencija zapisa
  "flags": string,           // Flagovi (mora biti "U")
  "services": string,        // Servisi (npr. "ERACUN:meta")
  "regularExpression": string, // Regexp izraz
  "mpsUrl": string,          // URL izvučen iz regexp-a
  "url": string,             // Domena iz URL-a
  "isValid": boolean         // Je li zapis valjan
}

Greške

400 Bad Request

Nedostaju potrebni parametri ili su neispravni.

{
  "success": false,
  "errorMessage": "Nedostaju potrebni parametri."
}

429 Too Many Requests

Previše zahtjeva u kratkom vremenu (rate limiting).

{
  "success": false,
  "errorMessage": "Previše česti zahtjevi. Molimo pričekajte 3 sekundi..."
}

500 Internal Server Error

Greška na serveru.

{
  "success": false,
  "errorMessage": "Greška pri provjeri: ..."
}

Ograničenje brzine (Rate Limiting)

API ima implementirano ograničenje brzine zahtjeva kako bi se spriječila preopterećenja.

Minimalni interval između zahtjeva: 5 sekundi
Ograničenje se primjenjuje po IP adresi
Prekoračenje rezultira HTTP 429 statusom

Primjeri koda

JavaScript / TypeScript (fetch)

const response = await fetch('/api/ams-check', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    identifierType: 'oib',
    identifier: '12345678901',
    environment: 'prod'
  })
});

const data = await response.json();

if (data.success) {
  console.log('DNS ime:', data.dnsName);
  console.log('NAPTR zapisi:', data.naptrRecords);
} else {
  console.error('Greška:', data.errorMessage);
}

cURL

curl -X POST https://your-domain.com/api/ams-check \
  -H "Content-Type: application/json" \
  -d '{
    "identifierType": "oib",
    "identifier": "12345678901",
    "environment": "prod"
  }'

Python (requests)

import requests

response = requests.post(
    'https://your-domain.com/api/ams-check',
    json={
        'identifierType': 'oib',
        'identifier': '12345678901',
        'environment': 'prod'
    }
)

data = response.json()

if data['success']:
    print(f"DNS ime: {data['dnsName']}")
    print(f"NAPTR zapisi: {data['naptrRecords']}")
else:
    print(f"Greška: {data['errorMessage']}")

Tehnički detalji

Formiranje DNS imena

Kanonski oblik: <scheme_code>:<identifier>
SHA256 hashiranje kanonskog oblika
BASE32 enkodiranje (RFC 4648)
Uklanjanje pratećih znakova '='
Formiranje DNS imena: <base32>.iso6523-actorid-upis.<env>.ams.porezna-uprava.hr

NAPTR zapisi

Flag mora biti "U"
Service mora sadržavati "ERACUN" ili "ERACUN:meta"
URL se izvlači iz regexp polja: !^.*$!URL!

DNS serveri

API koristi sljedeće DNS servere za provjeru:

dns1.hitronet.hr
dns2.hitronet.hr

Dokumentacija prema tehničkoj specifikaciji eRačun - AMS (Adresar metapodatkovnih servisa)