Skip to content

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]

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
}