API dokumentacija

Sve što portal radi — radi i API. Bazna adresa: https://dpp.mcldhi.com, svi endpointi pod /api/v1/. Zahtevi i odgovori su JSON; datumi ISO-8601 UTC; identifikatori UUID.

Autentifikacija

Svaki poziv nosi API ključ u zaglavlju:

X-Api-Key: <vas-kljuc>

Ključeve kreirate u portalu (Podešavanja → API ključevi), sa obimom (scope) i rokom važenja; opoziv je trenutan. U bazi čuvamo samo SHA-256 heš — ključ se prikazuje samo jednom, pri kreiranju.

ScopeŠta dozvoljava
passports:readČitanje proizvoda, pasoša, verzija, exporta
passports:writeKreiranje/izmena proizvoda i pasoša, issue, import, webhook registracija
tenant_adminKorisnici, API ključevi, SSO podešavanje — samo za portal naloge

Rotacija ključeva: napravite novi ključ u portalu, zamenite ga u vašim sistemima, zatim opozovite stari — prekid je nula sekundi jer ključevi važe paralelno. Opoziv: opozvan ključ odmah dobija 401 na svim rutama. API pristup zahteva plan sa uključenim API-jem (Pro i Industrija); na planu bez API-ja ključ se ne može ni izdati.

Ograničenja brzine (rate limiting)

RutaLimitNapomena
Javni resolver (/01/…, /dpp/…) 60 zahteva/min po IP adresi QR skeniranja sa istog IP-ja
Login (/api/v1/auth/*) 10 zahteva/min po IP adresi zaštita od brute-force napada
Klijentski API (/api/v1/*) po planu: {n}/min (Pro) do {n}/min (Industrija) particionisano po API ključu

Prekoračenje limita vraća HTTP 429 sa zaglavljem Retry-After: 60 — odgovor je kratak JSON. Edge proxy dodatno ograničava serije zahteva (10 zahteva/s + dozvoljeni impuls); i on vraća 429.

Besplatni plan (free tier)

{n} pasoša · {n} korisnik · bez API pristupa — bez kartice, registracijom na portalu. Pokušaj kreiranja pasoša preko limita vraća 402 ({"error":"Plan 'free' dozvoljava najviše {n} pasoša…"}); granica se proverava atomski u bazi, pa ni paralelni zahtevi ne mogu da je pređu.

Primeri (curl)

Javni resolver — GS1 Digital Link (bez ključa):

curl https://dpp.mcldhi.com/01/08600012345001/21/SN-DEMO-0001

Kreiranje pasoša:

curl -X POST https://dpp.mcldhi.com/api/v1/passports \
  -H "X-Api-Key: VAS_KLJUC" -H "Content-Type: application/json" \
  -d '{"productId":"<uuid>","identifierId":"<uuid>",
       "schemaVersionId":"<uuid>","payload":{ "identification":{…} }}'

Registracija webhook endpointa:

curl -X POST https://dpp.mcldhi.com/api/v1/webhooks \
  -H "X-Api-Key: VAS_KLJUC" -H "Content-Type: application/json" \
  -d '{"url":"https://vas-server.example/hook","events":["passport.issued"]}'

Masovni uvoz (CSV/JSON):

curl -X POST https://dpp.mcldhi.com/api/v1/imports \
  -H "X-Api-Key: VAS_KLJUC" -F "file=@proizvodi.csv"

Katalog šema i grupa

MetodPutanjaOpis
GET/api/v1/schemas/groups Grupe proizvoda (baterije, tekstil, čelik…) sa pravnim osnovom
GET/api/v1/schemas?group=<kod> Objavljene verzije šema za grupu — schemaVersionId za kreiranje pasoša

Proizvodi

MetodPutanjaOpis
GET/api/v1/products Lista proizvoda sa identifikatorima i Digital Link adresama
POST/api/v1/products Novi proizvod: modelName, productGroupId, identifiers[] (scheme gs1_gtin/gs1_grai/iso15459, qualifierType: item/batch/model)

Pasoši

MetodPutanjaOpis
GET/api/v1/passports Lista pasoša (status, verzija, grupa)
POST/api/v1/passports Novi nacrt: productId, identifierId, schemaVersionId, payload (po šemi)
GET/api/v1/passports/{id} Detalj pasoša
PUT/api/v1/passports/{id} Izmena nacrta (samo dok je status draft)
GET/api/v1/passports/{id}/readiness Skor popunjenosti + lista polja koja nedostaju za izdavanje
POST/api/v1/passports/{id}/issue Izdavanje — pravi nepromenljivu verziju sa SHA-256 hešom
POST/api/v1/passports/{id}/withdraw Povlačenje pasoša (razlog se audit-uje)
GET/api/v1/passports/{id}/versions Sve izdate verzije sa heševima
GET/api/v1/passports/{id}/export?format=json|zip|aasx|dpp-package JSON-LD pasoš, ZIP paket, AASX (IDTA AAS v3) ili Portable DPP package v0.1.0 (Minespider Packager)
GET/api/v1/passports/{id}/qr QR kod pasoša (PNG)
POST + GET/api/v1/passports/{id}/events Post-purchase događaji (popravka, prenos vlasništva, reciklaža…) — javni u /dpp/{slug}/events i EPCIS; webhook: passport.lifecycle
Životni ciklus: draft → active → (withdrawn). Izdavanje je nepovratno — izmene posle izdavanja idu kroz novu verziju, a sve verzije ostaju trajno sačuvane i hešovane.

Dobavljači (prikupljanje podataka)

MetodPutanjaOpis
POST/api/v1/supplier-invites Poziv dobavljaču: passportId, ime, email, izabrana polja iz šeme, poruka, rok — vraća siguran link za unos
GET/api/v1/supplier-invites Lista poziva (sent / viewed / submitted / approved / rejected)
GET/api/v1/supplier-invites/{id} Detalj + unete vrednosti dobavljača
POST/api/v1/supplier-invites/{id}/approve Odobrenje — vrednosti se upisuju u nacrt pasoša na tražena polja
POST/api/v1/supplier-invites/{id}/reject Odbijanje sa razlogom
POST/api/v1/supplier-invites/{id}/resend Ponovno slanje poziva (isti link)
POST/api/v1/supplier-invites/{id}/cancel Poništavanje poziva — link prestaje da važi

Dobavljač ne pravi nalog: prima link /supplier/{token}, unese samo tražena polja, status teče sent → viewed → submitted → approved/rejected. Svaki korak se audit-uje; token u bazi postoji samo kao SHA-256 heš.

Dokumenti, grantovi, uvoz

MetodPutanjaOpis
POST/api/v1/documents Upload dokumenta (deklaracije, test izveštaji)
POST/api/v1/documents/{docId}/link/{passportId} Povezivanje dokumenta na pasoš (partner/authority nivo)
GET/POST /api/v1/passports/{id}/grants + POST isto Grantovi pristupa: kupcu/partneru date uvid u partner-nivo podatke
POST/api/v1/imports Masovni CSV uvoz proizvoda/pasoša

Webhooks

MetodPutanjaOpis
GET/POST /api/v1/webhooks Lista / registracija endpointa za događaje (izdavanje, povlačenje)
DELETE/api/v1/webhooks/{id} Uklanjanje
GET/api/v1/webhooks/deliveries Poslednje isporuke sa statusima (za dijagnostiku)
POST/api/v1/webhooks/{id}/test Probna isporuka na vaš endpoint

Nalog i izvoz svih podataka

MetodPutanjaOpis
GET/api/v1/me Podaci o firmi i planu
GET/api/v1/me/export Pun izvoz tenanta — ZIP sa svim proizvodima, pasošima, verzijama, dokumentima i audit tragom (no lock-in)
GET/POST /api/v1/me/api-keysUpravljanje ključevima
GET/POST /api/v1/me/usersKorisnici firme

Rezolucija (javno, bez ključa)

MetodPutanjaOpis
GET/dpp/{slug} Javna stranica pasoša (public nivo), sa hešom integriteta i 30 jezičkih izbora: pregledana SR/EN osnova; ostali jezici su nepregledani i koriste EN fallback za deo sadržaja
GET/01/{gtin}/21/{ser} itd. GS1 Digital Link rezolucija — sken QR koda sa proizvoda vodi na odgovarajući prikaz po nivou pristupa
GET/health Status sistema

MCP — Model Context Protocol (za AI agente)

Udaljeni MCP endpoint: POST /mcp, JSON-RPC 2.0. Bez instalacije i bez koda — Claude, GPT i drugi agenti se povezuju direktno. Javni alati rade bez ključa; tenant alati traže X-Api-Key zaglavlje. Detalji i primera: /connect-ai.

AlatPristupOpis
passport_resolvejavno Rezolucija pasoša po GTIN+serija ili linku
passport_verifyjavno Kriptografska provera heša i potpisa pasoša
epcis_documentjavno EPCIS 2.0 dokument pasoša (JSON-LD)
passport_listX-Api-Key Lista pasoša vašeg tenanta

Primer: {"jsonrpc":"2.0","id":1, "method":"tools/list"} vraća spisak alata; tools/call sa {"name":"passport_resolve","arguments":{"slug":"demo-0001"}} vraća pasoš.

Greške i konvencije