Optimus API interface

Description status: 20.04.2021

Introduction

Optimus Software provides interactive RESTful API interfaces for direct integration of all audit functions directly into your system. Regardless of whether you want to integrate them with your ERP system, CRM or web store system.

APIs are central to service-to-service communication. The Optimus Software API is based on the REST paradigm, allowing you to easily connect your own landscape to our AI-powered systems. Data is transferred in JSON format, which can be easily converted to other languages. Thus we achieve platform independence.

We distinguish 2 possibilities of integration with our systems depending on which use case suits you best.

  1. All-in-one call
  2. Online VAT ID Verifier API

How to get started

To get started, you first need a valid Access Token for the APIs. You will receive this when you purchase an API license.

API plans and licenses:

  1. All-in-One Call API
    Included in the Excel-Addin Enterprise license (Click here for Excel-AddIn price plan)
    Included in Online VAT ID Auditor Premium API and Enterprise license (Click here for Online Auditor price plan)
  2. Online VAT-ID Auditor API
    Included in the Online VAT-ID Auditor Premium API and Enterprise license (Click here for the Online Auditor price plan)

In the first variant, you receive a license key, which you send as a parameter CustomerID.

In case of variant no. 2, you have the possibility to generate an API token within the web console.

All-in-One API

Overview

The principle of this connection variant is the simplicity of the integration.

With this call you send any number of records as a simple JSON structure and additionally as parameters the desired check options.

Thus, you can start a mass check of VAT ID numbers with one call and get the results back.

If the parameters are set optionally, an audit-proof PDF report with a qualified digital signature can also be returned in this call.

If one or more of your data fields is incorrect, the interface will use AI (artificial intelligence) to make a suggestion for correcting it. You can then accept this directly if required.

Authentication

Methods

Call
Pfad
Verb
Input
Output
VAT ID check bulk query
/CheckSync
POST
Request
Response

Request Parameter

Field
Typ
Description
RequestPDFReport
bool
As the name suggests, in addition to the results in the API, it would also provide an audit-proof PDF with digital signature
RequestCorrectionData
bool
Turns on the AI-supported check with intelligent retransmission. This provides a suggestion in the result in case of unspecified data or incorrect data from your database in order to correct them.
CustomerID
string
Is the license key to use the interface. It is also the authentication for the call.
OwnUStID
string
Your own VAT ID which is a requirement for verification in Germany.
DATA
DataDTO[] (array)
If the data to be checked is an array

DataDTO

Field
Typ
Description
Id
string
Your unique ID to be able to assign the transaction later in the response. This can be e.g. your vendor or customer number, or a unique GUID.
UStID
bool
The VAT identification number to be checked
Name
string
The location to be checked
PLZ
string
The postal code to be checked
Street
string
The road to be tested

Here is an example call with 2 records:

{
    "requestPDFReport": true,        //Creates PDF Report
    "digitallySignPdfReportQtsLtv": true,      //Provides a qualified digital signature on the created PDF (for e.g. critical (compliance) processes or high transaction values).
    "transliteration": true,
    "Data": [
        {
            "id": "177",  //Unique ID e.g. from you 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"
        }
    ]
}

Results

HTTP Response Codes

Code
Description
401
Unauthorized - The CustomerID is not authorized to execute the question.
400
Error - The parameters are not set or formatted correctly.
200
The query is successful.

Resultset data

The results are as follows:

{
    "pdfBytes": "JVBERi0xLjQKJeLj....",   //PDF - Report - Base64 encoded
    "data": [
        {
            "id": "177",
            "ustId": "OK",
            "name": {
                "status": "OK"
            },
            "city": {
                "status": "OK"
            },
            "zip": {
                "status": "Error",
                "determinedData": "100 00"      //For incorrect records a correction is suggested
            },
            "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

Field
Type
Description
PdfBytes
String (Base64 encoded)
The audit-proof PDF report with qualified digital signature (BASE64 encoded)
Data
ResultDataDTO[] (array)
The VAT identification number to be checked

ResultData DTO

Field
Type
Beschreibung
Id
string
The unique mapping you sent for this record when you made the request.
UStID
CheckStatus (enum)
Result of the VAT ID check
Name
ResultStatusDTO (enum)
Result of the company audit
Location
ResultStatusDTO (enum)
Result of the local test
Street
ResultStatusDTO (enum)
Result of the road test

ResultStatus DTO

Field
Type
Description
Status
CheckStatus (enum)
The unique mapping you sent for this record when you made the request.
determinedData
string
If the status is Error, the suggestion to transfer the correct data set is made here.

CheckStatus enum

OK, //The data are valid
Error, //Data are invalid
TempError, //The verification cannot be done at the moment (e.g. BZSt. not available)
NotRequested, //You have not requested the data set
NotIndicated, //The EU office has not transmitted back an indication of correctness

Swagger UI

With Swagger you can easily visualize our API description and convert it accordingly into client-based SDK libraries to facilitate mapping the fields through your environment.

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

https://dokumentation.optimussoftware.de

Online VAT ID checker API

Overview

This variant mirrors the exact process of the check via our online VAT ID checker web console. Thus, you can fully automate the insert, the process of our web console from your system.

The interface includes the following functions:

  • Insert / Update / Delete data in the online console.
  • Start verification / PDF is created in the web console.
  • Setting of automatic verification and interval
  • Downloading PDFs / deleting
  • Transfer of corrected data records
  • Quick check with data determination

Swagger UI

With Swagger you can easily visualize our API description and convert it accordingly into client-based SDK libraries to facilitate mapping the fields through your environment.

SWAGGER UI – API Description