API-Dokumentation ZeugnisParser

Informationen zur Integration des ZeugnisParsers zur automatischen Analyse von Arbeitszeugnissen.


Einführung

Die verlingo API ist nach den Prinzipien von REST aufgebaut. Unsere API besitzt einen einzigen Endpunkt und wir geben über Standard-http-Response-Codes API-Fehler zurück.

Alle Zugriffe erfolgen per HTTPS auf unseren Hauptendpunkt.

https://api.verlingo.de/zeugnisanalyse
Wichtig: Ungesicherte HTTP-Anfragen nehmen wir aus Sicherheitsgründen nicht entgegen. Es werden nur HTTPS-Anfragen angenommen.

Ein Test-Endpunkt steht zur Verfügung unter:

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.


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

Identifier und API Passwort

Diese Zugangsdaten geben Sie einfach per HTTP-Authorization Header als Identifier und API-Passwort an. Der Identifier und das API-Passwort müssen base64 codiert sein.

HTTP-VERB: ("Authorization", "Basic " + IHR_API-Zugang)

API-Schlüssel

Diese Zugangsdaten geben Sie einfach per HTTP-Authorization Header als API-Schlüssel an. Der API-Schlüssel muss base64 codiert sein.

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

Anfrage

POST https://api.verlingo.de/zeugnisanalyse
Bitte beachten: Das verwendete Format muss bei jedem Request mittels des Headers Content-Type mit angegeben werden. Im Falle von JSON muss der Header auf application/json gesetzt werden.

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 Bilder der Dokumente zurückgeschickt werden sollen (default: false)

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 Bei der übermittelten Datei handelt es sich um kein Zeugnis oder das Zeugnis 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

POST Response

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", …],
        "Schweregrad": "leicht oder mittel oder schwer"
        }, …
        ],
        "Zeugnisaufteilung": [{
        "Zeugniselement": "name",
        "Anteil": 0.15
        }, …
        ],
        "StandortImDokument": [
        2,
        3,
        …
        ]
        }, …
    ],
    "GesamtnoteAggregiert": 2.1,
    "GesamtnoteLeistungbeurteilungAggregiert": 2.3,
    "GesamtnoteVerhaltenAggregiert": 2.1,
    "GesamtnoteSchlussformulierungAggregiert": 1.8,
    "CurrentCredits": 1.877
    }

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. Sollten Attribute nicht gefüllt sein, werden diese nicht mit zurückgeschickt.
Icon For Arrow-up