eStudium.eu

Identifikátory, organizace a API PIVO

<!-- Autor programu: PB <pavel.bartos.pb@gmail.com> -->

Osoby, organizace a identifikátory

Vizitky, krátké adresy a přihlášení

Veřejnou vizitku osoby otevřete přímo na adrese

https://update.estudium.eu/CAR-0000-0002, organizaci například na

https://update.estudium.eu/CORE-00001. Uvedená ID jsou příklady; použijte

identifikátor přidělený konkrétnímu účtu. Změna zobrazovaného jména ID ani adresu

vizitky nemění. Vizitka je dostupná jen u aktivního účtu se souhlasem se zveřejněním.

Článek nebo kniha s PIVO má adresu https://update.estudium.eu/PIVO-0-0000-0001.

Publikace bez PIVO používá přímo své stávající 32znakové ID za doménou. Její adresu

zkopírujete z odkazu Otevřít v katalogu nebo vizitce. Krátká adresa sama

nepřiděluje PIVO: to nadále vydává pouze organizace. Staré odkazy

/profile.php?id=…, /pivo.php?id=… a /article.php?id=… přesměrují HTTP 301.

Canonical, sitemap.xml i publikační feed.xml používají nové adresy. Software

zůstává na adrese /login/projekt, například /admin/eweb-server.

Při přihlášení zadejte login, CAR nebo CORE a běžné heslo daného účtu.

U CAR/CORE nezáleží na velikosti písmen. Identifikátor je veřejný a heslo nenahrazuje;

zablokovaný účet se nepřihlásí. Minimální délka nového hesla je 10 znaků.

V Můj účet → Moje vizitka přetáhněte fotografii nebo logo do vyznačeného pole,

nebo vyberte soubor tlačítkem. Podporován je jeden PNG, JPEG nebo WebP do 512 KiB,

rozměry nejvýše 4000 × 4000 px. Náhled se zobrazí hned, změnu dokončíte tlačítkem

Uložit vizitku. Stejně se potvrzuje odstranění fotky. Chyba souboru se zobrazí

přímo u pole; platnost obrázku ověřuje i server.

Vizitka obsahuje kompaktní hlavičku, kontakty a identifikátory, vzdělání nebo

kategorii činnosti, organizace a vyplněné CV. E-mail, telefon a další volitelné

kontakty se zobrazí pouze podle zaškrtnutých voleb zveřejnění. Logo organizace se

zobrazuje celé. Prázdné CV se nevypisuje.

V Projekty autora / Projekty organizace je společný přehled veřejného softwaru,

knih, článků a dalších publikací účtu. Tlačítka filtrují typ; pro hledání a

indexování jsou všechny karty obsažené už ve stránce bez JavaScriptu. Typ publikace

zvolíte při jejím vložení do účtu nebo do PIVO. Katalog slučuje rozpoznané duplicity.

Samotné uvedení stejného jména mezi autory nepřidá cizí publikaci do vašeho účtu:

přidejte ji do vlastních publikací, případně odkazem na existující PIVO.

Neveřejné a archivované softwarové projekty do veřejného přehledu nevstupují.

Rychlý postup pro odborné časopisy (research journals)

CAR označuje osobu, CORE vydavatele/organizaci a PIVO konkrétní publikovaný výstup.

CAR a CORE se přidělují automaticky při vytvoření účtu, při veřejné registraci

stejně jako při založení administrátorem. Osoba dostane CAR, organizace CORE,

bez ohledu na její roli admin/registrovaný nebo zveřejnění vizitky. Starším účtům

se chybějící ID doplní při prvním požadavku. Uživatel ID nezadává ani nemění.

vydavatele. Do názvu napište veřejný název vydavatele, vyplňte logo,

registrační číslo, kategorii činnosti a případně existující ROR. Organizace

ihned získá CORE; pokud administrátor nastavil dočasné heslo, nejprve je změňte.

mohou požádat o členství. Vydavatel žádost schválí v Členové organizace.

Členství ani přístup spolupracovníka k projektům nedává právo vydávat PIVO:

PIVO vytváří přihlášený organizační účet nebo jeho serverový API klíč.

Správa PIVO → Registrovat PIVO. Zadejte titul, autory oddělené středníkem,

měsíc/rok vydání, anotaci, klíčová slova a veřejnou URL článku nebo vlastní PDF.

Doplňte název časopisu, ISSN, ročník, číslo, strany a licenci. Jeden vydavatel

může obsluhovat více časopisů; rozliší je metadata journal a issn.

v issuer_core; žádný prefix si časopis nerezervuje a číselná řada se pro každou

organizaci nerestartuje. V databázi se uloží vydavatel, ID, metadata a revize.

stránce článku a v PDF. Autor může existující PIVO přidat do své publikace;

tím znovu nevydává nové ID. Katalog propojí duplicitní záznamy stejného díla.

revizi a úplná metadata. Opravdu stažený článek označte akcí withdraw a důvodem;

zůstane veřejná stránka se stavem, nikoli znovu použitelné číslo.

Napojení redakčního systému přes API

V organizaci otevřete Správa PIVO → API klíče → Vytvořit API klíč. Hodnotu

uložte jen na serveru redakčního systému. Není určena do JavaScriptu návštěvníka.

Příklad níže předpokládá proměnnou prostředí PIVO_TOKEN s tímto klíčem.

curl --request POST 'https://update.estudium.eu/pivo-api.php' \
  --header "Authorization: Bearer $PIVO_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: journal-2026-article-0042' \
  --data '{"action":"create","metadata":{"title":"Example journal article","authors":"Novak, Jan; Smith, Eva","publication_date":"2026-09","abstract":"A complete public abstract of the article.","keywords":"education; research; learning analytics","type":"article","journal":"Example Research Journal","issn":"0378-5955","volume":"4","issue":"2","pages":"10-21","publisher":"Example Publisher","url":"https://journal.example.org/articles/42","language":"en","license":"CC BY 4.0"}}'

Příklad úspěšné odpovědi (zkrácený; skutečné ID určí registr):

{"ok":true,"created":true,"record":{"id":"PIVO-0-0000-0001","sequence":1,"issuer_core":"CORE-00001","revision":1,"status":"published","url":"https://update.estudium.eu/pivo.php?id=PIVO-0-0000-0001"}}

Do redakční databáze uložte record.id, record.url a record.revision.

Při timeoutu opakujte stejný požadavek se stejným Idempotency-Key a metadaty:

registr vrátí již přidělené ID. Nový článek musí mít jiný klíč. Detail bez hesla:

GET /pivo-api.php?id=PIVO-0-0000-0001. Změny se posílají POST na stejný endpoint

s action: update nebo action: withdraw; úplné příklady a chybové kódy jsou níže.

eUpdate automaticky nevkládá ID do cizího redakčního systému ani nemění jeho PDF.

Pro OJS nebo jiný research journal je potřeba serverová integrace, která zavolá

API po zveřejnění článku a uloží odpověď. PIVO není DOI Crossref/DataCite a samotné

vydání neznamená recenzní řízení ani zařazení časopisu do externího indexu.

Klíčová slova zadávejte jako výzkum; vzdělávání; umělá inteligence. V editoru

středník nebo Enter vytvoří samostatný štítek; vložený seznam se rozdělí ihned.

Křížek odebere štítek. Víceslovné fráze zůstávají pohromadě. API přijímá tentýž

řetězec se středníky nebo pole řetězců. Čárka uvnitř fráze se nerozděluje.

Limit je 30 klíčových slov po nejvýše 100 znacích; prázdné položky a přesné

opakované hodnoty se vynechají.

Registrace nabízí Osoba nebo Firma / škola / organizace. Organizace zadává

název, druh, kategorii činnosti, IČO nebo jiné registrační číslo, stát, právní formu

a sídlo. V profilu nahraje logo a popis. Má vlastní projekty, verze, moduly,

spolupracovníky a publikace stejně jako osobní účet. Typ účtu se po registraci

nemění; pro organizaci založte samostatný účet. Login slouží k přihlášení, název

organizace může obsahovat mezery a diakritiku. Kontaktní e-mail zůstává neveřejný,

dokud jeho zveřejnění výslovně nepovolíte. Ostatní vyplněná profilová data jsou

veřejná při souhlasu s veřejnou vizitkou.

CAR, CORE a ORCID/ROR

například CAR-0000-0001.

například CORE-00001.

například PIVO-0-0000-0001.

Každá řada začíná pořadovým číslem 1 a přidává 2, 3, 4… Číslo se kóduje v base36

(0–9, A–Z) a doplní nulami: 9 → 00009, 10 → 0000A. CAR má 8 znaků, CORE 5 a PIVO

9 znaků; pomlčky pouze člení zápis. První znak za PIVO je součástí čísla, nikoli

číslo vydavatele. Kapacity včetně nulového kódu jsou 36^8 = 2 821 109 907 456,

36^5 = 60 466 176 a 36^9 = 101 559 956 668 416. Nulový identifikátor se nepřiděluje.

Číselné řady jsou globální v této instalaci, přidělování probíhá pod databázovým

zámkem v transakci. Identifikátory jsou neměnné a po smazání účtu se nepoužijí znovu.

Stávající účty obdrží CAR automaticky při prvním spuštění nové verze.

CAR a CORE lze vyhledat v komunitě. Resolver /identity.php?id=CAR-0000-0001

odkáže na veřejnou vizitku; neveřejná vizitka se neodhalí. Zaniklý účet vrátí 410.

ORCID se zadává pro osobu; u organizace jde o ORCID kontaktní osoby.

ROR označuje organizaci; osoba ho může uvést jako související instituci.

Příklady: https://orcid.org/0000-0002-1825-0097, https://ror.org/02mhbdp94.

eUpdate kontroluje formát a kontrolní součet, nové ORCID/ROR nevydává a neověřuje

vlastnictví účtu u externího registru. Zdroj specifikací:

ORCID,

ROR.

Členství osob v organizacích

Osoba v Moje organizace zadá login nebo e-mail organizace. Žádost čeká na

schválení. Jedna osoba může patřit do více organizací. Organizace v **Členové

organizace** vidí žádosti i přijaté členy; může člena potvrdit, odstranit nebo

samostatně povolit spolupráci. Přístup ke všem projektům organizace vznikne až

po povolení spolupráce. Odstranění člena nebo odchod osoby jej okamžitě odebere.

Samotné zadání ROR ani žádost o členství žádná projektová práva nevytváří.

Schválené členství se zobrazí na veřejné vizitce osoby, pokud je veřejná i organizace.

Publikace a PDF

Osoba i organizace mohou přidávat publikace s názvem, autory, rokem, typem,

vydavatelem, ISBN, ISSN, DOI, jazykem, licencí, abstraktem, URL, odkazem na Google

Scholar a existujícím PIVO ID. ISBN a ISSN se kontrolují včetně kontrolní číslice.

DOI se zde pouze eviduje, neregistruje. Nahrávat lze pouze PDF do 20 MiB, celkem

500 MiB na účet. Upload probíhá po částech; nedokončené a nepřipojené soubory jsou

neveřejné. Veřejně lze PDF stáhnout po uložení do aktivní veřejné vizitky nebo

publikovaného PIVO záznamu. PDF se stahuje jako příloha, nespouští se na serveru.

Kontrola formátu nenahrazuje antivirovou kontrolu.

V PDF úložiště lze uklidit nedokončené uploady a nepoužité soubory. PDF připojené

k vizitce nejprve odpojte a vizitku uložte. PDF, které je součástí PIVO, se chrání

před smazáním. Do souboru nepatří neveřejné osobní údaje; zveřejňujte pouze obsah,

ke kterému máte potřebné oprávnění.

PIVO: veřejný katalog a API

Katalog /pivo.php je veřejný, má hledání a stránkování. Každý záznam má stabilní

stránku /pivo.php?id=PIVO-0-0000-0001, JSON a položku v sitemap. Profilové stránky

používají Person/Organization a záznamy CreativeWork/ScholarlyArticle ve strukturovaných

datech. Výsledky hledání se neindexují; veřejně připojené PDF lze indexovat.

PIVO vydávají přihlášené organizace v Správa PIVO nebo přes API. Povinná jsou

metadata: název, autoři, měsíc/rok, anotace, keywords a cílová HTTP/HTTPS URL nebo vlastní nahrané PDF.

Vydavatel potvrzuje předané údaje; název registru **neznamená recenzní posudek ani

ověření vědecké kvality**. PIVO je vlastní registr eUpdate, není DOI, Crossref ani

DataCite. Dostupnost resolveru závisí na provozu update.estudium.eu.

Vydavatel může měnit metadata a cílovou adresu, ID zůstane stejné. Uchová se historie

revizí. Stažení záznamu vyžaduje důvod a je nevratné: stránka a ID zůstanou veřejné

jako záznam o stažení. PIVO nesmaže ani zánik účtu vydavatele. Po registraci proto

neuvádějte do metadat údaje, které nemají být trvale veřejné.

Čtení bez přihlášení

curl 'https://update.estudium.eu/pivo-api.php?q=research&offset=0'
curl 'https://update.estudium.eu/pivo-api.php?id=PIVO-0-0000-0001'

Seznam vrací records, total, offset, limit (50); další strana má offset=50.

Detail vrací record a seznam revizí. Pole sequence je pořadové číslo v desítkové

soustavě, issuer_core identifikátor vydavatele, revision aktuální revize.

API klíč a vytvoření záznamu

Organizace vytvoří klíč v Správa PIVO → API klíče. Tajná hodnota se ukáže jen

jednou. V databázi se uchová pouze hash. Klíč platí 90 dní; lze jej ihned zneplatnit.

Organizace může mít 10 aktivních klíčů, každý s limitem 120 úspěšných změn za hodinu.

Klíč dovoluje pouze PIVO operace jménem svého vydavatele, ne správu účtů či projektů.

Blokovaný nebo odstraněný účet jej nemůže používat. Posílejte jej v Authorization,

nikdy jako parametr URL. API používá HTTPS a Content-Type: application/json.

curl -X POST 'https://update.estudium.eu/pivo-api.php' \
  -H "Authorization: Bearer $PIVO_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: journal-2026-article-001' \
  --data '{"action":"create","metadata":{"title":"Example research output","authors":"Jane Doe; John Smith","publication_date":"2026-09","keywords":["education"],"type":"article","publisher":"Example School","url":"https://example.org/article","language":"en","license":"CC BY 4.0","abstract":"An example record."}}'

Úspěch: HTTP 201 a {"ok":true,"created":true,"record":{...}}.

Stejný Idempotency-Key se stejnými metadaty vrátí původní ID (HTTP 200), jiný obsah

pod stejným klíčem vrátí 409. Klíč má 1–100 znaků a–z, A–Z, 0–9, tečka, dvojtečka,

pomlčka nebo podtržítko. Lze jej předat i v JSON jako idempotency_key.

Aktualizace a stažení

POST na stejnou URL; klíč zůstává v Authorization. Před aktualizací načtěte detail.

Pro update pošlete úplná metadata, nikoli pouze změněné pole.

{"action":"update","id":"PIVO-0-0000-0001","revision":1,"metadata":{"title":"Updated title","authors":"Jane Doe","abstract":"Updated complete abstract.","publication_date":"2026-09","keywords":["education"],"url":"https://example.org/new-location"}}
{"action":"withdraw","id":"PIVO-0-0000-0001","revision":2,"reason":"Duplicate publication"}

Nesprávná revize vrátí 409; tím se chrání souběžné úpravy. Cizí záznam nelze měnit.

Historie je dostupná ve stránce záznamu, JSON vrací čísla a data předchozích revizí.

PDF a API

Veřejné API PIVO přijímá odkaz nebo metadata.file_id vlastního hotového uploadu.

PDF nahrajte v přihlášeném webovém formuláři; Bearer klíč nepovoluje upload souborů.

Tím je oddělena velikostní kvóta a právo publikovat soubor od registrace metadat.

Pro čistě serverovou integraci použijte veřejnou URL publikace na vlastním serveru.

Chyby a provoz

Odpovědi mají JSON ok a při chybě error. Stavy: 401 neplatný/expirující klíč,

403 cizí záznam nebo chybný typ účtu, 404 nenalezeno, 409 konflikt klíče/revize,

422 neplatná metadata, 429 limit, 503 nedostupné úložiště. Čtení je GET, změny POST.

Neznámá HTTP metoda vrací 405. JSON specifikace API:

OpenAPI.

Registr, členství, metadata PDF a hashe klíčů jsou v MySQL. PDF jsou mimo veřejný

web v private/update-data/publications. Úplná interní záloha obsahuje SQL logický

stav včetně řad a všechny PDF. Obnovujte nejnovější zálohu; starý snímek registru

nesmí nahradit novější přidělené identifikátory. Při stěhování zachovejte adresu

resolveru nebo nastavte trvalá přesměrování. Před nasazením si uložte aktuální zálohu.

Proč PIVO používat a jak začít

PIVO dává výstupu stálou adresu oddělenou od umístění PDF. Když soubor přesunete,

upravíte cílovou URL a citace se starým PIVO odkazem mohou dál vést na správný

záznam. Registr propojí článek s vydavatelem CORE, nabídne metadata, citace a

historii. Hodí se například pro školní studie, výzkumné zprávy a institucionální

publikace. PIVO samo nevytváří prestiž, recenzní řízení ani indexaci v databázích.

Postup: založte účet organizace, vyplňte vizitku, otevřete Správa PIVO a registrujte

výstup. Autor článku musí zadat **nadpis, autora/autory, měsíc a rok vydání,

anotaci a klíčová slova**; PIVO navíc potřebuje URL nebo PDF. Každý autor má být

uveden samostatně středníkem, ideálně Novák, Jan; Svobodová, Eva. Institucionálního

autora zapište například {Example School}. Neuvádějte akademické tituly mezi jména.

Datum formulář zadává po měsících; API přijímá 2026-09 i 09/2026, ukládá 2026-09.

keywords může být pole řetězců nebo text oddělený středníky; maximum je 30 položek.

Starší záznamy zůstávají zachované, při jejich editaci je nutné chybějící údaje doplnit.

Vyhledávač, citace a duplicity

Na /articles.php jsou veřejné publikace osob a organizací i PIVO. Hledat lze podle

názvu, anotace, klíčových slov, autora/CAR/ORCID a organizace/CORE/ROR. Samostatná

stránka článku nabízí citace APA 7, IEEE a ISO 690, BibTeX a RIS. Odkaz a citace

lze kopírovat nebo stáhnout. Pro přesnější citaci doplňte časopis, ročník, číslo a

strany. Generované citace vycházejí ze zadaných jmen a údajů; zkontrolujte je podle

požadavků cílového časopisu. BibTeX/RIS lze importovat do citačních manažerů.

Stejný DOI, PIVO, kontrolní součet PDF nebo přesná shoda názvu, autorů a měsíce bez

DOI sloučí výsledky do jedné položky. Přednost má záznam PIVO. Původní publikace se

fyzicky nemažou a duplicitní URL odkáže na zvolený záznam. Různé DOI se samy podle

podobného názvu neslučují. Registrace dalšího PIVO pro rozpoznaný stejný výstup vrátí

409 s existujícím identifikátorem. Idempotency-Key řeší opakování téhož API požadavku.

Devět nejnavštěvovanějších článků se počítá za vybraný kalendářní měsíc, výchozí

je aktuální měsíc v pásmu Europe/Prague. Přepínačem lze zobrazit minulá období.

Celkové návštěvy jsou oddělené. Opakované otevření stejným návštěvníkem během hodiny

v daném měsíci se počítá jednou, rozpoznatelní roboti se nezapočítají. Jde o měřenou

návštěvnost detailu, nikoli citační ohlas nebo ověření kvality. Bez návštěv je

žebříček prázdný; při menším počtu navštívených článků zobrazí méně než devět položek.

Google Scholar a další platformy

Stránky článků mají čitelnou anotaci bez přihlášení a Highwire citation_* metadata

pro název, jednotlivé autory, rok, časopis a dostupné PDF. To připravuje web pro

procházení Scholarem; přijetí článku do indexu nelze slíbit. Pro Scholar je vhodné

plnotextové PDF s vyhledatelným textem, názvem, autory a literaturou; jeho doporučený

limit je 5 MB, přestože eUpdate dovoluje nahrát 20 MiB. Podmínky popisuje

Google Scholar.

Odkaz „Google Scholar“ na článku hledá jeho název, neodesílá žádost o registraci.

Zotero může načíst vložená metadata; další citační manažery mohou použít BibTeX nebo

RIS. Podrobnosti pro Zotero.

PIVO URL lze sdílet na webu organizace, v profilu autora nebo na jiných platformách.

eUpdate se bez zvláštní integrace nepřihlašuje k ORCID ani neodesílá metadata do

Crossref, DataCite, Scopus či Web of Science.

Rozšířený příklad API

{
  "action": "create",
  "idempotency_key": "study-2026-09-001",
  "metadata": {
    "title": "Example educational research",
    "authors": "Doe, Jane; Smith, John",
    "publication_date": "2026-09",
    "abstract": "A complete author-written abstract of this study.",
    "keywords": ["education", "learning analytics"],
    "type": "article",
    "journal": "Example Journal",
    "volume": "2",
    "issue": "1",
    "pages": "10-19",
    "url": "https://example.org/research",
    "language": "en"
  }
}

Čtení sjednoceného katalogu a citací:

curl 'https://update.estudium.eu/article-api.php?q=education&month=2026-09'
curl 'https://update.estudium.eu/article-api.php?author=CAR-0000-0001'
curl 'https://update.estudium.eu/article-api.php?organization=CORE-00001'
curl 'https://update.estudium.eu/article-api.php?id=PIVO-0-0000-0001'
curl 'https://update.estudium.eu/citation.php?id=PIVO-0-0000-0001&format=bibtex'

Katalog vrací records, total, offset, limit, month, timezone a top.

Položka má views za celou dobu, month_views pro vybraný měsíc a monthly_views

po měsících. Detail obsahuje article a citations. Formáty citací: apa, ieee,

iso690, bibtex, ris. Odkazy na neveřejné články a PDF bez veřejné vazby vrací 404.

Veřejné PDF může vyhledávač indexovat; soukromé PDF zůstává za kontrolou oprávnění.

RSS publikací a projektů v češtině i angličtině

Veřejné kanály RSS CZ a RSS EN obsahují každý

nejvýše 130 položek: 100 naposledy aktualizovaných veřejných publikací, článků

a PIVO a 30 nejnovějších veřejných nearchivovaných projektů. Každý projekt je

zastoupen jednou, s verzí vybranou podle nejnovějšího data vydání. Chybí-li datum

vydání, použije se čas nahrání verze; u projektu bez verzí datum vytvoření.

Moduly se samostatně nevkládají. Celý kanál je seřazen od nejnovější položky.

Jazykové varianty mají přeložený název, popis a kategorie kanálu i odpovídající

značku language. Obsahují stejné záznamy; vložené názvy, anotace a autorské texty

se automaticky nepřekládají. V administraci má každý kanál datum aktualizace,

náhled a odkaz; Přegenerovat RSS obnoví obě varianty.

Oba kanály se přegenerují při změně publikace, PIVO, veřejného profilu, projektu,

vydání, viditelnosti či archivace a při změně loginu vlastníka. Po aktualizaci

aplikace se nové RSS vytvoří automaticky při prvním požadavku. Nezměněné

požadavky soubory opakovaně nepřepisují.

Duplicity publikací se slučují stejně jako v katalogu. Neveřejné publikace,

stažené PIVO a soukromé či archivované projekty se vynechávají. Položka obsahuje

název, popis, autora, kategorii, trvalý odkaz a u publikací dostupné veřejné PDF

jako enclosure. pubDate určuje datum řazení; dc:date uchovává zadané datum

vydání. GUID je kanonická URL záznamu. Čtení RSS nezvyšuje návštěvnost článků.

Čtečka může uchovat již stažené položky i po jejich odebrání z kanálu.

RSS samo nezajišťuje zařazení do Google Scholar.