APIで処理する

このガイドでは、認証、Skillの検索、ドキュメントのアップロード、構造化された結果のダウンロードというVantage APIのワークフローを説明します。 達成できること: Vantage REST APIにドキュメントを送信し、構造化された抽出データをJSON形式で受け取ります。 所要時間: 約10分

前提条件

API クライアントの認証情報 (client_id と client_secret) を備えた Vantage テナント
処理対象のサンプル文書 (PDF、TIFF、JPEG、またはPNG)

まだ認証情報をお持ちでない場合は、テナント管理者が 管理 > API クライアント で API クライアントの認証情報を作成できます。

ベース URL を設定する

すべてのリクエストは、テナントのリージョン別 endpoint に送信されます。以下からリージョンを選択してください (この代入はシェルと Python の両方で使用できます) 。このガイドのすべての sample で BASE_URL を使用します。

BASE_URL="https://vantage-us.abbyy.com"

BASE_URL="https://vantage-eu.abbyy.com"

BASE_URL="https://vantage-au.abbyy.com"

ステップ1: 認証

クライアント資格情報を使用してアクセストークンを取得します。

cURL
Python

curl -X POST "$BASE_URL/auth2/connect/token" \
  -d "grant_type=client_credentials" \
  -d "scope=openid permissions global.wildcard" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

import requests

response = requests.post(
    f"{BASE_URL}/auth2/connect/token",
    data={
        "grant_type": "client_credentials",
        "scope": "openid permissions global.wildcard",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
    },
)

token = response.json()["access_token"]

レスポンスには access_token (有効期限：24時間) が含まれます。以降のすべてのリクエストでは、Authorization ヘッダーにこのトークンを使用してください。

ステップ2: Skillを探す

テナントで利用可能なスキルを一覧表示して、ドキュメントに適したスキルを見つけてください。

cURL
Python

curl -X GET "$BASE_URL/api/publicapi/v1/skills" \
  -H "Authorization: Bearer $TOKEN"

skills = requests.get(
    f"{BASE_URL}/api/publicapi/v1/skills",
    headers={"Authorization": f"Bearer {token}"},
).json()

for skill in skills:
    print(f"{skill['id']}: {skill['name']}")

使用するスキルの id をメモしておいてください (例：Invoice スキル) 。

ステップ3: ドキュメントを処理する

1回のAPI呼び出しでドキュメントをアップロードし、Skillで処理します。

cURL
Python

curl -X POST "$BASE_URL/api/publicapi/v1/transactions/launch?skillId=SKILL_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F 'Model={"files": [{}]}' \
  -F "Files=@invoice.pdf;type=application/pdf"

with open("invoice.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/api/publicapi/v1/transactions/launch",
        params={"skillId": "SKILL_ID"},
        headers={"Authorization": f"Bearer {token}"},
        files={
            "Model": (None, '{"files": [{}]}', "application/json"),
            "Files": ("invoice.pdf", f, "application/pdf"),
        },
    )

transaction_id = response.json()["transactionId"]

ステップ4：ステータスを確認する

処理が完了するまでトランザクションをポーリングします。

cURL
Python

curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID" \
  -H "Authorization: Bearer $TOKEN"

import time

while True:
    status = requests.get(
        f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}",
        headers={"Authorization": f"Bearer {token}"},
    ).json()

    print(f"Status: {status['status']}")

    if status["status"] == "Processed":
        break
    if status["status"] in ("Failed", "Canceled"):
        raise Exception("Processing failed")

    time.sleep(5)

5～10秒ごとにポーリングしてください。通常、処理にはドキュメントの複雑さに応じて10～30秒かかります。

ステップ5：結果のダウンロード

抽出されたデータをJSON形式で取得します。結果ファイルの識別子は、ステップ4でポーリングしたトランザクションステータスレスポンスから取得できます。documents[].resultFiles[] の各エントリには fileId と type が含まれます。デフォルトでは、Document skillは2つの結果ファイルを生成します。type: "Json" (fieldのメタデータを含む完全な結果) と type: "FieldsJson" (抽出された値。最初に確認する対象として最適です) です。Skillのエクスポート設定により、他の形式を追加することもできます。

cURL
Python

# トランザクションのステータスを取得し、レスポンス内のdocuments[].resultFiles[]を確認
curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID" \
  -H "Authorization: Bearer $TOKEN"

# fileIdを使用して結果ファイルをダウンロード
curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID/files/$FILE_ID/download" \
  -H "Authorization: Bearer $TOKEN" \
  -o result.json

# ステップ4のステータスレスポンスに結果ファイルが一覧表示されます
result_files = status["documents"][0]["resultFiles"]

# 値のみを含むファイルを選択
fields_file = next(f for f in result_files if f["type"] == "FieldsJson")

result = requests.get(
    f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{fields_file['fileId']}/download",
    headers={"Authorization": f"Bearer {token}"},
).json()

print(result)

値のみの結果では、Skillで定義された各fieldが、その抽出された値に対応付けられます。処理中にルールチェックに失敗した場合、ファイルにはVersionおよびFieldsと並んで、トップレベルのRuleErrors配列も含まれます。

表示例: 請求書の抽出結果（値のみ）

{
  "Version": "3.0",
  "Fields": {
    "Invoice Number": "INV-2024-0042",
    "Invoice Date": "01/15/2024",
    "Currency": "USD",
    "Total": "1,250.00",
    "Business Unit": {
      "Name": "Acme Corp",
      "City": "Springfield",
      "CountryCode": "US"
    },
    "Line Items": [
      {
        "Description": "Widget, industrial grade",
        "Quantity": "2",
        "Unit Price": "625.00",
        "Total Price": "1,250.00"
      }
    ]
  }
}

正確なフィールド名やネストの構造はスキルによって異なります。信頼度スコア、文字座標、その他のフィールドメタデータが必要な場合は、代わりにtype: "Json"の結果ファイルをダウンロードしてください。その構造についてはJSONスキーマリファレンスで説明しています。出力構造の詳細なウォークスルーについては、結果を理解するを参照してください。

完全なサンプル

表示完全な Python スクリプト

import requests
import time

# 設定
BASE_URL = "https://vantage-us.abbyy.com"
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
SKILL_ID = "YOUR_SKILL_ID"
FILE_PATH = "invoice.pdf"

# ステップ 1: 認証する
auth = requests.post(
    f"{BASE_URL}/auth2/connect/token",
    data={
        "grant_type": "client_credentials",
        "scope": "openid permissions global.wildcard",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
)
token = auth.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# ステップ 2: Skill を検索する
skills = requests.get(f"{BASE_URL}/api/publicapi/v1/skills", headers=headers).json()
print(f"Available skills: {[s['name'] for s in skills]}")

# ステップ 3: Document を処理する
with open(FILE_PATH, "rb") as f:
    launch = requests.post(
        f"{BASE_URL}/api/publicapi/v1/transactions/launch",
        params={"skillId": SKILL_ID},
        headers=headers,
        files={
            "Model": (None, '{"files": [{}]}', "application/json"),
            "Files": (FILE_PATH, f, "application/pdf"),
        },
    )
transaction_id = launch.json()["transactionId"]
print(f"Transaction: {transaction_id}")

# ステップ 4: 完了までポーリングする
while True:
    tx = requests.get(
        f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}",
        headers=headers,
    ).json()
    print(f"Status: {tx['status']}")
    if tx["status"] == "Processed":
        break
    if tx["status"] in ("Failed", "Canceled"):
        raise Exception(f"Processing failed")
    time.sleep(5)

# ステップ 5: 結果をダウンロードする（結果ファイルの ID はステータスのレスポンスから取得）
for doc in tx["documents"]:
    for rf in doc["resultFiles"]:
        if rf["type"] != "FieldsJson":
            continue
        result = requests.get(
            f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{rf['fileId']}/download",
            headers=headers,
        ).json()
        print(result)

import requests
import time

# 設定
BASE_URL = "https://vantage-eu.abbyy.com"
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
SKILL_ID = "YOUR_SKILL_ID"
FILE_PATH = "invoice.pdf"

# ステップ 1: 認証する
auth = requests.post(
    f"{BASE_URL}/auth2/connect/token",
    data={
        "grant_type": "client_credentials",
        "scope": "openid permissions global.wildcard",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
)
token = auth.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# ステップ 2: Skill を検索する
skills = requests.get(f"{BASE_URL}/api/publicapi/v1/skills", headers=headers).json()
print(f"Available skills: {[s['name'] for s in skills]}")

# ステップ 3: ドキュメントを処理する
with open(FILE_PATH, "rb") as f:
    launch = requests.post(
        f"{BASE_URL}/api/publicapi/v1/transactions/launch",
        params={"skillId": SKILL_ID},
        headers=headers,
        files={
            "Model": (None, '{"files": [{}]}', "application/json"),
            "Files": (FILE_PATH, f, "application/pdf"),
        },
    )
transaction_id = launch.json()["transactionId"]
print(f"Transaction: {transaction_id}")

# ステップ 4: 完了までポーリングする
while True:
    tx = requests.get(
        f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}",
        headers=headers,
    ).json()
    print(f"Status: {tx['status']}")
    if tx["status"] == "Processed":
        break
    if tx["status"] in ("Failed", "Canceled"):
        raise Exception(f"Processing failed")
    time.sleep(5)

# ステップ 5: 結果をダウンロードする（結果ファイルの ID はステータスのレスポンスから取得）
for doc in tx["documents"]:
    for rf in doc["resultFiles"]:
        if rf["type"] != "FieldsJson":
            continue
        result = requests.get(
            f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{rf['fileId']}/download",
            headers=headers,
        ).json()
        print(result)

import requests
import time

# 設定
BASE_URL = "https://vantage-au.abbyy.com"
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
SKILL_ID = "YOUR_SKILL_ID"
FILE_PATH = "invoice.pdf"

# ステップ 1: 認証する
auth = requests.post(
    f"{BASE_URL}/auth2/connect/token",
    data={
        "grant_type": "client_credentials",
        "scope": "openid permissions global.wildcard",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
)
token = auth.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# ステップ 2: Skill を検索する
skills = requests.get(f"{BASE_URL}/api/publicapi/v1/skills", headers=headers).json()
print(f"Available skills: {[s['name'] for s in skills]}")

# ステップ 3: ドキュメントを処理する
with open(FILE_PATH, "rb") as f:
    launch = requests.post(
        f"{BASE_URL}/api/publicapi/v1/transactions/launch",
        params={"skillId": SKILL_ID},
        headers=headers,
        files={
            "Model": (None, '{"files": [{}]}', "application/json"),
            "Files": (FILE_PATH, f, "application/pdf"),
        },
    )
transaction_id = launch.json()["transactionId"]
print(f"Transaction: {transaction_id}")

# ステップ 4: 完了までポーリングする
while True:
    tx = requests.get(
        f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}",
        headers=headers,
    ).json()
    print(f"Status: {tx['status']}")
    if tx["status"] == "Processed":
        break
    if tx["status"] in ("Failed", "Canceled"):
        raise Exception(f"Processing failed")
    time.sleep(5)

# ステップ 5: 結果をダウンロードする（結果ファイルの ID はステータスのレスポンスに含まれる）
for doc in tx["documents"]:
    for rf in doc["resultFiles"]:
        if rf["type"] != "FieldsJson":
            continue
        result = requests.get(
            f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{rf['fileId']}/download",
            headers=headers,
        ).json()
        print(result)

次のステップ

結果の確認方法

抽出されたフィールド、信頼度スコア、テーブルデータの確認方法を説明します。

API リファレンス

インタラクティブなプレイグラウンドを備えた完全な API ドキュメントです。

認証オプション

認可コードフロー、ROPC、その他の認証方法。

バッチ処理

個別の API 呼び出しで複数のドキュメントを処理し、より細かく制御できます。

はじめに

詳細情報

前提条件

ベース URL を設定する

ステップ1: 認証

ステップ2: Skillを探す

ステップ3: ドキュメントを処理する

ステップ4：ステータスを確認する

ステップ5：結果のダウンロード

完全なサンプル

次のステップ

結果の確認方法

API リファレンス

認証オプション

バッチ処理

​前提条件

​ベース URL を設定する

​ステップ1: 認証

​ステップ2: Skillを探す

​ステップ3: ドキュメントを処理する

​ステップ4：ステータスを確認する

​ステップ5：結果のダウンロード

​完全なサンプル

​次のステップ

結果の確認方法

API リファレンス

認証オプション

バッチ処理

前提条件

ベース URL を設定する

ステップ1: 認証

ステップ2: Skillを探す

ステップ3: ドキュメントを処理する

ステップ4：ステータスを確認する

ステップ5：結果のダウンロード

完全なサンプル

次のステップ