Der Push: der Einlieferungsvertrag, Version 1

Technische Seite für einen Verlag, der sein eigenes Plugin oder seinen eigenen Push-Code schreibt.

Diese Seite beschreibt, was ein Absender an Eiger Vault sendet, was er zurückerhält und wie er sich bei einem Fehler oder einem Unterbruch verhält. Sie folgt den veröffentlichten Verträgen, wie sie heute auf dem Hauptzweig unserer Repositories stehen: das native Dokument ev-native/1 für die Anfrage, der Vertrag Einliefern v1 für das, was der Vault antwortet, und das Rechteformat ev-rights/1. Diese Verträge sind versioniert, und eine veröffentlichte Version wird nie geändert: Eine Ergänzung kommt durch eine neue Version, die der vorherigen nichts wegnimmt. Einige Punkte werden später präzisiert: siehe Abschnitt 11.

Öffnungsstatus. Die Schnittstelle, die Ihre Anfragen entgegennimmt, ist noch nicht im Internet geöffnet; sie wird es erst mit der Ankunft des ersten Verlags. Ihre Adresse wird zu diesem Zeitpunkt mitgeteilt. Die nachstehenden Beispiele verwenden https://<Adresse der nativen Schnittstelle>.

1. Das Prinzip

Sie rufen den Vault nicht direkt auf: Sie rufen die native Schnittstelle auf, die Ihr natives Dokument in eine Einlieferungsanfrage übersetzt, sie mit Ihrem Schlüssel an den Vault weiterleitet und Ihnen dessen Antwort unverändert zurückgibt. Sie bewahrt nichts von dem auf, was durch sie hindurchgeht, und hat keine Warteschlange: Sie antwortet erst nach der Antwort des Vaults. Ist der Vault nicht erreichbar, antwortet sie 503.

Eine Einlieferungsanfrage trägt ein Dokument: die Textblöcke des Artikels und, optional, seine Dateien (Bilder, PDF der Seite, Video).

2. Die Authentifizierung

Der Verlagsschlüssel, den wir Ihnen übergeben haben, hat die Form evk_, gefolgt von sechzehn Hexadezimalziffern, von _ und dann von vierundsechzig weiteren Hexadezimalziffern. Er wird im Header Authorization unter dem Schema Bearer übergeben, und nirgendwo sonst:

Authorization: Bearer evk_0123456789abcdef_<64 Hexadezimalziffern>

• Eine Zeichenkette in der Form eines Schlüssels, die in der Adresse oder im JSON-Teil gefunden wird, lässt die Anfrage vor jedem Aufruf des Vaults ablehnen (native.key-outside-header). Keine Adresse der Schnittstelle trägt je einen Schlüssel, eine Referenz oder einen Dateinamen.
• Die Schnittstelle leitet den Header unverändert weiter, auch wenn er fehlt oder fehlerhaft ist: Nur der Vault beurteilt einen Schlüssel. Ein fehlender, fehlerhafter, unbekannter, widerrufener Schlüssel oder der eines deaktivierten Einlieferers wird mit demselben Code abgelehnt, deposit.unknown-or-revoked-key (401), der nie sagt, welche dieser Ursachen zutrifft.
• Der Schlüssel wird bei der Ankunft der Einlieferung beurteilt: Eine mit einem gültigen Schlüssel begonnene Einlieferung wird zu Ende geführt, selbst wenn der Schlüssel in der Zwischenzeit widerrufen wird.
• Die Identitätsstufe des Siegels ergibt sich aus dem Schlüssel: Ein Verlagsschlüssel ergibt die Stufe «authentifiziert».

3. Die Anfrage

POST /deposits
Authorization: Bearer evk_0123456789abcdef_<64 Hexadezimalziffern>
Content-Type: multipart/form-data; boundary=…
X-Correlation-ID: <optional>

POST /deposits zum Einliefern und POST /presence-checks für die Sammelprüfung (Abschnitt 9): Das sind die beiden einzigen Routen. Jeder andere Pfad und jede andere Methode erhält 404 (not-found).

Der Body besteht aus mehreren Teilen (multipart/form-data):

Die Namen native_document und supplementary_metadata sind reserviert: Keine Datei trägt sie. Jeder Teil, den die Anfrage trägt, muss vom nativen Dokument bezeichnet werden, und jeder Teil, den es bezeichnet, muss vorhanden sein. Ein Teil, der ein anderes Content-Transfer-Encoding als 7bit, 8bit oder binary deklariert, wird abgelehnt.

Die Korrelationskennung. Sie können X-Correlation-ID senden; andernfalls leitet die Schnittstelle eine ab. Sie begleitet die Anfrage bis zum Vault, kommt im Header der Antwort und im Body jeder Ablehnung zurück: Bewahren Sie sie für jede Supportanfrage auf.

Die Grenzen (Startwerte, von Eiger Vault vor der Inbetriebnahme angepasst):

Jenseits einer Grenze hört die Schnittstelle auf zu lesen und lehnt native.request-too-large (413) ab. Mit diesen Werten bleibt die schwerste Einlieferung, die sich daraus ergeben kann, einschliesslich Base64, unter den 24 MiB, die der Vault für den Body einer Einlieferung akzeptiert.

4. Das native Dokument

Es ist ein JSON-Text, den die Schnittstelle nie umschreibt. Gibt es keine explizite Ursprungshülle, werden diese Bytes selbst als Ursprungshülle der Einlieferung versiegelt: Sie werden unverändert aufbewahrt.

{
  "format": "ev-native/1",
  "source": "ch-src-0192f3a4-5b6c-7d8e-9fa0-b1c2d3e4f5a6",
  "metadata": {
    "document_type": "article",
    "source_reference": "12345",
    "published_at": "2026-10-05T08:30:00+02:00",
    "title": "Ein Titel",
    "authors": ["Anne Exemple"]
  },
  "body_form": "blocks",
  "text_blocks": [
    {"role": "paragraph", "text": "Ein Absatz."},
    {"role": "caption", "text": "Das Foto.", "file": "photo-1"}
  ],
  "files": [
    {"name": "photo-1", "role": "image", "media_type": "image/jpeg"}
  ],
  "cms_revision": "48213"
}

Der Vertrag ist auf allen Ebenen geschlossen. Ein Member, den der Vertrag nicht nennt, in welcher Tiefe auch immer, lässt das Dokument ablehnen (native.unknown-member): Ein falsch geschriebener Member, der stillschweigend durchginge, würde für immer versiegelt, ohne dass es jemandem etwas gesagt hätte.

Die Member der ersten Ebene.

Die Beschreibung metadata.

Die Felder, die der Vault selbst schreibt – der Schematyp, seine Version, die aufgelöste Kollektion –, werden nicht deklariert: Sie zu deklarieren, lässt das Dokument ablehnen.

Die Blöcke. Jeder Block hat eine role – paragraph, subheading (Zwischentitel), sidebar (Kasten) oder caption (Bildlegende) – und einen nicht leeren text. Ein Kasten trägt eine Liste text_blocks von mindestens einem Block, die keinen Kasten enthält. Eine Bildlegende kann eine Datei über ihren name in file bezeichnen. Der Text wird ohne jede Änderung übernommen, Tags eingeschlossen: Der Vault liest darin keine Auszeichnung, und <b> zählt dort als vier Zeichen.

Die Dateien. Jeder Eintrag von files hat einen name (eindeutig, nicht reserviert: Es ist der Name des Teils, der die Bytes trägt), eine role (image, video oder page_pdf; nie text) und einen media_type (in der Form Typ/Untertyp, in Kleinbuchstaben, ohne Parameter). Die Dateien werden in der Reihenfolge der Liste aufbewahrt, Byte für Byte. Der Name einer Datei gelangt nie zum Vault und steht in keiner Spur.

Die Daten. published_at und updated_at werden entweder als RFC-3339-Zeitpunkt mit seinem Offset geschrieben, so übernommen, wie das CMS ihn hält (2026-10-05T08:30:00+02:00), oder als Tag JJJJ-MM-TT, nur wenn nichts anderes bekannt ist. Ein Datum ohne Offset ist kein Zeitpunkt. Konvertieren Sie den Offset nicht: Der Vault konvertiert ihn nach UTC. updated_at ist das der Leserin oder dem Leser angezeigte Datum der Aktualisierung: Zeigt Ihre Website keines an, lassen Sie den Member weg, und setzen Sie nie ein technisches Änderungsdatum ein. Ein fehlendes Datum bleibt fehlend; wir ergänzen es nie.

Das Lesen des JSON. Der JSON-Teil ist striktes I-JSON (RFC 7493): gültiges UTF-8, ohne Byte-Order-Mark, ohne wiederholten Member, ohne einzelnes Surrogat-Zeichen und ohne Nichtzeichen, nur mit ganzen Zahlen. Eine leere Zeichenkette, null, eine leere Liste und ein leeres Objekt gelten als «fehlend»: Der Member wird weggelassen, und ein leerer obligatorischer Member gilt als fehlend. Kein Block von text_blocks und keine Datei von files wird durch diese Regel entfernt.

Die Quellenreferenz. Sie ist die Kennung, die Ihr CMS dem Artikel gibt, ohne jede Normalisierung, und sie ändert sich für denselben Artikel nie. Sie wird nicht aus einer Adresse abgeleitet. Sie folgt der erwarteten Form, die wir für Ihre Quelle vereinbart haben: Folgt sie ihr nicht, wird das Dokument abgelehnt (native.reference-rule-mismatch), ohne dass die Ablehnung die Referenz zitiert.

Die Revision des CMS. Sie identifiziert für Ihr CMS einen Zustand des Artikels. Sie wird nie zur Versionsbezeichnung. Sie dient dazu, den Idempotenzschlüssel zu berechnen (Abschnitt 6): Dieselbe Revision muss also immer denselben Inhalt ergeben, und eine sichtbare Änderung muss eine neue Revision ergeben.

5. Die Antwort

Eine Einlieferung, die ein Dokument oder eine Version erstellt, antwortet 201. Eine Einlieferung, die nichts erstellt – erkannte Wiederholung, unveränderter Inhalt –, antwortet 200, mit dem Siegel der erkannten Version. Beide Antworten haben dieselbe Form:

{
  "document": "ch-0192f3a4-5b6c-7d8e-9fa0-b1c2d3e4f5a6",
  "notices": [],
  "seal": {
    "depositor": "ch-dep-0192f3a4-5b6c-7d8e-9fa0-b1c2d3e4f5a7",
    "format": "ev-seal/1",
    "identity_level": "authenticated",
    "manifest_digest": {"sha-256": "…", "sha3-512": "…"},
    "origin_proofs_digest": {"sha-256": "…", "sha3-512": "…"},
    "received_at": "2026-10-05T06:31:12.123456Z"
  },
  "version_number": 1
}

Das zurückgegebene Siegel wird Byte für Byte von dem übernommen, was der Vault geschrieben hat; Sie können es als Beleg aufbewahren.

Die Hinweise (höchstens je einmal, ohne je zu zitieren, was sie verursacht hat):

6. Die Idempotenz

Sie senden keinen Idempotenzschlüssel: Die Schnittstelle berechnet ihn, durch einen Hashwert mit Schlüssel (HMAC-SHA-256, unter Ihrem Schlüssel) des Tripels (Quelle, Quellenreferenz, Revision des CMS). Der Schlüssel ist somit nie lesbar, und eine Wiederholung, die über ein Deployment auf unserer Seite hinweg erfolgt, legt denselben Schlüssel vor. Der Vault bewahrt ihn 30 Tage auf, nur für Ihren Einlieferer.

Nach den 30 Tagen gilt ein Schlüssel als neu. Ein Inhalt, der mit dem der letzten Version identisch ist, ergibt dann content_unchanged statt retry_recognized: Es gibt ohnehin keine zusätzliche Version.

7. Die Versionen

Ein Dokument wird durch das Paar (Quelle, Quellenreferenz) identifiziert. Eine Einlieferung, deren Paar bekannt ist, zielt auf das bestehende Dokument. Die Versionen werden pro Dokument 1, 2, 3 nummeriert, ohne Lücke.

Was eine Version ausmacht. Man vergleicht den Inhalt, den Sie deklarieren – die Beschreibung und die Bestandteile, strukturierten Text eingeschlossen –, mit dem der letzten Version. Die Bytes der Ursprungshülle gehen nicht in den Vergleich ein. Weichen sie ab, erstellt dies allein keine Version: Eine neu generierte Seite oder ein natives Dokument, in dem sich ein nicht übersetzter Member ändert, erstellt keine. Die Versionsbezeichnung und die Kollektion gehören zur Beschreibung: Sie zu ändern, erstellt eine Version.

Was sich nie ändert. Der Typ eines Dokuments: Eine Einlieferung, die ihn ändern würde, wird abgelehnt (deposit.document-type-change, 409). Der Einlieferer, der eine neue Version einliefern kann, ist jeder für die Quelle des Dokuments autorisierte Einlieferer.

Die Umklassierung. Eine neue Version kann die Kollektion innerhalb der Quelle des Dokuments wechseln, indem sie die neue Kollektion bezeichnet.

Das Veröffentlichungsdatum des Dokuments ist dasjenige, das seine erste Version deklariert.

8. Die Rücknahmen

Im Einlieferungsvertrag gibt es keine Operation zur Rücknahme: weder eine Löschung noch einen Status «unveröffentlicht». Ein in Ihrem CMS gelöschter oder unveröffentlichter Artikel bleibt in unserem Register, mit allen seinen Versionen. Um einen Inhalt zurückzunehmen, richtet der Verlag eine Anfrage an Eiger Vault; ein Operator trifft dann einen Entscheid, der für immer im Register eingetragen wird, mit seinen Urheberinnen und Urhebern, seinem Zeitpunkt und seiner Begründung. Es gibt zwei Stufen: die Sperrung (der Inhalt wird niemandem mehr gezeigt, das Siegel bleibt erhalten; der Entscheid ist umkehrbar) und die Löschung (die Verschlüsselungsschlüssel der Bestandteile und der Beschreibung werden zerstört; sie lässt sich nicht rückgängig machen). Dieses Verfahren wird vor der Inbetriebnahme im Detail beschrieben.

Was nie zurückgenommen wird, auch nach einer Löschung: die Kennung, die Hashwerte, das Siegel und ein Löschvermerk, der sagt, dass es ein Dokument gab, wann, von wem und warum es nicht mehr da ist.

9. Die Wiederaufnahme nach einem Unterbruch

Wenn Sie keine Antwort erhalten haben – Zeitüberschreitung, unterbrochene Verbindung, 503 –, ist der Ausgang der Einlieferung unbekannt. Senden Sie dieselbe Anfrage mit derselben Revision des CMS erneut: Sie erhalten das Siegel der ersten Einlieferung (200, retry_recognized), falls sie stattgefunden hat, oder die Einlieferung findet statt (201). Eine Wiederholung erstellt nie eine doppelte Version.

Wenn eine Reihe von Einlieferungen verloren gegangen sein kann, zum Beispiel nach einem Ausfall bei Ihnen oder bei uns, sagt Ihnen die Sammelprüfung, was wir kennen, ohne dass Sie uns etwas senden:

POST /presence-checks
Authorization: Bearer evk_0123456789abcdef_<64 Hexadezimalziffern>
Content-Type: application/json

{"references": [{"source": "ch-src-0192f3a4-5b6c-7d8e-9fa0-b1c2d3e4f5a6", "source_reference": "12345"},
                {"source": "ch-src-0192f3a4-5b6c-7d8e-9fa0-b1c2d3e4f5a6", "source_reference": "12346"}]}

Der Body ist auf 1000 Referenzen und auf 4 MiB begrenzt. Die Antwort 200 gibt ein Ergebnis pro übermitteltes Paar, in der übermittelten Reihenfolge:

{"results": [
  {"source": "ch-src-…", "source_reference": "12345", "state": "served",
   "collection": "ch-src-…:c1", "version_label": "Abendausgabe",
   "comparison_digest": {"sha-256": "…", "sha3-512": "…"}},
  {"source": "ch-src-…", "source_reference": "12346", "state": "absent"}
]}

Die Antwort trägt nie Inhalt, weder Dokumentkennung noch Versionsnummer. Eine periodische Wiedereinlieferung besteht darin, Ihre jüngsten Inhalte aufzulisten (anfänglich die letzten 48 Stunden, jede Stunde), sie der Sammelprüfung zu übermitteln und dann nur die fehlenden einzuliefern.

Der Wiedereinlieferungsmodus existiert im Einlieferungsvertrag: Eine so markierte Einlieferung erstellt nie eine Version eines bestehenden Dokuments und gibt das Siegel seiner letzten Version zurück. Seine Verwendung durch die native Schnittstelle wird präzisiert: siehe Abschnitt 11.

10. Die Ablehnungen

Eine Ablehnung hat immer dieselbe Form, mit ihrem HTTP-Status:

{"code": "native.missing-required-field", "message": "<fester Satz>", "correlation_id": "…"}

Die Meldung ist ein fester Satz, der sagt, wo (der Name eines Members, der Rang eines Blocks oder einer Datei) und was; sie zitiert nie die Eingabe: weder Wert noch Namen eines unbekannten Members noch Referenz noch Dateinamen. Der Code ist das Einzige, worauf sich Ihr Programm stützen soll. Eine Ablehnung schreibt bei uns nichts.

10.1 Die Reihenfolge

Dieselbe Übermittlung ergibt immer dieselbe Ablehnung, weil die Prüfungen in fester Reihenfolge erfolgen und die erste Abweichung die Ablehnung ergibt. Es gibt zwei Stufen: die native Schnittstelle, die vor jedem Aufruf des Vaults prüft, dann den Vault.

Stufe 1, die native Schnittstelle.

1. vor dem Lesen des Dokuments: eine Zeichenkette in Schlüsselform in der Adresse, dann die Grösse, dann die Transferkodierung der Teile;
2. das Lesen als I-JSON, dann die Objektform des Dokuments;
3. format: fehlend oder verschieden von ev-native/1;
4. die Namen der Member, auf allen Ebenen;
5. die Member, in der Reihenfolge source, collection, metadata, body_form, text_blocks, files, rights, jeder gründlich;
6. die explizite Ursprungshülle und ihre Nachweise, falls vorhanden;
7. die Bezeichnungen: jeder Dateiname, dann jede Bildlegende;
8. cms_revision;
9. der Abgleich der Teile der Anfrage mit dem, was das Dokument bezeichnet; dann die Quelle in der Konfiguration der Schnittstelle und die Referenz gegenüber der Regel ihrer Quelle.

Die genaue Stelle des Abgleichs der Teile der Anfrage in Bezug auf die Schritte 3 bis 8 wird präzisiert.

Stufe 2, der Vault, gemäss dem Vertrag Einliefern v1:

1. der Schlüssel;
2. die Zuordnung zu einer Quelle oder einer Kollektion und der Geltungsbereich: nicht autorisierte, deaktivierte, unbekannte, nicht bezeichnete Quelle oder Kollektion und, nur in unserer Testumgebung, nicht zugelassene Quelle;
3. die Grösse des Bodys und jedes Bestandteils;
4. das Format der Anfrage, der Beschreibung, der Bestandteile und des strukturierten Textes;
5. die Ursprungsnachweise, falls es welche gibt;
6. eine Ursprungshülle, die bereits mit einem anderen Dokument verknüpft ist;
7. unter der Sperre des Dokuments, in dieser Reihenfolge: Der Geltungsbereich wird neu gelesen; dann der Entscheid nach Abschnitt 7: ein bereits gesehener Idempotenzschlüssel, ein Typwechsel, die Erkennung einer Wiederholung, eines unveränderten Inhalts oder die Erstellung einer Version.

Ein Member der ersten Ebene, den der Einlieferungsvertrag nicht kennt, oder ein Body, der kein Objekt ist, wird mit deposit.malformed-request abgelehnt.

10.2 Die Codes der nativen Schnittstelle

Ein Schlüssel, der im JSON-Teil mit \u-Escapes geschrieben ist, wird erst beim Lesen dieses Teils entdeckt: native.invalid-json geht dann vor native.key-outside-header.

10.3 Die Codes des Vaults, unverändert zurückgegeben

Die Codes, die einem Abruf eigen sind (deposit.attested-fetch-missing, deposit.invalid-attested-fetch, deposit.domain-outside-source-domains, deposit.original-envelope-not-attested), betreffen keinen Push mit Verlagsschlüssel. Ob eine Ablehnung endgültig oder vorübergehend ist, liest sich an ihrem Status ab: Jedes 4xx ist endgültig, solange sich die Anfrage nicht ändert; 503 wird mit derselben Anfrage wiederholt.

11. Was geklärt wird

Gewisse Punkte des Vertrags werden präzisiert oder ergänzt. Wir kündigen sie Ihnen an, und eine Ergänzung ändert nichts an dem, was diese Seite bereits beschreibt.

• Die Reihenfolge der Ablehnungen, wenn mehrere auf dieselbe Einlieferung zutreffen, wird im Vertrag vollständig festgehalten. Bis dahin verlassen Sie sich auf den Code der Ablehnung, nicht auf seine Stelle.
• Die Einlieferung, die nicht innerhalb der Frist zustande kommt, erhält eine Antwort, die sagt, es erneut zu versuchen. Bis dahin behandeln Sie eine unterbrochene Verbindung oder eine Zeitüberschreitung als unbekannten Ausgang und senden dieselbe Anfrage erneut (Abschnitt 9).
• Die Rechte in einem nativen Dokument. Das native Dokument sieht einen Abschnitt rights vor; seine Verwendung in einer Einlieferung wird präzisiert. Bis dahin senden Sie keinen.
• Der Wiedereinlieferungsmodus und die Änderung der Rechte eines bestehenden Dokuments über die native Schnittstelle werden mit ihrer öffentlichen Öffnung freigegeben.

12. Die Vektoren

Der Vertrag des nativen Dokuments wird mit Referenzvektoren geliefert: zugelassene native Dokumente, mit der Einlieferungsanfrage, die sie ergeben, und abgelehnte Dokumente, mit ihrem Code. Sie ändern sich nie und können gegen Ihren eigenen Code abgespielt werden. Wir übergeben sie Ihnen zusammen mit dem Vertrag.