Zum Inhalt springen
EN14 Tage kostenlos testen
Produkt
Preise
Ressourcen
Vertrauen
Unternehmen
14 Tage kostenlos testenAnmeldenEnglish

Vorfallsakten

Teil der API-Referenz. Authentifizierung, Scopes, Anfragegrenzen und Fehler stehen im Überblick.

BitHive Reporting Desk API · 0.11.0

Vorfallsakten

GET/v1/records

Vorfallsakten auflisten

Gibt die Vorfallsakten der Module (NIS2, die DSGVO, Vertragliche Meldefristen) zurück, die die Person sieht, die das Token erstellt hat, jeweils mit ihren Modulen (regimes) und ihrer nächsten laufenden Frist. Das Token sieht, was diese Person sieht, bei jeder Anfrage neu geprüft: Ein Modul, das auf andere Nutzer beschränkt ist, bleibt weg, und eine Vorfallsakte, deren Pflichten alle zu solchen Modulen gehören, wird nicht aufgeführt. Hat die Person, die ein Token erstellt hat, das Konto verlassen, sieht das Token keine Vorfallsakte. Erfordert die Berechtigung records:read.

Scope: records:read

Antworten

200 Die Vorfallsakten, die das Token sieht. RecordList

{
  "records": [
    {
      "id": "cf6df210-3d1f-43c6-8ecb-374831ed5118",
      "summary": "Ransomware encrypted the billing systems",
      "state": "open",
      "entered_at": "2026-10-12T06:25:31Z",
      "aware_at": "2026-10-12T06:10:00Z",
      "occurred_at": "2026-10-12T03:40:00Z",
      "regimes": [
        "nis2"
      ],
      "next_deadline": {
        "obligation": "nis2.bsig.significant_incident:2d244e39-9353-4652-b8bb-fde203139229",
        "stage": "early_warning",
        "due_at": "2026-10-13T06:10:00Z",
        "overdue": false
      }
    }
  ]
}

403 Dem API-Token fehlt die erforderliche Berechtigung, oder, bei einem Schreibvorgang, das Konto ist gesperrt, weil eine Zahlung offen ist oder sein Abonnement beendet ist. Lesen ist in beiden Fällen weiter möglich. Das Schreiben einer Vorfallsakte wird außerdem abgewiesen, wenn die Person, die das Token erstellt hat, keine Vorfälle mehr bearbeiten darf, und eine neue Vorfallsakte außerhalb der Beta oder für ein Modul, das das Konto nicht mehr gebucht hat. Das Feld detail sagt, welcher Fall zutrifft. Problem

Beispiel

Beispiel

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/records"

POST/v1/records

Vorfallsakte anlegen

Erfasst einen Vorfall und eröffnet, was seine Parteien schulden: für jede Rechtseinheit und jeden Vertrag jede Art von Pflicht aus einem gebuchten Modul, deren Definition die Vorfallsakte erfüllt, mit ihrer vorgeschlagenen Anwendbarkeit und ihren Fristen. Das Konto muss in der Beta sein, die Person, die das Token erstellt hat, muss weiterhin Vorfälle bearbeiten dürfen, und die Module (regimes), Parteien und Definitionen müssen solche sein, die diese Person sieht. Jeder Schreibvorgang nimmt einen Idempotency-Key an. Die Einträge im Protokoll des Kontos nennen das Token. Erfordert die Berechtigung records:write.

Scope: records:write

Parameter

ParameterWoTypBeschreibung
Idempotency-Key erforderlichheaderstringWie bei jedem Schreibvorgang; die Schreibvorgänge der Vorfallsakten verlangen ihn.

Anfragekörper

  • application/json
{
  "summary": "Outage of the billing systems",
  "aware_at": "2026-10-12T09:30:00Z",
  "definitions": [
    "nis2.significant_incident"
  ],
  "legal_entities": [
    "2d244e39-9353-4652-b8bb-fde203139229"
  ],
  "answers": {
    "gdpr.risk": "high"
  }
}

Antworten

201 Die Vorfallsakte, wie das Token sie sieht. Record

{
  "id": "cf6df210-3d1f-43c6-8ecb-374831ed5118",
  "summary": "Ransomware encrypted the billing systems",
  "detail": "The billing systems are encrypted and offline. Network operation is not affected.",
  "state": "open",
  "entered_at": "2026-10-12T06:25:31Z",
  "aware_at": "2026-10-12T06:10:00Z",
  "occurred_at": "2026-10-12T03:40:00Z",
  "regimes": [
    "nis2"
  ],
  "next_deadline": {
    "obligation": "nis2.bsig.significant_incident:2d244e39-9353-4652-b8bb-fde203139229",
    "stage": "early_warning",
    "due_at": "2026-10-13T06:10:00Z",
    "overdue": false
  },
  "definitions": [
    "nis2.significant_incident"
  ],
  "answers": {
    "nis2.kritis": "no"
  },
  "items": [
    {
      "kind": "legal_entity",
      "name": "Example Netz GmbH"
    }
  ],
  "obligations": [
    {
      "key": "nis2.bsig.recipient_information:2d244e39-9353-4652-b8bb-fde203139229",
      "regime": "nis2",
      "type": "nis2.bsig.recipient_information",
      "party": {
        "kind": "legal_entity",
        "id": "2d244e39-9353-4652-b8bb-fde203139229"
      },
      "party_name": "Example Netz GmbH",
      "applicability": "required",
      "suggested": "required",
      "reason": "",
      "decided_by": "api-token:ac564834-c28c-4705-9129-6b7be8701c21",
      "decided_at": "2026-10-12T06:25:31Z",
      "stages": [
        {
          "id": "recipient_information",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": "requested"
        }
      ]
    },
    {
      "key": "nis2.bsig.significant_incident:2d244e39-9353-4652-b8bb-fde203139229",
      "regime": "nis2",
      "type": "nis2.bsig.significant_incident",
      "party": {
        "kind": "legal_entity",
        "id": "2d244e39-9353-4652-b8bb-fde203139229"
      },
      "party_name": "Example Netz GmbH",
      "applicability": "required",
      "suggested": "required",
      "reason": "",
      "decided_by": "api-token:ac564834-c28c-4705-9129-6b7be8701c21",
      "decided_at": "2026-10-12T06:25:31Z",
      "stages": [
        {
          "id": "early_warning",
          "closed": false,
          "due_at": "2026-10-13T06:10:00Z",
          "met_at": null,
          "rule": "nis2.bsig.early_warning",
          "rule_version": 1,
          "waiting_for": ""
        },
        {
          "id": "notification",
          "closed": false,
          "due_at": "2026-10-15T06:10:00Z",
          "met_at": null,
          "rule": "nis2.bsig.notification",
          "rule_version": 1,
          "waiting_for": ""
        },
        {
          "id": "intermediate_report",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": "requested"
        },
        {
          "id": "final_report",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": "submitted:notification"
        },
        {
          "id": "progress_report",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": "submitted:notification"
        },
        {
          "id": "final_report_after_progress",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": "closed"
        }
      ]
    },
    {
      "key": "nis2.enwg.significant_incident:2d244e39-9353-4652-b8bb-fde203139229",
      "regime": "nis2",
      "type": "nis2.enwg.significant_incident",
      "party": {
        "kind": "legal_entity",
        "id": "2d244e39-9353-4652-b8bb-fde203139229"
      },
      "party_name": "Example Netz GmbH",
      "applicability": "not_applicable",
      "suggested": "not_applicable",
      "reason": "answers",
      "decided_by": "api-token:ac564834-c28c-4705-9129-6b7be8701c21",
      "decided_at": "2026-10-12T06:25:31Z",
      "stages": [
        {
          "id": "early_warning",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": ""
        },
        {
          "id": "notification",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": ""
        },
        {
          "id": "intermediate_report",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": ""
        },
        {
          "id": "final_report",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": ""
        },
        {
          "id": "progress_report",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": ""
        },
        {
          "id": "final_report_after_progress",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": ""
        }
      ]
    }
  ]
}

400 Ein Body ist nicht das JSON-Objekt, das die API-Spezifikation vorsieht, oder ein Schreibvorgang der Vorfallsakten hat keinen Idempotency-Key. Problem

Beispiel

403 Dem API-Token fehlt die erforderliche Berechtigung, oder, bei einem Schreibvorgang, das Konto ist gesperrt, weil eine Zahlung offen ist oder sein Abonnement beendet ist. Lesen ist in beiden Fällen weiter möglich. Das Schreiben einer Vorfallsakte wird außerdem abgewiesen, wenn die Person, die das Token erstellt hat, keine Vorfälle mehr bearbeiten darf, und eine neue Vorfallsakte außerhalb der Beta oder für ein Modul, das das Konto nicht mehr gebucht hat. Das Feld detail sagt, welcher Fall zutrifft. Problem

Beispiel

409 Die Meldung der Stufe ist bereits als eingereicht erfasst, ihre Pflicht ist geschlossen, eine Anfrage mit demselben Idempotency-Key läuft noch, oder die Antwort des darunter ausgeführten Schreibvorgangs wird noch ermittelt. Problem

Beispiel

422 Eine Vorfallsakte oder Meldung wird mit einer Begründung abgewiesen, oder der Idempotency-Key wurde mit einer anderen Anfrage gesendet. Problem

Beispiel

Beispiel

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @new-record.json \
  "https://app.bithive-it.com/v1/records"

GET/v1/records/{recordId}

Eine Vorfallsakte mit ihren Pflichten und Fristen lesen

Gibt die Vorfallsakte mit den Pflichten zurück, die die Person sieht, die das Token erstellt hat: je Pflicht ihren Schlüssel, ihre Art, ihre Partei, ihre Anwendbarkeit und ihre Stufen, und je Stufe ihre gespeicherte Frist (Fälligkeits- und Erfüllungszeitpunkt, Regel und Version) oder den Zeitpunkt, auf den sie wartet. Eine Vorfallsakte eines anderen Kontos, eine, von der diese Person nichts sieht, und ein Fall anderer Art werden als nicht gefunden gemeldet. Erfordert die Berechtigung records:read.

Scope: records:read

Parameter

ParameterWoTypBeschreibung
recordId erforderlichpathstring (uuid)Kennung der Vorfallsakte.

Antworten

200 Die Vorfallsakte. Record

Beispiel

403 Dem API-Token fehlt die erforderliche Berechtigung, oder, bei einem Schreibvorgang, das Konto ist gesperrt, weil eine Zahlung offen ist oder sein Abonnement beendet ist. Lesen ist in beiden Fällen weiter möglich. Das Schreiben einer Vorfallsakte wird außerdem abgewiesen, wenn die Person, die das Token erstellt hat, keine Vorfälle mehr bearbeiten darf, und eine neue Vorfallsakte außerhalb der Beta oder für ein Modul, das das Konto nicht mehr gebucht hat. Das Feld detail sagt, welcher Fall zutrifft. Problem

Beispiel

Beispiel

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/records/$RECORDID"

POST/v1/records/{recordId}/submissions

Meldung einer Stufe als eingereicht erfassen

Erfasst, dass die Meldung einer Stufe eingereicht wurde: die Felder der Meldung in einer der Sprachen ihrer Vorlage, wann und von wem sie eingereicht wurde, über welchen Kanal sie an jeden Empfänger ging, an den sie ging, und warum sie nicht an die anderen ging. Die Kopie der Einreichung wird mit dem SHA-256 ihres Textes im Protokoll aufbewahrt, die Frist der Stufe ist erfüllt, und die Stufen, die von ihr aus laufen, werden angesetzt. Abgewiesen wird sie, solange ein Feld fehlt, bevor die Stufen erfasst sind, auf die sie folgt, und für eine bereits erfasste Stufe oder eine geschlossene Pflicht (409). Eine Pflicht, die noch offen ist, nimmt ihre Meldungen auch an, nachdem das Modul des Kontos oder seine Teilnahme an der Beta geendet hat. Jeder Schreibvorgang nimmt einen Idempotency-Key an. Erfordert die Berechtigung records:write.

Scope: records:write

Parameter

ParameterWoTypBeschreibung
recordId erforderlichpathstring (uuid)Kennung der Vorfallsakte.
Idempotency-Key erforderlichheaderstringWie bei jedem Schreibvorgang; die Schreibvorgänge der Vorfallsakten verlangen ihn.

Anfragekörper

  • application/json
{
  "obligation": "nis2.bsig.significant_incident:2d244e39-9353-4652-b8bb-fde203139229",
  "stage": "early_warning",
  "language": "de",
  "values": {
    "description": "Die Abrechnungssysteme sind ausgefallen.",
    "malicious": "unknown",
    "cross_border": "no"
  },
  "submitted_at": "2026-10-12T14:52:00Z",
  "submitted_by": "Security operations",
  "reference": "2026-104233",
  "sent": {
    "bsi": "bsi_portal"
  }
}

Antworten

201 Die Kopie der Einreichung. Submission

{
  "record": "cf6df210-3d1f-43c6-8ecb-374831ed5118",
  "obligation": "nis2.bsig.significant_incident:2d244e39-9353-4652-b8bb-fde203139229",
  "stage": "early_warning",
  "submitted_at": "2026-10-12T14:52:00Z",
  "recorded_at": "2026-10-12T14:55:12Z",
  "submitted_by": "Security operations",
  "reference": "2026-104233",
  "channel": "bsi_portal",
  "recipient": "bsi",
  "sent": [
    {
      "recipient": "bsi",
      "channel": "bsi_portal"
    }
  ],
  "not_sent": [],
  "template": "nis2.bsig.early_warning",
  "template_version": 1,
  "language": "de",
  "sha256": "6b1f0c2d9e8a7b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f7a8b9c0d1e2"
}

400 Ein Body ist nicht das JSON-Objekt, das die API-Spezifikation vorsieht, oder ein Schreibvorgang der Vorfallsakten hat keinen Idempotency-Key. Problem

Beispiel

403 Dem API-Token fehlt die erforderliche Berechtigung, oder, bei einem Schreibvorgang, das Konto ist gesperrt, weil eine Zahlung offen ist oder sein Abonnement beendet ist. Lesen ist in beiden Fällen weiter möglich. Das Schreiben einer Vorfallsakte wird außerdem abgewiesen, wenn die Person, die das Token erstellt hat, keine Vorfälle mehr bearbeiten darf, und eine neue Vorfallsakte außerhalb der Beta oder für ein Modul, das das Konto nicht mehr gebucht hat. Das Feld detail sagt, welcher Fall zutrifft. Problem

Beispiel

409 Die Meldung der Stufe ist bereits als eingereicht erfasst, ihre Pflicht ist geschlossen, eine Anfrage mit demselben Idempotency-Key läuft noch, oder die Antwort des darunter ausgeführten Schreibvorgangs wird noch ermittelt. Problem

Beispiel

422 Eine Vorfallsakte oder Meldung wird mit einer Begründung abgewiesen, oder der Idempotency-Key wurde mit einer anderen Anfrage gesendet. Problem

Beispiel

Beispiel

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @new-submission.json \
  "https://app.bithive-it.com/v1/records/$RECORDID/submissions"

POST/v1/contracts/{contractId}/archive

Vertrag archivieren

Nimmt einen Vertrag aus der Verwendung: Er zählt nicht mehr gegen die Größe der Vertragsfristen und kann von keiner neuen Vorfallsakte mehr genannt werden, während jede Vorfallsakte, die ihn nennt, ihn behält. Ein Vertrag, unter dem eine Mitteilungspflicht offen ist, wird abgewiesen (409), und das Feld detail nennt die Vorfallsakten, in denen eine offen ist. Einen archivierten Vertrag erneut zu archivieren ändert nichts. Wie die Meldung einer offenen Pflicht braucht das Archivieren weder ein gebuchtes Modul noch die Beta: Ein Konto, das nur noch das CRA-Modul hat, kann einen Vertrag, den es behalten hat, weiterhin archivieren. Erfordert die Berechtigung records:write und ein Token, dessen Ersteller Vorfälle bearbeiten darf und Inhaber oder Administrator ist.

Scope: records:write

Parameter

ParameterWoTypBeschreibung
contractId erforderlichpathstring (uuid)Kennung des Vertrags.

Antworten

200 Der Vertrag, wie er jetzt ist. ContractState

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "kind": "notice_clause",
  "counterparty": "Kunde AG",
  "archived_at": "2026-10-26T09:12:00Z"
}

403 Dem API-Token fehlt die erforderliche Berechtigung, oder, bei einem Schreibvorgang, das Konto ist gesperrt, weil eine Zahlung offen ist oder sein Abonnement beendet ist. Lesen ist in beiden Fällen weiter möglich. Das Schreiben einer Vorfallsakte wird außerdem abgewiesen, wenn die Person, die das Token erstellt hat, keine Vorfälle mehr bearbeiten darf, und eine neue Vorfallsakte außerhalb der Beta oder für ein Modul, das das Konto nicht mehr gebucht hat. Das Feld detail sagt, welcher Fall zutrifft. Problem

Beispiel

409 Unter dem Vertrag ist eine Mitteilungspflicht offen, sodass er nicht archiviert werden kann; oder die Größe der Vertragsfristen hat keinen Vertrag frei, sodass er nicht wiederhergestellt werden kann. Das Feld detail sagt, welcher Fall zutrifft. Problem

Beispiel

Beispiel

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/contracts/$CONTRACTID/archive"

POST/v1/contracts/{contractId}/restore

Archivierten Vertrag wiederherstellen

Nimmt einen archivierten Vertrag wieder in Verwendung. Eine Mitteilungsklausel wird abgewiesen, solange die Größe der Vertragsfristen keinen Vertrag frei hat (409). Einen Vertrag in Verwendung wiederherzustellen ändert nichts. Erfordert die Berechtigung records:write, ein Token, dessen Ersteller Vorfälle bearbeiten darf und Inhaber oder Administrator ist, und ein Konto in der Beta.

Scope: records:write

Parameter

ParameterWoTypBeschreibung
contractId erforderlichpathstring (uuid)Kennung des Vertrags.

Antworten

200 Der Vertrag, wie er jetzt ist. ContractState

Beispiel

403 Dem API-Token fehlt die erforderliche Berechtigung, oder, bei einem Schreibvorgang, das Konto ist gesperrt, weil eine Zahlung offen ist oder sein Abonnement beendet ist. Lesen ist in beiden Fällen weiter möglich. Das Schreiben einer Vorfallsakte wird außerdem abgewiesen, wenn die Person, die das Token erstellt hat, keine Vorfälle mehr bearbeiten darf, und eine neue Vorfallsakte außerhalb der Beta oder für ein Modul, das das Konto nicht mehr gebucht hat. Das Feld detail sagt, welcher Fall zutrifft. Problem

Beispiel

409 Unter dem Vertrag ist eine Mitteilungspflicht offen, sodass er nicht archiviert werden kann; oder die Größe der Vertragsfristen hat keinen Vertrag frei, sodass er nicht wiederhergestellt werden kann. Das Feld detail sagt, welcher Fall zutrifft. Problem

Beispiel

Beispiel

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/contracts/$CONTRACTID/restore"

Der Vertrag selbst. Diese Seite entsteht aus dem OpenAPI-Dokument des Dienstes. Es ist als Datei veröffentlicht, damit ein Client-Generator denselben Vertrag lesen kann, den diese Seite beschreibt. openapi.yaml herunterladen

Doku

14 Tage kostenlos testen