Povežite vašu platformu s diploma.ba

Pregled

Osnovna adresa je https://diploma.ba. Zahtjevi i odgovori su u JSON formatu. Svaki poziv se potpisuje vašim API ključem i radi samo s certifikatima vaše ustanove.

Brzi početak

1. Registrujte ustanovu i sačekajte da administrator odobri nalog.
2. Otvorite Profil, sekcija API pristup, i kliknite na generisanje ključa. Ključ se prikaže samo jednom, pa ga odmah kopirajte.
3. Spremite ključ na serveru vaše platforme, npr. u varijablu okruženja DIPLOMA_API_KEY.
4. Pošaljite probni zahtjev (ispod). U odgovoru dobijete verifyUrl: otvorite ga da vidite certifikat.

curl -X POST https://diploma.ba/api/v1/certificates \
  -H "Authorization: Bearer dpl_VAS_KLJUC" \
  -H "Content-Type: application/json" \
  -d '{
    "studentName": "Ime Prezime",
    "studentEmail": "student@example.com",
    "certificateType": "Napredni kurs programiranja",
    "identifier": "kurs-12-korisnik-345"
  }'

Napomena za Windows: u PowerShellu pišite curl.exe umjesto curl, i sve zahtjeve stavite u jednu liniju (bez znaka \ za novi red). Za lokalno testiranje koristite http://localhost:3000, ne https.

curl -X POST https://diploma.ba/api/v1/certificates \
  -H "Authorization: Bearer dpl_VAS_KLJUC" \
  -H "Content-Type: application/json" \
  --data-binary @podaci.json

Autentikacija

Svaki zahtjev mora imati zaglavlje Authorization s vašim ključem. Ključ počinje s dpl_, a ispred njega mora stajati riječ Bearer i razmak.

Authorization: Bearer dpl_VAS_KLJUC

• Ključ držite samo na serveru. Nikada ga ne stavljajte u kod koji se izvršava u browseru ili mobilnoj aplikaciji.
• Mi čuvamo samo hash ključa, pa ga ne možemo ponovo prikazati. Ako ga izgubite, generišite novi (stari odmah prestaje važiti).
• Ako sumnjate da je ključ procurio, opozovite ga ili zamijenite novim u profilu.

Izdavanje certifikata

Zaglavlja: Authorization i Content-Type: application/json. Tijelo zahtjeva:

Odgovor je 201 za novi certifikat, ili 200 s alreadyIssued: true ako taj certifikat već postoji:

{
  "success": true,
  "alreadyIssued": false,
  "certificateId": 123,
  "certificateHash": "3f2a…",
  "txHash": "0x9b1c…",
  "status": "active",
  "verifyUrl": "https://diploma.ba/verifikuj?hash=3f2a…"
}

Upis na blockchain traje nekoliko sekundi, pa postavite vremensko ograničenje zahtjeva na barem 60 sekundi. Sačuvajte certificateHash i verifyUrl uz zapis u vašoj bazi: hash vam treba za status i poništavanje.

Masovno izdavanje

Izdaje do 100 certifikata u jednom zahtjevu i upisuje ih na blockchain jednom transakcijom, pa je brže i jeftinije nego 100 pojedinačnih poziva. Koristite ga kada završi cijela generacija ili kurs.

curl -X POST https://diploma.ba/api/v1/certificates/bulk \
  -H "Authorization: Bearer dpl_VAS_KLJUC" \
  -H "Content-Type: application/json" \
  -d '{
    "certificateType": "Napredni kurs programiranja",
    "recipients": [
      { "studentName": "Ana Anić", "studentEmail": "ana@example.com", "identifier": "kurs-12-korisnik-1" },
      { "studentName": "Ben Benić", "studentEmail": "ben@example.com", "identifier": "kurs-12-korisnik-2" }
    ]
  }'

{
  "success": true,
  "issuedCount": 1,
  "alreadyIssuedCount": 1,
  "txHash": "0x9b1c…",          // null ako ništa nije izdato
  "results": [
    {
      "index": 0,                // mjesto primaoca u vašoj listi
      "alreadyIssued": true,
      "certificateId": 120,
      "certificateHash": "3f2a…",
      "txHash": "0x7e44…",
      "status": "active",
      "verifyUrl": "https://diploma.ba/verifikuj?hash=3f2a…"
    },
    {
      "index": 1,
      "alreadyIssued": false,
      "certificateId": 123,
      "certificateHash": "8c1d…",
      "txHash": "0x9b1c…",
      "status": "active",
      "verifyUrl": "https://diploma.ba/verifikuj?hash=8c1d…"
    }
  ]
}

• Sigurno za ponavljanje. Certifikati koji već postoje se preskaču i vraćaju s alreadyIssued: true, a izdaju se samo novi. Ako zahtjev padne ili ne znate je li prošao, pošaljite ga ponovo.
• Odgovor ima isti redoslijed kao lista koju ste poslali (index je mjesto u listi). Sačuvajte certificateHash i verifyUrl za svakog primaoca.
• Greška u jednom primaocu odbija cijeli zahtjev (status 400), a poruka kaže koji je primalac neispravan, npr. recipients[3].studentEmail. Ništa se tada ne izdaje.
• Emailovi se šalju nakon odgovora, jedan po jedan, pa za veću grupu mogu stizati i do minut-dvije. Šalju se samo za novoizdate certifikate.
• Ako testirate iz terminala, spremite JSON u UTF-8 datoteku i pošaljite je s --data-binary @podaci.json (vidi Brzi početak), da se č, ć, š, ž i đ ne pokvare.
• Ograničenje: 10 masovnih zahtjeva u minuti. Za više od 100 primalaca pošaljite više zahtjeva, kao u primjeru iznad.

Lista izdatih certifikata

Najnoviji certifikati su prvi. Svi parametri su opcioni i pišu se u adresu (query string):

curl "https://diploma.ba/api/v1/certificates?limit=50&status=active" \
  -H "Authorization: Bearer dpl_VAS_KLJUC"

{
  "success": true,
  "certificates": [ { … }, { … } ],
  "nextCursor": "98"      // null kada nema više stranica
}

Jedan odgovor sadrži najviše 100 certifikata, ali možete dohvatiti sve: ponavljajte zahtjev s cursor sve dok nextCursor ne bude null (cijeli primjer petlje je u poglavlju „Primjeri koda“).

Status jednog certifikata

Umjesto {certificateHash} upišite hash koji ste dobili pri izdavanju (64 znaka).

curl https://diploma.ba/api/v1/certificates/HASH_CERTIFIKATA \
  -H "Authorization: Bearer dpl_VAS_KLJUC"

{
  "success": true,
  "certificate": { … }   // objekat certifikata, vidi iznad
}

Objekat certifikata (isti je i u listi):

{
  "certificateId": 123,
  "certificateHash": "3f2a…",
  "studentName": "Ime Prezime",
  "studentEmail": "student@example.com",
  "certificateType": "Napredni kurs programiranja",
  "identifier": "kurs-12-korisnik-345",
  "metadata": {},
  "status": "active",
  "issuedAt": "2026-11-12T13:10:48.553Z",
  "expiresAt": null,
  "txHash": "0x9b1c…",
  "verifyUrl": "https://diploma.ba/verifikuj?hash=3f2a…"
}

Poništavanje certifikata

Tijelo zahtjeva nije potrebno.

curl -X POST https://diploma.ba/api/v1/certificates/HASH_CERTIFIKATA/revoke \
  -H "Authorization: Bearer dpl_VAS_KLJUC"

{
  "success": true,
  "alreadyRevoked": false,
  "certificateHash": "3f2a…",
  "status": "revoked"
}

• Certifikat se poništava na blockchainu i u našoj bazi, a stranica za provjeru ga odmah prikazuje kao poništenog.
• Poništavanje je trajno i ne može se poništiti.
• Ako je certifikat već poništen, dobijete status 200 s alreadyRevoked: true.

Greške i ograničenja

Kada nešto nije u redu, odgovor ima odgovarajući HTTP status i poruku u polju error:

{ "error": "Nevažeći ili nedostajući API ključ." }

Ograničenja po ustanovi:

• Izdavanje: 60 zahtjeva u minuti
• Masovno izdavanje: 10 zahtjeva u minuti (do 100 primalaca u svakom)
• Lista i status: 120 zahtjeva u minuti
• Poništavanje: 30 zahtjeva u minuti

Veći broj pogrešnih ključeva s iste IP adrese privremeno blokira daljnje pokušaje (status 429).

Primjeri koda

Node.js, izdavanje:

// Pozovite sa SERVERA vaše platforme, nikada iz browsera
async function izdajCertifikat(korisnik, kurs) {
  const res = await fetch('https://diploma.ba/api/v1/certificates', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.DIPLOMA_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      studentName: korisnik.punoIme,
      studentEmail: korisnik.email,
      certificateType: kurs.naziv,
      identifier: `kurs-${kurs.id}-korisnik-${korisnik.id}`,
    }),
  });

  const data = await res.json();
  if (!res.ok) throw new Error(data.error);   // 400, 401, 403, 429, 502, 500

  // Sačuvajte ova dva podatka uz zapis "položio kurs" u vašoj bazi
  return { hash: data.certificateHash, verifyUrl: data.verifyUrl };
}

Node.js, masovno izdavanje za cijelu listu polaznika:

// Izdaje certifikate za cijelu listu polaznika, u grupama od po 100
async function izdajSve(polaznici, kurs) {
  const rezultati = [];

  for (let i = 0; i < polaznici.length; i += 100) {
    const grupa = polaznici.slice(i, i + 100);

    const res = await fetch('https://diploma.ba/api/v1/certificates/bulk', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.DIPLOMA_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        certificateType: kurs.naziv,
        recipients: grupa.map((p) => ({
          studentName: p.punoIme,
          studentEmail: p.email,
          identifier: `kurs-${kurs.id}-korisnik-${p.id}`,
        })),
      }),
    });

    const data = await res.json();
    if (!res.ok) throw new Error(data.error);   // sigurno je ponoviti istu grupu

    // results ima isti redoslijed kao grupa
    data.results.forEach((r, k) => rezultati.push({ korisnik: grupa[k], ...r }));
  }
  return rezultati;
}

Node.js, dohvat svih certifikata:

// Dohvaća SVE certifikate vaše ustanove, stranicu po stranicu
async function sviCertifikati() {
  const svi = [];
  let cursor = null;

  do {
    const url = new URL('https://diploma.ba/api/v1/certificates');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.DIPLOMA_API_KEY}` },
    });
    const data = await res.json();
    if (!res.ok) throw new Error(data.error);

    svi.push(...data.certificates);
    cursor = data.nextCursor;      // null na zadnjoj stranici
  } while (cursor);

  return svi;
}

Node.js, poništavanje:

async function ponistiCertifikat(hash) {
  const res = await fetch(`https://diploma.ba/api/v1/certificates/${hash}/revoke`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.DIPLOMA_API_KEY}` },
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error);
  return data;   // { success: true, alreadyRevoked: false|true, status: 'revoked' }
}

Python, izdavanje:

import os, requests

res = requests.post(
    "https://diploma.ba/api/v1/certificates",
    headers={"Authorization": f"Bearer {os.environ['DIPLOMA_API_KEY']}"},
    json={
        "studentName": "Ime Prezime",
        "studentEmail": "student@example.com",
        "certificateType": "Napredni kurs programiranja",
        "identifier": "kurs-12-korisnik-345",
    },
    timeout=60,   # upis na blockchain može potrajati nekoliko sekundi
)
data = res.json()
res.raise_for_status()
print(data["verifyUrl"])

Česta pitanja