Erechio Status API

openapi: 3.2.0
info:
  title: Erechio Status API
  version: 1.3.0
  summary: E-Rechnungen (XRechnung UBL/CII, ZUGFeRD-/Factur-X-XML) mit den KoSIT-Regeln prüfen, Fehler auf Deutsch erklärt.
  description: 'Prüft eine E-Rechnung gegen das XML-Schema (XSD: UBL 2.1 bzw. UN/CEFACT CII D16B) und mit denselben Schematron-Regeln und Szenarien wie die Prüfkonfiguration der KoSIT für XRechnung 3.0.2 (EN 16931 für UBL Invoice, UBL CreditNote und CII sowie die nationalen Regeln BR-DE). Jede Meldung trägt Regelcode, Fehlerstufe, Fundstelle und – für die häufigsten Regeln – eine deutsche Erklärung mit Hinweis zur Behebung.


    Ergebnis in zwei Stufen: `regelpruefung_bestanden` (keine Fehler in den Schematron-Regeln, Spezifikationskennung passt zu einem KoSIT-Szenario) und `vollstaendig_validiert` (zusätzlich schemagültig – das entspricht der Annahme durch das KoSIT-Prüftool). Nicht geprüft wird die inhaltliche und steuerliche Richtigkeit. Keine PDF-Annahme (bei ZUGFeRD das eingebettete XML senden).


    Änderungen 1.3.0 (2026-10-23): `GET /v1/status` meldet den echten Zustand – `ok` (200) nur mit bereitem Prüfprozess, lesbaren Schlüsseln und speicherbaren Nutzungsdaten, sonst `gestört` (503) mit `gruende`; Prüfungen werden dann mit 503 `gestoert` abgelehnt und nicht gezählt. Gezählt wird erst, wenn die Antwort 200 vollständig gesendet ist. Trennt der Client die Verbindung, wird die Prüfung beendet (auch in der Warteschlange) und nicht gezählt.


    Wichtig: HTTP 200 heißt „Prüfung ausgeführt“, nicht „Rechnung fehlerfrei“. Maßgeblich sind `vollstaendig_validiert` und `regelpruefung_bestanden`.


    Änderungen 1.2.0 (2026-10-22): neues Feld `regelstand` in Prüfergebnis und Status – Kennung der verwendeten Regel- und Schemadateien (Anfang ihrer SHA-256); Herkunft, Prüfsummen und Änderungsprotokoll des Prüfverhaltens auf https://erechio.de/aenderungen.html.


    Änderungen 1.1.0 (2026-10-21): XSD-Schemaprüfung ergänzt; neue Felder `vollstaendig_validiert`, `regelpruefung_bestanden`, `schemapruefung`; `valid` ist veraltet und gleich `vollstaendig_validiert` (in 1.0.0 war `valid` schon bei bestandener Regelprüfung ohne Schemaprüfung `true`); `ohne` nennt jetzt die inhaltliche Prüfung; Kontingent wird vor der Prüfung reserviert und nur bei 200 gezählt; neu Status 503 (`zeitlimit`, `ausgelastet`); Meldungen mit Code `XSD` (Schemafehler, Fundstelle als Zeile) und `ABBRUCH` (Regelprüfung wegen eines Werts im falschen Format abgebrochen). Änderungsprotokoll: https://erechio.de/api/#aenderungen


    Die Rechnung wird nur im Arbeitsspeicher geprüft und nicht gespeichert. Die Basisadresse steht in der Mail mit Ihrem Schlüssel. Testschlüssel kostenlos (50 Dokumente im Monat), Starter 500 Dokumente im Monat für 14 € inkl. 19 % MwSt. (netto 11,76 €). Nur für Unternehmer (§ 14 BGB) mit Sitz in Deutschland. Eine Verfügbarkeit wird nicht zugesagt.


    Technische Hinweise zum Datenformat, keine Steuer- oder Rechtsberatung. Erechio ist kein Angebot der KoSIT.'
  termsOfService: https://erechio.de/agb.html
  contact:
    name: Erechio
    url: https://erechio.de/api/
    email: info@erechio.de
  x-logo:
    url: https://erechio.de/logo.svg
servers:
- url: '{ERECHIO_URL}'
  description: Erechio API (Nürnberg)
  variables:
    ERECHIO_URL:
      default: https://api.erechio.de
      description: Basisadresse der API
tags:
- name: Status
  description: Zustand des Dienstes
paths:
  /v1/status:
    get:
      tags:
      - Status
      operationId: getStatus
      summary: Zustand des Dienstes
      description: 'Ohne Schlüssel. Version, Regelstand und Bereitschaft (seit 1.3.0 ehrlich: 503, wenn keine Prüfung möglich ist).'
      security: []
      responses:
        '200':
          description: Dienst läuft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
              example:
                status: ok
                version: 1.3.0
                regeln: KoSIT XRechnung 3.0.2, EN 16931 Schematron 1.3.16, XSD UBL 2.1 / CII D16B
                regelstand: e17455c9cb03
                zeit: '2026-10-17T08:00:00.000Z'
        '503':
          description: 'Dienst gestört: keine Prüfungen möglich (z. B. kein Prüfprozess bereit, Nutzungsdaten nicht lesbar oder nicht speicherbar). Prüfungen werden in diesem Zustand mit 503 `gestoert` abgelehnt und nicht gezählt.'
          headers:
            Retry-After:
              required: true
              description: Sekunden bis zum nächsten Versuch
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
              example:
                status: gestört
                gruende:
                - Nutzungsdaten nicht speicherbar
                version: 1.3.0
                regeln: KoSIT XRechnung 3.0.2, EN 16931 Schematron 1.3.16, XSD UBL 2.1 / CII D16B
                regelstand: e17455c9cb03
                zeit: '2026-10-23T08:00:00.000Z'
components:
  schemas:
    Status:
      type: object
      required:
      - status
      - version
      - regeln
      - regelstand
      - zeit
      properties:
        status:
          type: string
          enum:
          - ok
          - gestört
          description: ok = bereit für Prüfungen; gestört = keine Prüfungen möglich (Grund in gruende), HTTP 503
        version:
          type: string
          description: Version der API, z. B. 1.3.0
        regeln:
          type: string
        regelstand:
          type: string
          pattern: ^[0-9a-f]{12}$
          description: 'Kennung des Regelstands: Anfang der SHA-256 über alle Regel- und Schemadateien. Gleiche Kennung = gleiche Regeln. Details: https://erechio.de/aenderungen.html (seit 1.2.0)'
        zeit:
          type: string
          format: date-time
        gruende:
          type: array
          items:
            type: string
          description: 'Nur bei gestört: Gründe ohne interne Details (seit 1.3.0)'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: 'Header `Authorization: Bearer pk_…`'
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternativ zum Bearer-Header
externalDocs:
  description: Dokumentation mit Beispielen
  url: https://erechio.de/api/