Verarbeitung von documents mit separaten API-Aufrufen

Ein typisches Szenario für die Verarbeitung von documents mit separaten API-Aufrufen (zum Erstellen eines Vorgangs, Hochladen einer Datei und Starten eines Vorgangs) besteht aus den folgenden Schritten:

Abrufen einer Liste aller verfügbaren Skills
Erstellen eines leeren Vorgangs
Hinzufügen eines Satzes von Dateien, die im Vorgang verarbeitet werden sollen
Starten des Vorgangs
Überwachen des Vorgangsstatus
Herunterladen von Quelldateien und Ergebnisdateien

Jede Anfrage an den Server muss Authentifizierungsinformationen (wie ein Zugriffstoken) enthalten. Weitere Informationen finden Sie unter Authentifizierung.

Eine Liste aller verfügbaren Skills abrufen

Senden Sie dazu eine GET-Anfrage an die Ressource skills:

GET https://vantage-us.abbyy.com/api/publicapi/v1/skills

GET https://vantage-eu.abbyy.com/api/publicapi/v1/skills

GET https://vantage-au.abbyy.com/api/publicapi/v1/skills

Führen Sie den folgenden Befehl aus:

curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/skills" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-eu.abbyy.com/api/publicapi/v1/skills" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-au.abbyy.com/api/publicapi/v1/skills" \
-H "Authorization: Bearer token"

Die Antwort enthält eine JSON-Datei, die in etwa wie folgt aussieht:

[
   {
      "id": "Receipt",
      "name": "Receipt",
      "type": "Document"
   },
   {
      "id": "c4b26798-07cb-11eb-adc1-0242ac120002",
      "name": "NewClassifier",
      "type": "Classification"
   },
   {
      "id": "c4b26798-07cb-11eb-adc1-0242ac120002",
      "name": "Invoice",
      "type": "Document"
   }
]

Definieren Sie die Skill-ID, die Sie verwenden möchten. Detaillierte Beschreibungen der Skills finden Sie bei den integrierten Skills.

Erstellen eines leeren Vorgangs

Senden Sie dazu die folgende POST-Anfrage an die Ressource transactions:

POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions

POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions

POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions

Führen Sie den folgenden Befehl aus:

curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions" \
-H "accept: */*" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d "{\"skillId\":\"123\"}"

curl -X POST "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions" \
-H "accept: */*" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d "{\"skillId\":\"123\"}"

curl -X POST "https://vantage-au.abbyy.com/api/publicapi/v1/transactions" \
-H "accept: */*" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d "{\"skillId\":\"123\"}"

Nach dem erfolgreichen Erstellen eines leeren Vorgangs erhalten Sie eine Antwort mit der Vorgangs-ID:

{
   "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Hinzufügen eines Dateisatzes, der im Vorgang verarbeitet werden soll

Die maximale Anzahl von Dateien in einem Vorgang beträgt 1000.

Ein Dateisatz kann auf zwei Arten hinzugefügt werden:

Direkt zum Vorgang
Zu einem Document und anschließend dieses Document zum Vorgang hinzufügen

Dateien direkt zum Vorgang hinzufügen

Senden Sie dazu eine POST-Anfrage an die Ressource transactions/<transaction-id>/files:

POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files

POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/files

POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/files

Senden Sie im Body der Anfrage die zu verarbeitende Datei. Details zu den verfügbaren Parametern zur Anpassung von Dateien finden Sie in der Swagger-API-Referenz für Ihre Region: US, EU oder AU. Führen Sie den folgenden Befehl aus:

curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/" \
-H "Authorization: Bearer token" \
-F "Files=@Invoice07.jpg; type=image/jpeg"

curl -X POST "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/" \
-H "Authorization: Bearer token" \
-F "Files=@Invoice07.jpg; type=image/jpeg"

curl -X POST "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/" \
-H "Authorization: Bearer token" \
-F "Files=@Invoice07.jpg; type=image/jpeg"

Bei Erfolg gibt der Server HTTP 200 mit einem leeren Antworttext zurück. Um die hinzugefügten Dateien und ihre Bezeichner anzuzeigen, rufen Sie GET transactions/<transaction-id>/documents ab. Sie können beliebig viele Dateien hinzufügen, indem Sie diesen Aufruf mehrfach wiederholen; beachten Sie, dass jeder Dateiname innerhalb des Vorgangs eindeutig sein muss (das Hinzufügen einer Datei mit einem doppelten Namen gibt HTTP 409 zurück). Zusätzliche Optionen zum Hochladen von Dateien:

Dateien zu einem Dokument hinzufügen

Erstellen Sie zunächst ein Dokument, indem Sie eine POST-Anfrage an die Ressource transactions/<transaction-id>/documents senden:

POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents

POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents

POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents

curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json-patch+json"

curl -X POST "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json-patch+json"

curl -X POST "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json-patch+json"

Als Antwort erhalten Sie den Dokumentbezeichner. Fügen Sie dann Dateien zum Dokument hinzu, indem Sie eine POST-Anfrage an die Ressource transactions/<transaction-id>/documents/<document-id>/sourceFiles senden:

POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles

POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles

POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles

curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/" \
-H "Authorization: Bearer token" \
-F "Files=@Invoice07.jpg; type=image/jpeg"

curl -X POST "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/" \
-H "Authorization: Bearer token" \
-F "Files=@Invoice07.jpg; type=image/jpeg"

curl -X POST "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/" \
-H "Authorization: Bearer token" \
-F "Files=@Invoice07.jpg; type=image/jpeg"

Starten des Vorgangs

Um den Vorgang mit dem angegebenen Skill und den angegebenen Dateien zu starten, senden Sie die folgende POST-Anfrage an die Ressource transactions/<transaction-id>/start:

POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/start

POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/start

POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/start

curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/start" \
-H "accept: */*" \
-H "Authorization: Bearer token" \
-d ""

curl -X POST "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/start" \
-H "accept: */*" \
-H "Authorization: Bearer token" \
-d ""

curl -X POST "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/start" \
-H "accept: */*" \
-H "Authorization: Bearer token" \
-d ""

Überwachung des Vorgangsstatus

Um den Vorgangsstatus zu überwachen, verwenden Sie eine Schleife mit kurzem Timeout (prüfen Sie den Status nicht häufiger als einmal pro Sekunde) und senden Sie eine GET-Anfrage an die Ressource transactions/<transaction_id> mit der Vorgangs-ID in der Anforderungs-URI:

GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id

GET https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id

GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id

curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id" \
-H "Authorization: Bearer token"

Die Antwort sieht in etwa wie folgt aus:

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processing", 
   "manualReviewLink": "https://vantage-us.abbyy.com/api/publicapi/v1/verify?documentIds=9838448d-72ae-4e9a-b071-2bb16f732e46",
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.JPG"
      }
   ]
}

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processing", 
   "manualReviewLink": "https://vantage-eu.abbyy.com/api/publicapi/v1/verify?documentIds=9838448d-72ae-4e9a-b071-2bb16f732e46",
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.JPG"
      }
   ]
}

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processing", 
   "manualReviewLink": "https://vantage-au.abbyy.com/api/publicapi/v1/verify?documentIds=9838448d-72ae-4e9a-b071-2bb16f732e46",
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.JPG"
      }
   ]
}

In der Antwort:

Wenn der Wert des Schlüssels status auf Folgendes gesetzt ist:
- New — der Vorgang wurde erstellt, wird aber derzeit nicht verarbeitet.
- Processing — der Vorgang wurde gestartet, aber die Ergebnisse sind noch nicht verfügbar.
- Processed — der Vorgang wurde erfolgreich abgeschlossen, und Sie können die Ergebnisse herunterladen.
- Failed — der Vorgang ist fehlgeschlagen.
- Canceled — der Vorgang wurde abgebrochen.
Der Schlüssel manualReviewLink enthält einen Link zur Weboberfläche des Clients für die Manuelle Überprüfung und ein Vantage-Zugriffstoken, falls eine Manuelle Überprüfung erforderlich ist. Dieser Link und das Token können verwendet werden, um die Ergebnisse der Klassifizierung und Feldextraktion für einen bestimmten Vorgang zu überprüfen und zu korrigieren. Bis die Überprüfung abgeschlossen ist, ist der Wert des Schlüssels status auf Processing gesetzt. Der bereitgestellte Link ist 168 Stunden lang gültig. Danach sollte mit derselben Methode ein neuer Link erstellt und für einen weiteren Zeitraum von 168 Stunden abgerufen werden. Weitere Informationen finden Sie unter Integrating manual review.

Benutzer, die über diesen Link autorisiert sind, können keine anderen Documents oder Vorgänge anzeigen oder ändern.

Bei einem Document-Skill sieht die Antwort nun etwa wie folgt aus:

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processed",
   "documents": [
      {
         "id": "9838448d-72ae-4e9a-b071-2bb16f732e46",
         "resultFiles": [
            {
               "fileId": "3a3e6245-48e1-489a-9fef-a10b5ba28515",
               "type": "Json"
            }
         ],
         "businessRulesErrors": []
      }
   ],
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.jpg"
      }
   ]
}

Im Array documents enthält jedes Dokument ein Array resultFiles. Verwenden Sie dieses Array, um die Werte von fileId abzurufen. Das Format der Ausgabedateien wird durch den verwendeten Skill definiert. Derzeit geben alle Skills die extrahierten Felder im JSON-Format zurück. Bei einem Klassifizierungs-Skill sieht die Antwort nach der Verarbeitung der Dokumente etwa wie folgt aus:

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processed",
   "documents": [
      {
         "id": "9838448d-72ae-4e9a-b071-2bb16f732e46",
         "classification": {
            "isResultClassConfident": true,
            "resultClass": {
               "id": "8f2a51d4-6c0b-4e2a-9d3e-5b7c1a9f0e64",
               "name": "Invoice"
            },
            "classConfidences": [
               {
                  "classId": "8f2a51d4-6c0b-4e2a-9d3e-5b7c1a9f0e64",
                  "className": "Invoice",
                  "confidence": 89
               },
               {
                  "classId": "2c9d7e01-4b3a-4f6c-8a15-d0e6f2b8c473",
                  "className": "PurchaseOrder",
                  "confidence": 32
               }
            ]
         }
      }
   ],
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.jpg"
      }
   ]
}

Entnehmen Sie die Klasse des Dokuments dem Schlüssel resultClass.name und prüfen Sie den Konfidenzwert jeder wahrscheinlichen Klasse in den Schlüsseln confidence (eine ganze Zahl von 0 bis 100). Bei einem Process-Skill kann die Antwort je nach den im Process-Skill verfügbaren Verarbeitungsstufen alle oder nur einen Teil der Informationen enthalten, die für Dokument- und Klassifizierungs-Skills zurückgegeben werden.

Quelldateien und Ergebnisdateien herunterladen

Nachdem die Verarbeitung abgeschlossen ist, können Sie zwei Arten von Dateien herunterladen:

Quelldateien — die ursprünglich hochgeladenen Dateien, die in ihrem ursprünglichen Binärformat zurückgegeben werden.
Ergebnisdateien — die Verarbeitungsausgabe: die extrahierten Daten, standardmäßig im JSON-Format (das Ausgabeformat wird durch die Skill festgelegt).

Quelldateien und Ergebnisdateien verwenden unterschiedliche Endpoints und unterschiedliche Dateibezeichner:

Quelldatei — GET transactions/<transaction-id>/documents/<document-id>/sourceFiles/<file-id>/download. Die Datei-ID stammt aus der Antwort von GET transactions/<transaction-id>/documents (sourceFiles[].id).
Ergebnisdatei — GET transactions/<transaction-id>/files/<file-id>/download. Die Datei-ID stammt aus dem Array resultFiles in der Antwort zum Vorgangsstatus (documents[].resultFiles[].fileId).

Um eine Liste von documents mit ihren Bezeichnern abzurufen, senden Sie eine GET-Anfrage an die Ressource transactions/<transaction-id>/documents und geben Sie die Vorgangs-ID an:

GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents

GET https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents

GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents

curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents" \
-H "Authorization: Bearer token"

Als Ergebnis erhalten Sie eine Liste aller documents, die innerhalb dieses Vorgangs erstellt wurden. Die Antwort enthält außerdem die Kennungen dieser documents, die benötigt werden können, um detaillierte Informationen zu bestimmten Dokumenten anzufordern.

Quelldateien

Um eine benötigte Quelldatei herunterzuladen, senden Sie eine GET-Anfrage an die Ressource transactions/<transaction-id>/documents/<document-id>/sourceFiles/<file-id>/download und geben Sie die Bezeichner des Vorgangs, Dokuments und der Datei aus der letzten Antwort an:

GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download

GET https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download

GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download

Führen Sie den folgenden Befehl aus:

curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download" \
-H "Authorization: Bearer token"

Die Antwort enthält die Datei im Binärformat. Wiederholen Sie diesen Schritt für alle Quelldateien.

Ergebnisdateien

Um eine Ergebnisdatei herunterzuladen, senden Sie eine GET-Anfrage an die Ressource transactions/<transaction-id>/files/<file-id>/download und geben Sie die Vorgangs-ID sowie die fileId der Ergebnisdatei an. Rufen Sie die fileId aus dem resultFiles-Array ab, das beim Überwachen des Vorgangsstatus zurückgegeben wird (jeder Eintrag hat eine fileId und einen type, z. B. Json):

GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download

GET https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download

GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download

Führen Sie den folgenden Befehl aus:

curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download" \
-H "Authorization: Bearer token"

Übersicht

Entwicklerhandbuch

Verarbeitung von documents mit separaten API-Aufrufen

Eine Liste aller verfügbaren Skills abrufen

Erstellen eines leeren Vorgangs

Hinzufügen eines Dateisatzes, der im Vorgang verarbeitet werden soll

Dateien direkt zum Vorgang hinzufügen

Dateien zu einem Dokument hinzufügen

Starten des Vorgangs

Überwachung des Vorgangsstatus

Quelldateien und Ergebnisdateien herunterladen

Quelldateien

Ergebnisdateien

​Eine Liste aller verfügbaren Skills abrufen

​Erstellen eines leeren Vorgangs

​Hinzufügen eines Dateisatzes, der im Vorgang verarbeitet werden soll

​Dateien direkt zum Vorgang hinzufügen

​Dateien zu einem Dokument hinzufügen

​Starten des Vorgangs

​Überwachung des Vorgangsstatus

​Quelldateien und Ergebnisdateien herunterladen

​Quelldateien

​Ergebnisdateien

Eine Liste aller verfügbaren Skills abrufen

Erstellen eines leeren Vorgangs

Hinzufügen eines Dateisatzes, der im Vorgang verarbeitet werden soll

Dateien direkt zum Vorgang hinzufügen

Dateien zu einem Dokument hinzufügen

Starten des Vorgangs

Überwachung des Vorgangsstatus

Quelldateien und Ergebnisdateien herunterladen

Quelldateien

Ergebnisdateien