VertragsImportWebservice

Allgemein

Dieser Webservice ermöglicht Maklermitarbeitern, GDV-/CSV Dateien Hochzuladen um Verträge zu importieren. Der Maklermitarbeiter kann für sich und seine Untervermittler Vorgänge anlegen sowie den Status seiner Vorgänge abfragen.

Authentifizierung

Benötigter oAuth2 scope: ameise.imports

Der Access-Token wird im Authorization-Header übergeben:

Authorization: Bearer [Access-Token]

ServiceAccount unterstützung

Version
v1	Ja

Platzhalter

Auf dieser Seite werden folgende Platzhalter verwendet welche abhängig vom Consumer ersetzt werden müssen:

Platzhalter	Beschreibung
${pfad}	Basis-Url der Schnittstelle.
${import-datei}	Datei mit Vertragsdaten.
${auth}	Alle HTTP-Header zwecks Authentifizierung.

Basis URL

Die Basis URL's der Schnittstelle, ist wie folgt aufgebaut:

Produktiv-System:

https://imports.ameiseapis.com/api/v1

Test-System:

https://imports-ameiseapis.inte.dionera.dev/api/v1

Funktionen

Name	Method	HTTP	Response
Vertragsimport	POST	${pfad}/import	${ImportProzess-id}
Vertragsimport Prozessliste	GET	${pfad}/list	ArrayOf ImportProzess

Fehlerbehandlung

Über den Erfolg eines Aufrufs gibt der HTTP-Status-Code im Header der Antwort Aufschluss. Ist eine Aktion erfolgreich, wird i.d.R der Code 200 (OK) oder 204 (No Content) zurückgegeben.

Falls ein Fehler aufgetreten ist und die Ursache beim Client liegt, wird mit einem der 4xx codes geantwortet, liegt die Ursache beim Server mit 500 (Internal Server Error).

Liegt der Fehler beim Anwender wird zusätzlich im HTTP-Body ein JSON-Objekt mit den anzuzeigenden Meldungen ausgegeben, falls nicht, wird eine Standard-HTML-Fehlerseite ausgegeben.

Beispiel

HTTP/1.1 400 Bad Request

POST ${pfad}/import
HTTP/1.1
Content-Length: 73
Content-Type: application/json; charset=UTF-8
Date: Thu, 16 Dec 2021 14:04:20 GMT
Server: nginx

{
    "name": "Bad Request",
    "message": "no companies set",
    "code": 0,
    "status": 400
}

Request

Datentypen

Company

Name	Typ	Anmerkung
companies	ArrayOf string	Ein oder mehrere Gesellschafts-IDs, die mit der Importdatei verwendet werden sollen. Bei einem Import mit einer GDV-Datei muss min. eine Gesellschafts-ID angegeben werden.

Broker

Name	Typ	Anmerkung
broker	string	ID eines Vermittlers, der mit der Importdatei verwendet werden soll. Der Vermittler muss ein Untervermittler des Anwenders sein. Ist kein Wert gesetzt, wird der Vermittler des Anwenders für den Import genutzt.

File

Name	Typ	Anmerkung
file	${import-datei}	GDV-konforme Datei bzw. CSV-Import-Datei. Ohne eine Datei ist ein Vertragsimport nicht möglich.

Beispiel

cUrl:

curl https://imports-ameiseapis.inte.dionera.dev/api/v1/import -XPOST -H "Authorization: Bearer XXXXXX" -F "file=/transfer_11280.txt" -vvv -F "companies[0]=00000"

Requests

POST ${pfad}/import

[Request Headers]
${auth}
Content-Type: multipart/form-data; boundary=WebAppBoundary
Host: ${pfad}

[Request Body]
broker: "019999"
companies: ["00000"]
file: ${import-datei}

GET ${pfad}/list

[Request Headers]
${auth}
Host: ${pfad}

Response

Datentypen

Name	Typ	Anmerkung
process_id	string
status	string	mögliche Werte: uploaded, transmitted, received, imported, validated, customersParsed, customersPrepared, customersAssigned, customersFinalized, customersDone, contractsPrepare, contractsPrepared, contractsFinalized, processed, archived, failed
companies	ArrayOf Company	wird nur gesetzt bei Prozessen mit GDV-Dateien
broker	ArrayOf Broker
start_time	timestamp
end_time	timestamp	wird nur gesetzt im status "processed"
type	string	beschreibt die art des Datensatzes ( CSV/GDV )
amount_of_records	int	wird nur gesetzt wenn Verträge verarbeitet wurden

Company

Name	Typ	Anmerkung
id	string
name	string

Broker

Name	Typ	Anmerkung
id	string
name	string

Beispiele

HTTP/1.1 200 OK

[Response Headers] 
HTTP/1.1 200 OK
Content-Length: 37
Content-Type: application/json; charset=UTF-8
Date: Fri, 17 Dec 2021 09:16:08 GMT
Server: nginx
Vary: Accept

[POST Response] 
{
    "process_id":"acdb9bc309c530de3fe0"
}

[GET Response]
{
    "process_id": "83048b4679c6d2ecb127",
    "status": "processed",
    "broker": {
        "id": "999999",
        "name": "A & Corp"
    },
    "start_time": 1565868031,
    "end_time": null,
    "companies": [
        {
            "id": "00000",
            "name": "- Allgemein -"
        }
    ],
    "type": "GDV",
    "amount_of_records": 0
},
{
    "process_id": "f3efb0a292cdff88396a",
    "status": "contractsPrepared",
    "broker": {
        "id": "999999",
        "name": "A & Corp"
    },
    "start_time": 1610530436,
    "end_time": null,
    "type": "CSV",
    "amount_of_records": 3
}

HTTP/1.1 400 BAD REQUEST

[Response Headers]
HTTP/1.1 400 Bad Request
Content-Length: 70
Content-Type: application/json; charset=UTF-8
Date: Fri, 17 Dec 2021 09:24:17 GMT
Server: nginx
Vary: Accept

[Response] 
{
    "name": "Bad Request",
    "message": "file is empty",
    "code": 0,
    "status": 400
}