Stand der Beschreibung: 20.04.2021
Optimus Software bietet Ihnen interaktive API-Schnittstellen für die direkte Integration
aller Prüfungsfunktionen in Ihr System unabhängig davon, ob Sie diese
in ein ERP-, CRM- oder Webshop-System integrieren.
APIs sind von zentraler Bedeutung für die Service-to-Service-Kommunikation.
Je nach Anwendungsfall stehen Ihnen zwei Integrationsmöglichkeiten zur Verfügung:
Die All-In-One-API ist ein zentraler, parametrisch gesteuerter API-Aufruf,
der sämtliche Prüfungsfunktionen in einem einzigen Request bündelt.
Alle fachlichen Optionen werden ausschließlich über Parameter gesteuert;
zusätzliche API-Logik ist nicht erforderlich.
Über einen einzigen Aufruf können unter anderem folgende Funktionen aktiviert oder
deaktiviert werden:
Die Prüfungsergebnisse werden direkt im Response zurückgegeben und können
unmittelbar im eigenen System weiterverarbeitet werden.
Einsatzempfehlung:
Ideal für Kunden, die die Prüfung vollständig in ihre eigenen Prozesse integrieren
möchten und maximale Flexibilität bei minimalem Integrationsaufwand benötigen.
Diese API ermöglicht die technische Anbindung und Steuerung unserer webbasierten
Optimus-Prüfer-Lösung direkt aus Ihrem System heraus.
Die fachliche Logik, Automatisierung, Prüfung und Archivierung verbleiben vollständig
in der Online-Lösung, während Ihr System die Daten und Konfiguration steuert.
Typische Anwendungsfälle:
Die eigentliche Prüfung wird automatisiert durch unsere Online-Lösung durchgeführt.
Ihr System fungiert dabei als führende Instanz für Daten und Konfiguration,
nicht für die Prüflogik selbst.
Einsatzempfehlung:
Geeignet, wenn bewährte Funktionen wie Monitoring, Automatik und revisionssichere
Archivierung genutzt werden sollen, gleichzeitig aber eine nahtlose Systemintegration
erforderlich ist.
Beide API-Typen sind Bestandteil derselben API-Lösung und können gleichzeitig genutzt
und flexibel miteinander kombiniert werden; es ist nur ein Zugang erforderlich,
die Unterscheidung erfolgt ausschließlich über die jeweiligen API-Aufrufe.
Um durchzustarten benötigen Sie zuerst eine gültigen Access Token für die APIs. Diesen erhalten Sie über die Anmeldung im Online Prüfer unter Einstellungen -> API Token.
Der Grundsatz dieser Anbindungsvariante ist die Simplizität der Integration.
Mit diesem API-Aufruf übermitteln Sie eine beliebige Anzahl von Datensätzen sowie
zusätzlich die gewünschten Prüfungsoptionen.
So können Sie mit nur einem Aufruf eine Massenprüfung von USt-ID-Nummern
durchführen und die Ergebnisse direkt im Response erhalten.
Über optional gesetzte Parameter kann zusätzlich ein
revisionssicherer PDF-Bericht mit qualifizierter digitaler Signatur
zurückgegeben werden.
Sollten ein oder mehrere übermittelte Datenfelder fehlerhaft oder unvollständig sein,
liefert die Schnittstelle die korrekt ermittelten Werte als Vorschlag zurück.
Diese können bei Bedarf direkt übernommen und zur Stammdatenkorrektur verwendet werden.
Dieser Endpunkt stellt den zentralen All-In-One-Prüfaufruf dar. Über einen einzelnen POST-Request können eine oder mehrere USt-ID-Prüfungen durchgeführt und vollständig über Parameter gesteuert werden.
Die Schnittstelle unterstützt einfache und qualifizierte Prüfungen sowie optionale Zusatzfunktionen wie PDF-Prüfberichte, qualifizierte digitale Zeitstempel-Signaturen, Transliteration und Stammdatenkorrekturen.
Alle Prüfungsergebnisse werden synchron im Response zurückgegeben und können unmittelbar im aufrufenden System weiterverarbeitet werden.
Beispielaufruf mit 2 Datenzeilen (Kommentare dienen ausschließlich der Erläuterung sind nicht Bestandteil des Request):
POST /api/implementation/direct-check
Authorization: Bearer <AUTH_TOKEN>
Content-Type: application/json
{
"requestPDFReport": true,
// Erstellt einen PDF-Prüfbericht aus den Prüfdaten
"digitallySignPdfReportQtsLtv": true,
// Aktiviert eine qualifizierte digitale Zeitstempel-Signatur
// (nur in Kombination mit requestPDFReport)
"transliteration": true,
// Transliteriert nicht-lateinische Schriftzeichen in lateinische Schrift
"checkDataList": [
{
"id": "177",
// Eindeutige ID aus Ihrem System zur Zuordnung der Ergebnisse. Da eine USt-ID in bestimmten Konstellationen von mehreren rechtlich oder organisatorisch verbundenen Einheiten verwendet werden kann, ist die USt-ID selbst nicht zwingend eindeutig. Die id muss daher pro Datensatz eindeutig sein.
"ustId": "SI13348990",
// Zu prüfende Umsatzsteuer-Identifikationsnummer
"name": "Calcit",
// Optionaler Firmenname für die qualifizierte Prüfung
"zip": "2005",
// Optionale Postleitzahl
"street": "Stahovica"
// Optionale Straße und Hausnummer
},
{
"id": "214",
"ustId": "CZ24801224",
"name": "HM pro cz s.r.o.",
"city": "PRAHA 10",
"zip": "1005"
}
]
}
Die Ergebnisse würden dann wie folgt aussehen:
{
"pdfBytes": "JVBERi0xLjQKJeLj....",
// Optional: Base64-kodierter PDF-Prüfbericht
// Wird nur zurückgegeben, wenn requestPDFReport=true gesetzt wurde
"data": [
{
"id": "177",
// Die im Request übergebene eindeutige ID zur Zuordnung des Ergebnisses
"ustID": "OK",
// Gesamtergebnis der USt-ID-Prüfung
"name": {
"status": "OK"
// Firmenname stimmt überein
},
"ort": {
"status": "OK"
// Ort stimmt überein
},
"plz": {
"status": "ERROR",
"determinedData": "100 00"
// Bei nicht übereinstimmenden Angaben wird ein korrigierter Wert vorgeschlagen
},
"strasse": {
"status": "NOT_REQUESTED",
"determinedData": "Černokostelecká 938/8"
}
},
{
//Zweiter Datensatz Ergebnis
"id": "221",
"ustID": "OK",
"name": {
"status": "ERROR",
"determinedData": "CALCIT D.O.O."
},
"ort": {
"status": "OK"
},
"plz": {
"status": "ERROR",
"determinedData": "1242"
},
"strasse": {
"status": "ERROR",
"determinedData": "015 Stahovica"
}
}
]
}
Der Quick Check dient der schnellen und unkomplizierten Prüfung einer einzelnen USt-ID. Als Eingabe wird ausschließlich die USt-ID im Pfad übergeben.
Die Schnittstelle liefert unmittelbar das Prüfergebnis sowie die zugehörigen Firmen- und Adressdaten zurück, sofern diese ermittelt werden können.
Der Quick Check eignet sich insbesondere für einfache Prüfungen ohne zusätzliche Optionen wie PDF-Berichte oder Signaturen.
GET /api/implementation/quick-check/DE284700631
Authorization: Bearer <AUTH_TOKEN>
{
"ustId": "DE284700631",
"ustIdCheckStatus": "OK",
"completeAddressDetermination": true,
"companyName": "Optimus Software GmbH",
"companyStreet": "Tal 44",
"companyZip": "80331",
"companyCity": "München"
}
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