Optimus API Schnittstelle

Stand der Beschreibung: 20.04.2021

Einführung

Optimus Software bietet Ihnen interaktive RESTful API Schnittstellen für die direkte Integration aller Prüfungsfunktionen direkt in Ihr System. Unabhängig ob Sie diese in Ihr ERP-System, CRM oder Web-Shop System integrieren möchten.

APIs sind von zentraler Bedeutung für die Service-to-Service-Kommunikation. Die Optimus Software API orientiert sich am REST Paradigma und ermöglicht so eine problemlose Anbindung Ihrer eigenen Landschaft an unsere KI gestützten Systeme. Die Datenübertragung wird dabei, in dem einfach in andere Sprachen konvertierbaren, JSON-Format durchgeführt. Dadurch erzielen wir Plattformunabhängigkeit.

Wir unterscheiden 2 Möglichkeiten der Integration mit unseren Systemen je nach dem welcher Use-Case am besten für Sie passt.

  1. All-in-One Aufruf
  2. Online USt-ID Prüfer API

So starten Sie durch

Um durchzustarten benötigen Sie zuerst eine gültigen Access Token für die APIs. Diesen erhalten Sie bei Erwerb einer API-Lizenz.

API Pläne und Lizenzen:

  1. All-in-One Aufruf API
  2. Online USt-ID Prüfer API

Bei der ersten Variante, erhalten Sie einen Lizenzschlüssel, den Sie als Parameter CustomerID mitsenden.

Bei der Variante Nr. 2 haben Sie die Möglichkeit innerhalb der Web-Konsole einen API Token zu generieren

All-in-One API

Übersicht

Der Grundsatz dieser Anbindungsvariante ist die Simplizität bei der Integration.

Mit diesem Aufruf senden Sie eine beliebige Anzahl an Datensätzen als simple JSON Struktur und zudem als Parameter zusätzlich die gewünschten Prüfungsoptionen.

Somit können Sie mir einem Aufruf eine Massenprüfung von USt-ID Nummern starten und erhalten die Ergebnisse zurück.

Bei optional gesetzten Parametern, kann in diesem Aufruf auch eine revisionssicherer PDF-Bericht mit qualifizierter digitaler Signatur zurückgegeben werden.

Sollte beim Aufruf einer oder mehrere Ihrer Datenfelder fehlerhaft sein, wird in der Schnittstelle mithilfe von KI (künstlicher Intelligenz) ein Vorschlag unterbreitet um diese entsprechend zu berichtigen. Diesen können Sie dann bei Bedarf direkt übernehmen.

Authentifizierung

Methoden

Aufruf
Pfad
Verb
Input
Output
USt-Id Prüfung Massenabfrage
/CheckSync
POST
Request
Response

Request Parameter

Feld
Typ
Beschreibung
RequestPDFReport
bool
Wie der Name hindeutet, würde neben den Ergebnissen in der API auch eine revisionssichere PDF mit digitaler Signatur bereitstellen
RequestCorrectionData
bool
Schaltet die KI gestützte Prüfung mit intelligenter Zurückübermittlung ein. Diese liefert bei nicht angegebenen Daten oder fehlerhaften Daten aus Ihrer Datenbank einen Vorschlag im Ergebnis um diese zu berichtigen.
CustomerID
string
Ist der Lizenzschlüssel um die Schnittstelle zu nutzen. Ist auch gleich die Authentifizierung für den Aufruf.
OwnUStID
string
Ihre eigene USt-ID die in Deutschland als Voraussetzung bei der Überprüfung gilt.
DATA
DataDTO[] (array)
Sind die zu prüfenden Daten als Array

DataDTO

Feld
Typ
Beschreibung
Id
string
Ihre eindeutige ID um den Vorgang später in der Antwort zuordnen zu können. Kann z.B. Ihre Kreditoren- oder Debitorennummer sein, oder auch eine eindeutige GUID.
UStID
bool
Die zu prüfende Umsatzsteuer-Identifikationsnummer
Name
string
Die zu prüfende Ortsangabe
PLZ
string
Die zu prüfende PLZ
Strasse
string
Die zu prüfende Straße

Hier ein Beispiel Aufruf mit 2 Datensätzen:

{
    "requestPDFReport": true,        //Erstellt einen PDF-Bericht aus den Prüfungsdaten
    "digitallySignPdfReportQtsLtv": true,      //Erbringt eine qualifizierte digitale Signatur auf die erstellte PDF (für z.B. kritische (Compliance) Abläufe oder hohe Transaktionswerte)
    "transliteration": true,
    "Data": [
        {
            "id": "177",  //Eindeutige ID z.B. für die Erkennung aus Ihrem System
            "ustId": "SI13348990",
            "name": "CAlcit",
            "zip": "2005",
            "street": "stahovica"
        },
        {
            "id": "214",
            "ustId": "CZ24801224",
            "name": "HM pro cz s.r.o.",
            "city": "PRAHA 10",
            "zip": "1005"
        }
    ]
}

Ergebnisse

HTTP Response Codes

Code
Beschreibung
401
Unauthorized – Die CustomerID ist nicht berechtigt die Frage auszuführen.
400
Fehler – Die Parameter sind nicht richtig gesetzt oder formatiert.
200
Die Abfrage ist erfolgreich.

Resultset Daten

Die Ergebnisse sehen folgendermaßen aus:

{
    "pdfBytes": "JVBERi0xLjQKJeLj....",   //PDF - Bericht - Base64 kodiert
    "data": [
        {
            "id": "177",
            "ustId": "OK",
            "name": {
                "status": "OK"
            },
            "city": {
                "status": "OK"
            },
            "zip": {
                "status": "Error",
                "determinedData": "100 00"      //Für falsche Datensätze wird eine Korrektur vorgeschlagen
            },
            "street": {
                "status": "NotRequested",
                "determinedData": "Černokostelecká 938/8"
            }
        },
        {
            "id": "221",
            "ustId": "OK",
            "name": {
                "status": "Error",
                "determinedData": "CALCIT D.O.O."
            },
            "city": {
                "status": "OK",
                "determinedData": null
            },
            "zip": {
                "status": "Error",
                "determinedData": "1242"
            },
            "street": {
                "status": "Error",
                "determinedData": "015 Stahovica"
            }
        }
    ]
}

Result DTO

Feld
Typ
Beschreibung
PdfBytes
String (Base64 encoded)
Der revisionssichere PDF-Bericht mit qualifizierter digitaler Signatur (BASE64 encoded)
Data
ResultDataDTO[] (array)
Die zu prüfende Umsatzsteuer-Identifikationsnummer

ResultData DTO

Feld
Typ
Beschreibung
Id
string
Die eindeutige Zuordnung die Sie für diesen Datensatz bei der Anfrage gesendet haben.
UStID
CheckStatus (enum)
Ergebniss der USt-ID Prüfung
Name
ResultStatusDTO (enum)
Ergebniss der Firmenprüfung
Ort
ResultStatusDTO (enum)
Ergebniss der Orts-Prüfung
Strasse
ResultStatusDTO (enum)
Ergebniss der Straßen-Prüfung

ResultStatus DTO

Feld
Typ
Beschreibung
Status
CheckStatus (enum)
Die eindeutige Zuordnung die Sie für diesen Datensatz bei der Anfrage gesendet haben.
determinedData
string
Wenn Status Error, wird hier der Vorschlag zur Übernahme des richtigen Datensatzes unterbreitet.

CheckStatus enum

OK, //Die Daten sind gültig
Error, //Die Daten sind ungültig
TempError, // Die Überprüfung kann derzeit nicht erfolgen (z.B. BZSt. nicht verfügbar)
NotRequested, //Sie haben den Datensatz nicht angefragt
NotIndicated, //Die EU-Stelle hat keine Angabe zur Richtigkeit zurückübertragen

Swagger UI

Mit Swagger können Sie einfach unsere API Beschreibung visualisieren und entsprechend in Client-Basierte SDK Bibliotheken umwandeln um das Mapping der Felder durch Ihre umgebung zu erleichtern.

https://app.swaggerhub.com/apis/Optimus-Software-GbH/CloudPrueferAPI/1.2

https://dokumentation.optimussoftware.de

Online USt-ID Prüfer API

Übersicht

Diese Variante spiegelt den genauen Ablauf der Prüfung über unsere Online USt-ID Prüfer Web-Konsole dar. Somit können Sie das einfügen, den Ablauf unserer Web-Console vollständig aus Ihrem System automatisieren.

Die Schnittstelle beinhaltet folgende Funktionen:

  • Daten in die Online Konsole Einfügen / Aktualisieren / Löschen
  • Überprüfung Starten / PDF wird in der Web-Konsole angelegt.
  • Einstellung der automatischen Prüfung und des Intervalls
  • Download von PDFs / Löschen
  • Übernahme von berichtigten Datensätzen
  • Schnellprüfung mit Datenermittlung

Swagger UI

Mit Swagger können Sie einfach unsere API Beschreibung visualisieren und entsprechend in Client-Basierte SDK Bibliotheken umwandeln um das Mapping der Felder durch Ihre umgebung zu erleichtern.

SWAGGER-UI SCHNITTSTELLEN-BESCHREIBUNG