API – Übersicht

Die REST-API des EPflicht-Portals erlaubt das Anlegen, Abrufen und Einreichen von Einlieferungen (aktuell: Monographien) sowie das Abrufen von Referenzdaten.

Basis-URL

Alle Endpunkte liegen unter dem Präfix /api/.

Authentifizierung

Schreibende und einlieferungsbezogene Endpunkte erfordern einen API-Schlüssel, der im Header X-API-Key mitgesendet wird:

curl https://<host>/api/monographs \
  -H "X-API-Key: <Ihr-Schlüssel>"

API-Schlüssel werden im Lieferantenkonto unter den Kontoeinstellungen erstellt und verwaltet. Der Schlüssel wird nur einmal bei der Erstellung im Klartext angezeigt – bewahren Sie ihn sicher auf.

Referenzdaten-Endpunkte

Die reinen Lese-Endpunkte für Referenzdaten (z. B. /api/doc-types, /api/languages) sind ohne Authentifizierung abrufbar.

Referenzdaten (IDs nachschlagen)

Beim Anlegen einer Monographie werden Fremdschlüssel als ganzzahlige IDs erwartet (z. B. doc_type_id, file_format_id, role_id). Diese IDs sind pro Installation unterschiedlich und müssen vorab abgefragt werden.

Alle benötigten Referenzlisten lassen sich gebündelt abrufen:

curl https://<host>/api/monographs/related-fields

Oder einzeln über die jeweiligen Endpunkte:

Endpunkt	Liefert IDs für
`GET /api/doc-types`	`doc_type_id`
`GET /api/file-formats`	`file_format_id`
`GET /api/access-rights`	`access_right_archive_object_id`
`GET /api/access-status`	`access_status_id`
`GET /api/languages`	`language_id`, `language_other_ids` (String-Codes, z. B. `"ger"`)
`GET /api/person-roles`	`role_id` (Personen)
`GET /api/organisation-roles`	`role_id` (Organisationen)
`GET /api/publisher-names`	`name_id` (Verlage)
`GET /api/ddcs`	`content_information_ddc_id`
`GET /api/rvks`	`content_information_rvk_id`

IDs in den Beispielen sind Platzhalter

Sämtliche numerischen IDs in dieser Dokumentation (1, 2, …) sind Platzhalter. Verwenden Sie ausschließlich die in Ihrer Installation tatsächlich vorhandenen IDs aus den obigen Endpunkten – andernfalls antwortet die API mit 422.

Statusfluss

Jede Einlieferung durchläuft folgende Stati:

open → verified → valid → finished

open – Die Einlieferung wird vom Lieferanten bearbeitet. Nur in diesem Status sind Änderungen über die API möglich.
verified – Eingereicht; liegt in der Bearbeitungsqueue der SLUB.
valid – Von der SLUB geprüft und freigegeben.
finished – Abgeschlossen.

Über die API steuerbar ist der Übergang open → verified (siehe Einreichen).