> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 個別の API コールで documents を処理する

> 個別の ABBYY Vantage API コールで documents を処理します: 空のトランザクションを作成し、ファイルを追加し、処理を開始し、ステータスを監視し、結果をダウンロードします。

export const VantageRegion = ({children}) => {
  const STORAGE_KEY = "abbyy.vantage.region";
  const REGIONS = [{
    code: "eu",
    label: "Europe"
  }, {
    code: "us",
    label: "North America"
  }, {
    code: "au",
    label: "Australia / Asia-Pacific"
  }];
  const [region, setRegion] = useState("eu");
  const [open, setOpen] = useState(false);
  const containerRef = useRef(null);
  const dropdownRef = useRef(null);
  function safeGetSavedRegion() {
    try {
      const saved = typeof window !== "undefined" ? window.localStorage.getItem(STORAGE_KEY) : null;
      const valid = new Set(REGIONS.map(r => r.code));
      return saved && valid.has(saved) ? saved : "eu";
    } catch {
      return "eu";
    }
  }
  function safeSetSavedRegion(code) {
    try {
      if (typeof window !== "undefined") {
        window.localStorage.setItem(STORAGE_KEY, code);
      }
    } catch {}
  }
  function dispatchRegionChanged(code) {
    try {
      if (typeof window !== "undefined") {
        window.dispatchEvent(new CustomEvent("abbyy:region-changed", {
          detail: {
            code
          }
        }));
      }
    } catch {}
  }
  function replaceRegionInString(text, currentRegion) {
    if (typeof text !== "string") return text;
    const hostRegex = /https:\/\/vantage-(eu|us|au)\.abbyy\.com/gi;
    const tokenRegex = /https:\/\/vantage-\[region\]\.abbyy\.com/gi;
    const bareHostRegex = /vantage-(eu|us|au)\.abbyy\.com/gi;
    const bareTokenRegex = /vantage-\[region\]\.abbyy\.com/gi;
    return text.replace(hostRegex, `https://vantage-${currentRegion}.abbyy.com`).replace(tokenRegex, `https://vantage-${currentRegion}.abbyy.com`).replace(bareHostRegex, `vantage-${currentRegion}.abbyy.com`).replace(bareTokenRegex, `vantage-${currentRegion}.abbyy.com`);
  }
  useEffect(() => {
    setRegion(safeGetSavedRegion());
  }, []);
  useEffect(() => {
    const root = containerRef.current;
    if (!root) return;
    const anchors = root.querySelectorAll("a[href]");
    anchors.forEach(a => {
      const href = a.getAttribute("href");
      if (href) {
        const next = replaceRegionInString(href, region);
        if (next !== href) {
          a.setAttribute("href", next);
        }
      }
    });
    const walker = typeof document !== "undefined" ? document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null) : null;
    if (walker) {
      const toUpdate = [];
      let node = walker.nextNode();
      while (node) {
        const updated = replaceRegionInString(node.nodeValue, region);
        if (updated !== node.nodeValue) {
          toUpdate.push([node, updated]);
        }
        node = walker.nextNode();
      }
      toUpdate.forEach(([textNode, value]) => {
        textNode.nodeValue = value;
      });
    }
  }, [region, children]);
  useEffect(() => {
    const root = containerRef.current;
    if (!root) return;
    const anchors = root.querySelectorAll("a[href]");
    anchors.forEach(a => {
      a.style.fontWeight = "600";
      a.style.textDecoration = "underline";
      a.style.textUnderlineOffset = "2px";
    });
  }, [region, children]);
  useEffect(() => {
    const onRegionChanged = evt => {
      const code = evt && evt.detail && evt.detail.code;
      if (!code || code === region) return;
      setRegion(code);
    };
    if (typeof window !== "undefined") {
      window.addEventListener("abbyy:region-changed", onRegionChanged);
    }
    return () => {
      if (typeof window !== "undefined") {
        window.removeEventListener("abbyy:region-changed", onRegionChanged);
      }
    };
  }, [region]);
  useEffect(() => {
    const onClickAway = e => {
      if (!dropdownRef.current) return;
      if (!dropdownRef.current.contains(e.target)) {
        setOpen(false);
      }
    };
    document.addEventListener("click", onClickAway, true);
    return () => document.removeEventListener("click", onClickAway, true);
  }, []);
  const onSelect = code => {
    setRegion(code);
    safeSetSavedRegion(code);
    dispatchRegionChanged(code);
    setOpen(false);
  };
  const current = REGIONS.find(r => r.code === region) || REGIONS[0];
  return <div className="not-prose">
      <div className="mb-4 inline-flex items-center gap-2" ref={dropdownRef}>
        <span className="text-sm text-zinc-950/80 dark:text-white/80">Tenant Region:</span>
        <div className="relative">
          <button type="button" aria-haspopup="listbox" aria-expanded={open ? "true" : "false"} onClick={() => setOpen(v => !v)} className="h-8 px-3 rounded-md bg-zinc-900/5 dark:bg-white/5 border border-zinc-950/20 dark:border-white/20 text-sm inline-flex items-center gap-2">
            <span className="text-zinc-950 dark:text-white">{current.label}</span>
            <svg width="8" height="24" viewBox="0 -9 3 24" className="transition-transform text-gray-400 overflow-visible dark:text-gray-600 ml-auto" style={{
    transform: open ? "rotate(270deg)" : "rotate(90deg)"
  }}>
              <path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round"></path>
            </svg>
          </button>
          {open ? <div role="listbox" className="absolute z-50 left-full top-0 ml-2 w-56 rounded-xl border border-zinc-950/20 dark:border-white/20 bg-white dark:bg-zinc-900 shadow-lg p-2">
              {REGIONS.map(r => {
    const selected = r.code === region;
    return <button key={r.code} type="button" role="option" aria-selected={selected ? "true" : "false"} onClick={() => onSelect(r.code)} className={"w-full flex items-center justify-between px-3 py-2 rounded-lg text-sm hover:bg-zinc-950/5 dark:hover:bg-white/10 text-zinc-950 dark:text-white" + (selected ? " font-medium" : "")}>
                    <span style={selected ? {
      color: "#ff2038"
    } : undefined}>{r.label}</span>
                    <span className={selected ? "ml-3" : "ml-3 invisible"} style={selected ? {
      color: "#ff2038"
    } : undefined}>✓</span>
                  </button>;
  })}
            </div> : null}
        </div>
      </div>
      <div ref={containerRef} className="prose dark:prose-invert max-w-none">{children}</div>
    </div>;
};

トランザクションの作成、ファイルのアップロード、トランザクションの開始など、個別の API コールを使用して documents を処理する一般的なシナリオは、次の手順で構成されます。

1. [利用可能なすべての Skill の一覧を取得する](#receiving-a-list-of-all-available-skills)
2. [空のトランザクションを作成する](#creating-an-empty-transaction)
3. [トランザクション内で処理するファイルのセットを追加する](#adding-a-set-of-files-to-be-processed-in-the-transaction)
4. [トランザクションを開始する](#starting-the-transaction)
5. [トランザクションのステータスを監視する](#monitoring-the-transaction-status)
6. [ソースファイルと結果ファイルをダウンロードする](#downloading-source-files-and-result-files)

各リクエストには、アクセストークンなどの認証情報を必ず含める必要があります。詳細については、[認証](/ja/vantage/developer/authentication/authentication) を参照してください。

<div id="receiving-a-list-of-all-available-skills">
  ### 利用可能なすべての Skill の一覧を取得する
</div>

そのためには、`skills` リソースに `GET` リクエストを送信します。

<VantageRegion>
  ```
  GET https://vantage-us.abbyy.com/api/publicapi/v1/skills
  ```
</VantageRegion>

次のコマンドを実行します：

<VantageRegion>
  ```bash theme={null}
  curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/skills" \
  -H "Authorization: Bearer token"
  ```
</VantageRegion>

レスポンスには、次のような JSON が含まれます：

```
[
   {
      "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"
   }
]
```

使用する Skill 識別子を指定します。Skill の詳細な説明は、組み込み Skill に記載されています。

<div id="creating-an-empty-transaction">
  ### 空のトランザクションを作成する
</div>

`transactions` リソースに次の `POST` リクエストを送信します。

<VantageRegion>
  ```
  POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions
  ```
</VantageRegion>

次のコマンドを実行します：

<VantageRegion>
  ```bash theme={null}
  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\"}"
  ```
</VantageRegion>

空のトランザクションが正常に作成されると、トランザクション識別子を含むレスポンスが返されます。

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

<div id="adding-a-set-of-files-to-be-processed-in-the-transaction">
  ### トランザクションで処理するファイルセットの追加
</div>

<Info>
  1 つのトランザクションに含められるファイルの最大数は 1000 件です。
</Info>

ファイルセットの追加方法は次の 2 通りです:

* [トランザクションへ直接追加](#adding-files-directly-to-the-transaction)
* [Document に追加してから、その Document をトランザクションに追加](#adding-files-to-a-document)

<div id="adding-files-directly-to-the-transaction">
  #### トランザクションにファイルを直接追加する
</div>

その場合は、`POST` リクエストを `transactions/<transaction-id>/files` リソースに送信します。

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

<VantageRegion>
  リクエストの本文に処理対象のファイルを送信します。ファイルのカスタマイズに使用できる Parameter の詳細は、[API Reference](https://vantage-us.abbyy.com/api/swagger) を参照してください。
</VantageRegion>

次のコマンドを実行します：

<VantageRegion>
  ```bash theme={null}
  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"
  ```
</VantageRegion>

その結果、追加されたファイルとその識別子の一覧を含むレスポンスが返ってきます。この呼び出しを複数回繰り返すことで、必要な数だけファイルを追加できます。

ファイルのアップロードに関する追加オプション:

* [追加した画像の編集](/ja/vantage/developer/processing-documents/editing-added-images)
* [ファイルとドキュメントの順序の設定](/ja/vantage/developer/processing-documents/ordering-files-and-docs)

<div id="adding-files-to-a-document">
  #### Document にファイルを追加する
</div>

まず、`POST` リクエストを `transactions/<transaction-id>/documents` リソースに送信して、Document を作成します。

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

<VantageRegion>
  ```bash theme={null}
  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"
  ```
</VantageRegion>

その結果、Document 識別子を含むレスポンスが返されます。

次に、`transactions/<transaction-id>/documents/<document-id>/sourceFiles` リソースに `POST` リクエストを送信して、Document にファイルを追加します。

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

<VantageRegion>
  ```bash theme={null}
  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"
  ```
</VantageRegion>

<div id="starting-the-transaction">
  ### トランザクションの開始
</div>

指定した Skill とファイルでトランザクションを開始するには、`transactions/<transaction-id>/start` リソースに次の `POST` リクエストを送信します。

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

<VantageRegion>
  ```bash theme={null}
  curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/start" \
  -H "accept: */*" \
  -H "Authorization: Bearer token" \
  -d ""
  ```
</VantageRegion>

<div id="monitoring-the-transaction-status">
  ### トランザクションのステータスを監視する
</div>

短いタイムアウトを設定したループでトランザクションのステータス監視を開始するには (1秒より高頻度の確認は推奨しません) 、リクエストURIにトランザクション識別子を含めて `transactions/<transaction_id>` リソースへ `GET` リクエストを送信します。

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

<VantageRegion>
  ```bash theme={null}
  curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id" \
  -H "Authorization: Bearer token"
  ```
</VantageRegion>

レスポンスは次のようになります。

```
{
   "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"
      }
   ]
}
```

レスポンスでは、次のようになります。

* **status** キーの値が次のいずれかに設定されている場合:
  * **New** — トランザクションは作成されていますが、現在は処理中ではありません。
  * **Processing** — トランザクションは開始されていますが、結果はまだ準備できていません。
  * **Processed** — トランザクションは正常に完了しており、結果をダウンロードできます。
  * **Failed** — トランザクションは失敗しました。
  * **Canceled** — トランザクションはキャンセルされました。
* **manualReviewLink** キーには、手動確認が必要な場合、手動確認クライアントのWebインターフェイスへのリンクとVantage access token が含まれます。このリンクとトークンを使用すると、特定のトランザクションの分類および field extraction の結果を確認し、修正できます。確認が完了するまで、**status** キーの値は **Processing** に設定されます。提供されたリンクは 168 時間有効です。有効期限が切れた場合は、同じ方法で新しいリンクを作成して取得し、さらに 168 時間利用する必要があります。詳しくは、[手動確認の統合](/ja/vantage/developer/integrating-manual-review) を参照してください。

<Info>
  このリンクを使用して認証されたユーザーは、他の documents やトランザクションを表示または変更できません。
</Info>

documents skill の場合、レスポンスは次のようになります。

```
{
   "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"
      }
   ]
}
```

**documents** 配列では、各 documents に **resultFiles** 配列があります。**fileId** の値を取得するには、この配列を使用します。出力ファイルの形式は、使用する Skill によって決まります。現在、すべての Skill は抽出されたフィールドを [JSON 形式](/ja/vantage/developer/output/json/json-output) で返します。

分類スキルの場合、documents が処理された後に返されるレスポンスは、次のようになります。

```
{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processed",
   "documents": [
      {
         "id": "9838448d-72ae-4e9a-b071-2bb16f732e46",
         "classification": {
            "isResultClassConfident": true,
            "resultClass": "Invoice",
            "classConfidences": [
               {
                  "class": "Invoice",
                  "confidence": 89
               },
               {
                  "class": "PurchaseOrder",
                  "confidence": 32
               }
            ]
         }
      }
   ],
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.jpg"
      }
   ]
}
```

Document のクラスを **resultClass** キーから取得し、各候補クラスの信頼度を **confidence** キーで確認します。

Process skill の場合、レスポンスには、Process skill で利用可能なステージに応じて、Document および分類スキルで返される情報の全部または一部が含まれることがあります。

<div id="downloading-source-files-and-result-files">
  ### ソースファイルと結果ファイルのダウンロード
</div>

処理が完了すると、2 種類のファイルをダウンロードできます。

* **ソースファイル** — アップロードした元のファイルで、元のバイナリ形式のまま返されます。
* **結果ファイル** — 処理結果の出力ファイルです。既定では、抽出データが [JSON 形式](/ja/vantage/developer/output/json/json-output) で返されます (出力形式は Skill で設定されます) 。

<Info>
  ソースファイルと結果ファイルでは、使用するエンドポイントとファイル識別子が異なります。

  * **ソースファイル** — `GET transactions/<transaction-id>/documents/<document-id>/sourceFiles/<file-id>/download`。ファイル ID は `GET transactions/<transaction-id>/documents` のレスポンス (`sourceFiles[].id`) から取得します。
  * **結果ファイル** — `GET transactions/<transaction-id>/files/<file-id>/download`。ファイル ID は [トランザクションのステータス](#monitoring-the-transaction-status) のレスポンス内の `resultFiles` 配列 (`documents[].resultFiles[].fileId`) から取得します。
</Info>

documents の識別子を含む一覧を取得するには、`transactions/<transaction-id>/documents` リソースに `GET` リクエストを送信し、トランザクションの識別子を指定します。

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

<VantageRegion>
  ```bash theme={null}
  curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents" \
  -H "Authorization: Bearer token"
  ```
</VantageRegion>

その結果、このトランザクション内で作成された documents の一覧が返されます。レスポンスにはこれらの documents の識別子も含まれており、特定の documents の詳細情報を取得する際に必要になる場合があります。

<div id="source-files">
  #### ソースファイル
</div>

必要なソースファイルをダウンロードするには、`transactions/<transaction-id>/documents/<document-id>/sourceFiles/<file-id>/download` リソースに `GET` リクエストを送信し、トランザクション、Document、ファイルの識別子 (直前のレスポンスから取得) を指定します。

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

次のコマンドを実行します。

<VantageRegion>
  ```bash theme={null}
  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"
  ```
</VantageRegion>

レスポンスにはファイルがバイナリ形式で含まれます。すべてのソースファイルに対してこの手順を繰り返します。

<div id="result-files">
  #### 結果ファイル
</div>

結果ファイルをダウンロードするには、`transactions/<transaction-id>/files/<file-id>/download` リソースに `GET` リクエストを送信し、トランザクション識別子と結果ファイルの `fileId` を指定します。`fileId` は、[トランザクションのステータスを監視](#monitoring-the-transaction-status) した際に返される `resultFiles` 配列から取得します (各エントリには `fileId` と、`Json` などの `type` が含まれます)。

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

次のコマンドを実行します。

<VantageRegion>
  ```bash theme={null}
  curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download" \
  -H "Authorization: Bearer token"
  ```
</VantageRegion>