API-Dokumentation ZeugnisParser

Informationen zur Integration des ZeugnisParsers zur automatischen Analyse von Arbeitszeugnissen.

Stand: 05/21

Einführung

Die verlingo ZeugnisParser API ist nach den Prinzipien von REST aufgebaut. Es stehen mehrere Endpunkte zur Verfügung:

Alle Zugriffe erfolgen über HTTPS.

Wichtig: Ungesicherte HTTP-Anfragen nehmen wir aus Sicherheitsgründen nicht entgegen. Es werden nur HTTPS-Anfragen angenommen.

Authentifizierung

Jeder Nutzer unserer API erhält individuelle Zugangsdaten. Sollten Sie Interesse an einer Integration unseres Services haben, dann schicken Sie uns eine kurze Email an info@verlingo.de

API-Schlüssel

Diese Zugangsdaten geben Sie einfach per HTTP-Authorization Header als API-Schlüssel an.

HTTP-VERB: ("Authorization", IHR_API-Schlüssel)

HTTP Status-Codes

Im Folgenden finden Sie eine Liste der wichtigsten HTTP-Status-Codes, die die verlingo API ausgibt, und wie Sie diese interpretieren können. Im Allgemeinen stehen 200er-Codes für einen erfolgreichen Request, 400er für einen Fehler in den Request-Daten (zum Beispiel fehlt ein zwingend anzugebender Parameter) und 500er für einen Fehler auf unseren Servern.

Code Bedeutung
200 OK Eine erfolgreiche Anfrage
400 Bad Request Liegt meist an einem Syntax-Fehler im Request-Body
401 Unauthorized Falsche oder fehlende Authentifizierung
404 Not Found Die Ressource konnte nicht gefunden werden
406 Not Acceptable Das Format der Anfrage wird nicht unterstützt
417 Expectation Failed Die übermittelte Datei konnte nicht analysiert werden
500, 502, 503 Server Error Serverfehler. Wiederholen Sie die Anfrage nach kurzer Zeit und melden Sie sich bei uns, falls der Fehler dauerhaft auftritt

Beispielanalyse

Es steht eine Beispielanalyse unter dem nachfolgenden Test-Endpunkt zur Verfügung:

GET https://zeugnisanalyse.verlingo.de/v1/beispielanalyse

Der Test-Endpunkt kann direkt ohne Authorization-Header und ohne speziellen Request-Body angesprochen werden und liefert eine Beispielantwort zurück ohne den Analyseprozess wirklich zu durchlaufen.


Zeugnisanalyse

POST https://zeugnisanalyse.verlingo.de/v1/analyse
Bitte beachten: Als Format verwenden wir JSON, dies muss mittels des Headers Content-Types (application/json) mit angegeben werden.

Request / Basis-Anfrage

http-Header:

{ 
  "Content-Type": "application/json"
  "Accept": "application/json"
  "Authorization": IHR_API-Schlüssel
}

http-Body:

{
    "DoAnalysis": {
      "Zeugnis": ["Base64(datei1)", "Base64(datei2)", …],
      "Format": "PDF" | "JPG" | "JPEG" | "PNG"
      "Dokument": "true" | "false"
    }
}

Zeugnis:

Die Größe der Dateien pro Anfrage darf 10 MB nicht überschreiten. Zudem müssen die Dateien in einem Base64 enkodierten String vorliegen und UTF-8 kodiert sein.

Wichtig: Sie können pro Anfrage mehrere Zeugnisse in einer Datei oder in mehreren Dateien an uns zur Analyse schicken. Die einzelnen Seiten eines Zeugnisses müssen zusammenhängend und in der richtigen Reihenfolge sein.

Format:

Wir akzeptieren die Formate PDF, JPG, JPEG, PNG

Dokument:

Bestimmt, ob die Bilder und die analysierte Dokumentenstruktur (Seite, Textposition, Sätze etc.) der Dokumente zurückgeschickt werden sollen (default: false).

POST Response / Antwort

Sie erhalten von unserer API immer eine Antwort im JSON-Format und den HTTP-Statuscode 200 bei einer erfolgreichen Antwort.

Basis-Struktur der Antwort

{
    "Zeugnisanalysen": [{
        "Result": "SUCCESS  oder WARNING  oder ERROR",
        "Message": "message",
        "Gesamtnote": 2.2,
        "GesamtnoteLeistungbeurteilung": 1.9,
        "GesamtnoteVerhalten": 1.7,
        "GesamtnoteSchlussformulierung": 1.5,
        "GesamtnoteProOberkategorie": [{
            "Bezeichnung": "bezeichnung",
            "Info": "info",
            "Gesamtnote": 2
        }, {
            "Bezeichnung": "bezeichnung",
            "Info": "info",
            "Gesamtnote": 1.8
        }, …
        ],
        "Vorname": "Max",
        "Nachname": "Mustermann",
        "Inhaber": "Max Mustermann",
        "Geburtsdatum": "yyyy-MM-dd",
        "Alter": 29,
        "Firma": "Firma AG",
        "Berufsbezeichnung": "berufsbezeichnung",
        "Beschaeftigungsbeginn": "yyyy-MM-dd",
        "Beschaeftigungsende": "yyyy-MM-dd",
        "BeschaeftigungsdauerInMonaten": 34,
        "Zeugnisart": "zeugnisart",
        "Seitenanzahl": 1,
        "Zeichenanzahl": 2522,
        "Wortanzahl": 241,
        "Zeugnislaenge": "Zu kurz  oder Gut  oder Zu lang",
        "Creationdate": "yyyy-MM-dd",
        "Taetigkeiten": [
            "Taetigkeiten1",
            "Taetigkeiten2",
            …
        ],
        "Auffaelligkeiten": [{
            "Beschreibung": "beschreibung",
            "Details": ["details1", "details2", …],
            "Hinweis": "hinweis",
            "Schweregrad": "leicht oder mittel oder schwer"
        }, …
        ],
        "UnterdurchschnittlicheSaetze": [{
            "Satz": "Herr Mustermann verfügt über ein solides Fachwissen, das er zur Bewältigung seiner Aufgaben erfolgreich einsetzte.",
            "Kategorie": "Fachwissen",
            "Note": "3",
            "Seite": 1,
            "Paragraph": 17,
            "IndexInParagraph": 0
        }, …
        ],
        "FehlendeKategorien": [{
            "Bezeichnung": "Arbeitsbefähigung & Belastbarkeit",
            "Kuerzel": "BELAS"
        }, …
        ],
        "Zeugnisaufteilung": [{
            "Zeugniselement": "name",
            "Anteil": 0.15
        }, …
        ],
        "StandortImDokument": [
            2,
            3,
            …
        ]
    }, …
    ],
    "GesamtnoteAggregiert": 2.1,
    "GesamtnoteLeistungbeurteilungAggregiert": 2.3,
    "GesamtnoteVerhaltenAggregiert": 2.1,
    "GesamtnoteSchlussformulierungAggregiert": 1.8,
    }

Wenn Sie das Property "Dokument" auf "true" gesetzt haben, wird die Antwort wie folgt ergänzt:

{
"Zeugnisanalysen": [
  {
    …,
    "Dokument": {
        "Pages": [
            {
                "PageNr": 1,
                "Images": [
                {
                    "Image": "Base64Image",
                    "Format": "jpg"
                },
                ...
                ],
                "Paragraphs": [
                {
                    "Page": 1,
                    "Index": 0,
                    "Content": "content",
                    "X": 1011,
                    "Y": 570,
                    "Xendpoint": 1476,
                    "Yendpoint": 662,
                    "W": 465,
                    "H": 92,
                    "Sentences": [
                        {
                            "Page": 1,
                            "ParagraphIndex": 0,
                            "Index": 0,
                            "Content": "content",
                            "Rating": 0,
                            "Category": "category",
                            "IsConfident": true oder false
                        },
                        ...
                    ]
                },
                ...
                ]
            },
          ...
        ]
      },
      …
  }, …
],
…
}
Info: Dies beschreibt die komplette Struktur der JSON Antwort.

Abfrage der Credits

Unter dem nachfolgenden Endpunkt können die aktuellen Credits abgerufen werden:

GET https://zeugnisanalyse.verlingo.de/v1/credits

Der Endpunkt muss mit der oben beschriebenen Authentifizierung, aber ohne Request-Body angesprochen werden und liefert als Antwort:

{
    "CurrentCredits": 1500 
}
Icon For Arrow-up