Helfen Sie uns, die Dokumentation zu verbessern.

Mit diesem Formular können Sie fehlende, unklare oder fehlerhafte Inhalte in der Dokumentation melden und Verbesserungsvorschläge machen. Ihr Feedback hilft uns, die Qualität und Vollständigkeit kontinuierlich zu verbessern.

API - DMS Einrichtung Webservices

Die unitop API besteht aus mehreren Bestandteilen, die wir an folgendem Beispiel erläutern:

https://gob.unitop.development:7048/BC/api/gob/unitopDC/v1.0/companies?tenant=default

Servername | gob.unitop.development
Port | 7048
Instanz | BC
Firmenname | gob
Extensionname | unitopDC
Version | v1.0
Endpunkt | companies
Tenant | ?tenant=default

Mandanten

Zuerst müssen die Mandanten geladen werden, um die entsprechende ID zu erhalten. Dies geschieht über folgende URL per GET:

https://gob.unitop.development:7048/BC/api/gob/unitopDC/v1.0/companies?tenant=default

Die Autorisierung muss entsprechend der Konfiguration für den Benutzer vorgenommen werden. Als Ergebnis wird ein JSON-Format (anbei ein Beispiel) ausgegeben:

{
    "@odata.context": "https://gob.unitop.development:7048/BC/api/gob/unitopDC/v1.0/$metadata#companies",
    "value": [
        {
            "id": "c12e00fd-2b5f-eb11-bb5d-000d3a387b5c",
            "systemVersion": "17.3.20469.21356",
            "name": "CRONUS DE",
            "displayName": "",
            "businessProfileId": "",
            "systemCreatedAt": "2021-01-25T16:40:13.363Z",
            "systemCreatedBy": "00000000-0000-0000-0000-000000000001",
            "systemModifiedAt": "2021-01-25T16:40:13.363Z",
            "systemModifiedBy": "00000000-0000-0000-0000-000000000001"
        },
        {
            "id": "278e510f-2c5f-eb11-bb5d-000d3a387b5c",
            "systemVersion": "17.3.20469.21356",
            "name": "My Company",
            "displayName": "",
            "businessProfileId": "",
            "systemCreatedAt": "2021-01-25T16:40:42.403Z",
            "systemCreatedBy": "00000000-0000-0000-0000-000000000001",
            "systemModifiedAt": "2021-01-25T16:40:42.403Z",
            "systemModifiedBy": "00000000-0000-0000-0000-000000000001"
        }
    ]
}

Zu archivierende Dokumente

Folgende URL bezieht alle Dateien, welche zur Archivierung bereitstehen: (GET-Anfrage)

https://gob.unitop.development:7048/BC/api/gob/unitopDC/v1.0/companies({{CompanyId}})/documentsToArchive?tenant=default

Hierbei empfiehlt es sich eine Anzahl der Datensätze anzugeben, damit das Ergebnis nicht zu groß wird.

Die Variable {{CompanyId}} steht als Platzhalter für die GUID aus der Mandanten-Abfrage. Als Resultat wird erneut ein JSON-Format ausgegeben:

{ 
    "@odata.context": "https://gob.unitop.development:7048/BC/api/gob/unitopDC/v1.0/$metadata#companies(c12e00fd-2b5f-eb11-bb5d-000d3a387b5c)/documentsToArchive", 
    "value": [ 
        { 
            "@odata.etag": "W/\"JzQ0OzM3OHNuNTJwU3dOZk5ZaVhtUk1UUEJqc0NkRTJac21reGFBRExjc29VbUE9MTswMDsn\"", 
            "documentTypeNo": "DMS000008", 
            "documentNo": "{DC9E0945-2C5F-EB11-BB5D-000D3A387B5C}-27", 
            "documentVersion": 1, 
            "documentDate": "0001-01-01", 
            "contactNo": "", 
            "contactName": "", 
            "companyContactNo": "", 
            "companyContactName": "", 
            "customerNo": "", 
            "customerName": "", 
            "vendorNo": "", 
            "vendorName": "", 
            "description": "ATHENS Schreibtisch", 
            "description2": "", 
            "freeText": "Important File", 
            "errorCounter": 0, 
            "lastErrorText": "", 
            "fileName": "Lorem Ipsum.DMS000008_1", 
            "fileNameWithExtension": "Lorem Ipsum.DMS000008_1.txt.txt", 
            "fileBase64Text": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNldGV0dXIgc2FkaXBzY2luZyBlbGl0ciwgc2VkIGRpYW0gbm9udW15IGVpcm1vZCB0ZW1wb3IgaW52aWR1bnQgdXQgbGFib3JlIGV0IGRvbG9yZSBtYWduYSBhbGlxdXlhbSBlcmF0LCBzZWQgZGlhbSB2b2x1cHR1YS4gQXQgdmVybyBlb3MgZXQgYWNjdXNhbSBldCBqdXN0byBkdW8gZG9sb3JlcyBldCBlYSByZWJ1bS4gU3RldCBjbGl0YSBrYXNkIGd1YmVyZ3Jlbiwgbm8gc2VhIHRha2ltYXRhIHNhbmN0dXMgZXN0IExvcmVtIGlwc3VtIGRvbG9yIHNpdCBhbWV0LiBMb3JlbSBpcHN1bSBkb2xvciBzaXQgYW1ldCwgY29uc2V0ZXR1ciBzYWRpcHNjaW5nIGVsaXRyLCBzZWQgZGlhbSBub251bXkgZWlybW9kIHRlbXBvciBpbnZpZHVudCB1dCBsYWJvcmUgZXQgZG9sb3JlIG1hZ25hIGFsaXF1eWFtIGVyYXQsIHNlZCBkaWFtIHZvbHVwdHVhLiBBdCB2ZXJvIGVvcyBldCBhY2N1c2FtIGV0IGp1c3RvIGR1byBkb2xvcmVzIGV0IGVhIHJlYnVtLiBTdGV0IGNsaXRhIGthc2QgZ3ViZXJncmVuLCBubyBzZWEgdGFraW1hdGEgc2FuY3R1cyBlc3QgTG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQu" 
        }, 
        { 
            "@odata.etag": "W/\"JzQ0O29TbTJZZjRFc2FvRnpMSGtxNmowRkZ5ejMzbU5Jcjl2ZUZ6aTdzNjZlV2M9MTswMDsn\"", 
            "documentTypeNo": "DMS000008", 
            "documentNo": "{E29E0945-2C5F-EB11-BB5D-000D3A387B5C}-27", 
            "documentVersion": 1, 
            "documentDate": "0001-01-01", 
            "contactNo": "", 
            "contactName": "", 
            "companyContactNo": "", 
            "companyContactName": "", 
            "customerNo": "", 
            "customerName": "", 
            "vendorNo": "", 
            "vendorName": "", 
            "description": "AMSTERDAM Lampe", 
            "description2": "", 
            "freeText": "Invoice 4711", 
            "errorCounter": 0, 
            "lastErrorText": "", 
            "fileName": "d3 Belegarchivierung.DMS000008_1", 
            "fileNameWithExtension": "d3 Belegarchivierung.DMS000008_1.pdf.pdf", 
            "fileBase64Text": "JVBERi0xLjcNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFuZyhkZ…" 
        } 
    ] 
}

Die Datei steht entsprechend in dem fileBase64Text als Base64 konvertiert zur Verfügung. Primärschlüssel hierbei sind:

documentTypeNo
documentNo
documentVersion

Die anderen Felder sind rein informativ.

Archivierung Dokumente

Bei der Archivierung von Dokumenten gibt es verschiedene Anfragetypen (Post, Get, Delete, Put). Wir verwenden bei Webservices nur diese beiden:

POST - Eine Änderung übertragen,
GET - Einen oder mehrere Datensätze abholen.

Um ein Dokument zu archivieren, ist ein Anfragetyp "POST" notwendig:

https://gob.unitop.development:7048/BC/api/gob/unitopDC/v1.0/companies({{CompanyId}})/documentsArchiving?tenant=default

Im Body muss zwingend der entsprechende Primärschlüssel angegeben werden.

Anschließend kann im archiveErrorText eine Begründung hinterlegt werden, weshalb diese Datei nicht archiviert werden konnte.

War die Archivierung erfolgreich, muss das Feld archivedUniqueFileId gesetzt werden. Die folgende RelativeServerURL wird anschließend automatisch anhand der Basis-URL aus der DMS-Einrichtung zusammengesetzt.

Oder alternativ wird die URL vollständig im Feld archivedDocumentRelativeServerUrl übermittelt.

Der JSON-Body sieht für die Anfrage wie folgt aus:

{    
    "documentTypeNo": "DMS000008",
    "documentNo": "{DC9E0945-2C5F-EB11-BB5D-000D3A387B5C}-27",
    "documentVersion": 1,
    "archiveErrorText": "",
    "archivedUniqueFileId": "",
    "archivedDocumentRelativeServerUrl": "http://MyExternalArchiv.com/files?id=xyz123"
}

Die Antwort entsprechend:

{
    "@odata.context": "https://gob.unitop.development:7048/BC/api/gob/unitopDC/v1.0/$metadata#companies(c12e00fd-2b5f-eb11-bb5d-000d3a387b5c)/documentsArchiving/$entity",
    "@odata.etag": "W/\"JzQ0OzJPdXBTWGxIU3hyMnYxbnlqT0luY2FraXEvYmdGRkN3dWw0M014aUdUQWc9MTswMDsn\"",
    "documentTypeNo": "DMS000008",
    "documentNo": "{DC9E0945-2C5F-EB11-BB5D-000D3A387B5C}-27",
    "documentVersion": 1,
    "archiveErrorText": "",
    "archivedUniqueFileId": "",
    "archivedDocumentRelativeServerUrl": "http://MyExternalArchiv.com/files?id=xyz123"
}

Im Falle eines Fehler kommt folgende Antwort (Response):

{
    "error": {
        "code": "Internal_RecordNotFound",
        "message": "The DMS Document To Archive does not exist. Identification fields and values: Document Type No.='DMS000008',Document No.='{DC9E0945-2C5F-EB11-BB5D-000D3A387B5C}-27',Document Version='1'  CorrelationId:  e07d17ed-9465-4a9e-9e48-2b034d50d3de."
    }
}

In diesem Beispiel wurde versucht ein Datensatz erneut zu archivieren.

Table of Contents

API - DMS Einrichtung Webservices

Mandanten

Zu archivierende Dokumente

Archivierung Dokumente