Monographie anlegen & einreichen

Dieser Leitfaden beschreibt den vollständigen Ablauf, um eine Monographie über die API anzulegen und einzureichen. Der Ablauf besteht aus fünf Schritten:

Referenz-IDs nachschlagen
Monographie anlegen
Dokument hochladen
Optionale Angaben ergänzen
Einreichen

In allen Beispielen ist <host> durch den tatsächlichen Hostnamen und <Ihr-Schlüssel> durch Ihren API-Schlüssel zu ersetzen.

1. Referenz-IDs nachschlagen

Die Pflichtfelder einer Monographie verweisen über numerische IDs auf Referenzdaten. Schlagen Sie diese zuerst nach (siehe API-Übersicht):

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

2. Monographie anlegen

POST /api/monographs legt die Monographie an. Die Einlieferung startet im Status open. Die Antwort (201 Created) enthält die erzeugte id (UUID), die in allen folgenden Schritten verwendet wird.

Pflichtfelder

Feld	Typ	Beschreibung
`title`	String	Titel
`publishing_date`	Integer	Erscheinungsjahr
`doc_type_id`	Integer (FK)	Dokumenttyp
`edition_name`	String	Auflage
`file_format_id`	Integer (FK)	Dateiformat
`access_right_archive_object_id`	Integer (FK)	Zugriffsrechte Archivobjekt
`access_status_id`	Integer (FK)	Zugriffsstatus
`persons`	Liste	mindestens eine Person (`name`, `role_id`)
`publishers`	Liste	mindestens ein Verlag (`name_id`, `place`)

Das Dokument ist ebenfalls Pflicht, wird aber separat in Schritt 3 hochgeladen.

Beispiel-Payloads

Minimal (nur Pflichtfelder)Vollständig (alle Lieferantenfelder)

{
  "title": "Beispieltitel einer Monographie",
  "publishing_date": 2025,
  "doc_type_id": 1,
  "edition_name": "1. Auflage",
  "file_format_id": 1,
  "access_right_archive_object_id": 1,
  "access_status_id": 1,
  "persons": [
    {"name": "Mustermann, Max", "role_id": 1}
  ],
  "publishers": [
    {"name_id": 1, "place": "Dresden"}
  ]
}

{
  "title": "Beispieltitel einer Monographie",
  "publishing_date": 2025,
  "doc_type_id": 1,
  "edition_name": "1. Auflage",
  "file_format_id": 1,
  "access_right_archive_object_id": 1,
  "access_status_id": 1,
  "caption": "Ein erläuternder Untertitel",
  "language_id": "ger",
  "language_other_ids": ["eng"],
  "net_publication_id": "urn:nbn:de:bsz:14-beispiel-123456",
  "description": "Kurze inhaltliche Beschreibung der Monographie.",
  "keywords": ["Schlagwort A", "Schlagwort B"],
  "content_information_ddc_id": 1,
  "content_information_rvk_id": 1,
  "fsk": 0,
  "persons": [
    {"name": "Mustermann, Max", "role_id": 1, "additional_information": "Hrsg."},
    {"name": "Musterfrau, Erika", "role_id": 2}
  ],
  "publishers": [
    {"name_id": 1, "place": "Dresden"},
    {"name_id": 2, "place": "Leipzig"}
  ]
}

Aufruf

curl -X POST https://<host>/api/monographs \
  -H "X-API-Key: <Ihr-Schlüssel>" \
  -H "Content-Type: application/json" \
  -d @monograph.json

Die Antwort enthält u. a. die id der neuen Monographie:

{
  "id": "3f1c2e8a-7b9d-4c5e-a1b2-0123456789ab",
  "title": "Beispieltitel einer Monographie",
  "...": "..."
}

3. Dokument hochladen

Das Dokument (PDF oder EPUB) wird separat als Datei-Upload hochgeladen. Das Feld heißt document, der Request ist multipart/form-data:

curl -X PUT https://<host>/api/monographs/3f1c2e8a-7b9d-4c5e-a1b2-0123456789ab/document \
  -H "X-API-Key: <Ihr-Schlüssel>" \
  -F "document=@/pfad/zur/datei.pdf"

Pflicht vor dem Einreichen

Ohne hochgeladenes Dokument schlägt das Einreichen in Schritt 5 fehl.

4. Optionale Angaben ergänzen

Bei Bedarf lassen sich weitere Angaben ergänzen, solange die Einlieferung im Status open ist. Beispiele:

ISBN hinzufügen:

curl -X POST https://<host>/api/monographs/3f1c2e8a-7b9d-4c5e-a1b2-0123456789ab/isbns \
  -H "X-API-Key: <Ihr-Schlüssel>" \
  -H "Content-Type: application/json" \
  -d '{"isbn13": "978-3-16-148410-0"}'

Analog stehen weitere Endpunkte zur Verfügung, jeweils unter /api/monographs/{id}/…: dois, urns, handles, production-numbers, multiparts, series, persons, organisations, publishers. Die vollständige Parameterliste finden Sie in der interaktiven API-Referenz.

5. Einreichen

POST /api/monographs/{id}/submit reicht die Einlieferung ein und überführt sie von open nach verified.

curl -X POST https://<host>/api/monographs/3f1c2e8a-7b9d-4c5e-a1b2-0123456789ab/submit \
  -H "X-API-Key: <Ihr-Schlüssel>"

Bei Erfolg (200 OK) wird der neue Prozessstatus zurückgegeben:

{
  "status": "verified",
  "...": "..."
}

Fehlen Pflichtangaben oder das Dokument, antwortet die API mit 400 und listet die fehlenden Felder auf:

{
  "status": "invalid",
  "missing": ["Titel", "Dokument"]
}

In diesem Fall ergänzen Sie die fehlenden Angaben (Schritte 2–4) und reichen erneut ein.

Status prüfen

Den aktuellen Status einer Einlieferung können Sie jederzeit abrufen:

curl https://<host>/api/monographs/3f1c2e8a-7b9d-4c5e-a1b2-0123456789ab/status \
  -H "X-API-Key: <Ihr-Schlüssel>"