SOAP Web サービス（ErpIntegrationService・BIP レポート実行）

全体像

SOAP サービスの 2 つの種類

種類	内容	主な操作
業務オブジェクト・サービス	業務オブジェクト（例：取引先）を ADF で公開したもの	`create`・`get`・`update`・`merge`・`delete`・`find`・`process`
プロセス・サービス	特定のオブジェクトに属さない業務処理を公開したもの	サービスごとの独自操作（ErpIntegrationService など）

WSDL とエンドポイントの見つけ方

製品別の SOAP Web Services ガイド（例：SOAP Web Services for Oracle Fusion Cloud Financials）で、サービス名・操作・WSDL の URL を確認します。
Developer Connect（環境上の画面）や Service Catalog Service（API）でも、業務オブジェクト・サービスを探せます。
実際の URL は https://<ホスト>/fscmService/<サービス名>?WSDL です。?WSDL を外したものがエンドポイントです（ブラウザで開くと空白ページになりますが、異常ではありません）。

REST との使い分け

観点	SOAP	REST
形式	XML	JSON
ページング	既定ではなし（大量だとタイムアウトしやすい）	`limit`・`offset`
公式の推奨	REST がない機能で使う	同等の機能があれば REST を優先
今も SOAP を使う場面	ErpIntegrationService、BIP のレポート実行、REST 未提供の機能	業務オブジェクトの登録・照会

廃止予定（deprecated）の SOAP サービス・操作もあるため、ガイドの状態（Active／Deprecated）を確認してから使います。データ取得では、属性を絞り込める find 操作を get より優先し、応答は文字列処理ではなく XML パーサーで解析します。

ErpIntegrationService

FBDI の取込や ESS ジョブの実行を、外部から自動化するためのサービスです。REST の /erpintegrations と同じ機能を SOAP で提供します（REST 版は ERP Integration Service を参照）。

WSDL：https://<ホスト>/fscmService/ErpIntegrationService?WSDL
名前空間：http://xmlns.oracle.com/apps/financials/commonModules/shared/model/erpIntegrationService/
同様の機能を持つ Financial Utilities Service は 非推奨 です。新規の利用者は ErpIntegrationService を使います。

主な操作

操作	内容
`importBulkData`	ファイルを UCM にアップロードし、ロードとインポートの ESS ジョブを実行する（FBDI 自動化の中心）
`exportBulkData`	ESS ジョブを実行し、出力とログを圧縮して UCM に置く（アウトバウンド向け）
`submitESSJobRequest`	ジョブ・パッケージとジョブ定義を指定して ESS ジョブを実行し、要求 ID を返す
`getESSJobStatus`	要求 ID で ESS ジョブの状況を返す
`getESSExecutionDetails`	子ジョブを含む実行状況を JSON 文字列で返す
`downloadESSJobExecutionDetails`	ESS ジョブの出力・ログを ZIP で返す
`uploadFileToUcm`／`getDocumentForDocumentId`	UCM へのアップロード／文書 ID によるダウンロード
`extractAndPurge`	取込結果の出力を UCM に置き、インターフェース表を削除（パージ）する

loadAndImportData と downloadExportOutput は非推奨です。代わりに importBulkData と downloadESSJobExecutionDetails を使います。

importBulkData の主な引数

引数	内容
`document`	ファイルの情報。中身（Base64）、ファイル名、コンテンツ・タイプ、文書タイトル、作成者、セキュリティ・グループ、アカウント（例：`fin$/payables$/import$`）
`jobDetails`	実行する ESS ジョブ（ジョブ定義名・パッケージ名）とパラメータ・リスト
`notificationCode`	通知の 2 桁コード。1 桁目は方法（1＝メール、2＝ベル、3＝両方）、2 桁目は条件（0＝常に、1＝成功時、2＝失敗時）。不要なら `#NULL`
`callbackURL`	完了時にジョブ状況を受け取る Web サービスの URL。不要なら `#NULL`
`jobOptions`	処理の種類を表す `キー=値` のカンマ区切り（例：`ImportOption=Y`、`ExtractFileType=ALL`、`InterfaceDetails=1`）

戻り値は、最初のジョブ（Load Interface File for Import：インポート用インタフェース・ファイルのロード）の要求 ID です。
ERP Cloud アダプタのガイドは、importBulkData を直接呼ぶ場合は jobOptions に値を設定するよう求めています。jobOptions は FBDI の取込とコールバックの受信に必要です。なお OIC では、Web サービスを直接呼ぶより、アダプタの Import Bulk Data into Oracle ERP Cloud アクションの利用が推奨されています。

BI Publisher レポートの実行

推奨：ESS ジョブにして ErpIntegrationService で取得する

公式の Integration Playbook は、BIP（Oracle Analytics Publisher）を抽出に直接使うことはサポート外とし、BICC と REST で要件を満たせない場合は次の方法を案内しています。

BIP のデータモデルとレポートを作る（BI Publisher）
そのレポートを実行する カスタム ESS ジョブ（ジョブ・タイプ BIPJobType） を定義する（ESS の基本と運用）
ErpIntegrationService の exportBulkData（または submitESSJobRequest）でジョブを実行する
getESSJobStatus で終了（SUCCEEDED・WARNING・ERROR など）を確認する。またはコールバック・イベントで受け取る
downloadESSJobExecutionDetails で出力（ZIP・Base64）を取得し、デコードして展開する

この方法なら、ジョブの監視・再実行・ログ取得を ESS の仕組みに乗せられます。

直接実行：runReport

少量で短時間に終わるレポートは、BIP のレポート・サービスの runReport 操作で直接実行することもあります。Fusion では、WS-Security で認証する ExternalReportWSSService（https://<ホスト>/xmlpserver/services/ExternalReportWSSService?WSDL）が使われます。WSDL の URL とバインディング（SOAP 1.1／1.2）は、環境の WSDL で確認してください。

要求の reportRequest の主な項目は、BI Publisher 開発者ガイドの ReportRequest 型として説明されています。

項目	内容
`reportAbsolutePath`	カタログ上のレポートのパス（例：`/Custom/Financials/XX_GL_JOURNALS.xdo`）
`attributeFormat`	出力形式（`csv`・`xml`・`pdf`・`xlsx` など。使える形式はテンプレートの種類による）
`attributeTemplate`	使うレイアウト（テンプレート）名
`parameterNameValues`	パラメータ名と値の組
`sizeOfDataChunkDownload`	`-1` で全データを 1 回の応答で返す（分割しない）

応答の reportBytes に、出力ファイルの中身が Base64 で入ります。reportContentType で形式（text/plain、application/pdf など）を確認してから保存します。

WS-Security ヘッダ

認証情報の載せ方は、クライアント側の OWSM ポリシーで次のように分かれます（詳しくは認証・認可）。

oracle/wss_username_token_over_ssl_client_policy：SOAP ヘッダーの UsernameToken。HTTPS が前提で、追加の設定は不要です。
oracle/wss_http_token_over_ssl_client_policy：HTTP ヘッダー（Basic）。curl の -u と同じです。
メッセージ保護付きのポリシー（wss11_..._with_message_protection_...）：署名・暗号化を行います。WSDL に含まれるサーバー証明書をクライアントに取り込みます。

UsernameToken を使う場合のヘッダーは、OASIS の WS-Security 標準の形です。タイムスタンプの要否はポリシーによります。

<soapenv:Header>
  <wsse:Security soapenv:mustUnderstand="1"
      xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <wsu:Timestamp wsu:Id="TS-1">
      <wsu:Created>2026-10-15T01:00:00.000Z</wsu:Created>
      <wsu:Expires>2026-10-15T01:05:00.000Z</wsu:Expires>
    </wsu:Timestamp>
    <wsse:UsernameToken wsu:Id="UT-1">
      <wsse:Username>INT_AP_USER</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">********</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
</soapenv:Header>

SoapUI 等での試し方

SoapUI で New SOAP Project を作り、Initial WSDL に https://<ホスト>/fscmService/ErpIntegrationService?WSDL を指定します。操作ごとのサンプル要求が生成されます。
試す操作（まずは参照系の getESSJobStatus が安全です）の要求を開きます。
認証を設定します。要求の認証設定で Basic を選ぶか、プロジェクトの WS-Security 設定で Username（PasswordText）と Timestamp を追加して要求に適用します。
? の箇所を値に置き換えて実行します。
応答の Base64（ファイルの中身）は、デコードしてから中身を確認します。

curl や Python からでも呼べます。公式ガイドの Python の例は、Content-Type: text/xml;charset=UTF-8 と Basic 認証ヘッダーで要求を送っています。SOAPAction は省略しても動作しますが、指定が推奨されています。

コード例

ESS ジョブの状況を照会する（getESSJobStatus）

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:typ="http://xmlns.oracle.com/apps/financials/commonModules/shared/model/erpIntegrationService/types/">
  <soapenv:Header/>
  <soapenv:Body>
    <typ:getESSJobStatus>
      <typ:requestId>2101234</typ:requestId>
    </typ:getESSJobStatus>
  </soapenv:Body>
</soapenv:Envelope>

curl -s -u "$FA_USER:$FA_PASS" \
  -H "Content-Type: text/xml;charset=UTF-8" \
  --data-binary @getESSJobStatus.xml \
  "$FA_HOST/fscmService/ErpIntegrationService"

FBDI ファイルを取り込む（importBulkData）

要素名とパラメータ・リストの並びは例です。実際には WSDL から生成した要求と、FBDI ガイドのジョブ・パラメータで確認してください。

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:typ="http://xmlns.oracle.com/apps/financials/commonModules/shared/model/erpIntegrationService/types/"
    xmlns:erp="http://xmlns.oracle.com/apps/financials/commonModules/shared/model/erpIntegrationService/">
  <soapenv:Header/>
  <soapenv:Body>
    <typ:importBulkData>
      <typ:document>
        <erp:Content>UEsDBBQAAAAIA...（ZIP を Base64 にした文字列）</erp:Content>
        <erp:FileName>AP_INV_20261015_01.zip</erp:FileName>
        <erp:ContentType>zip</erp:ContentType>
        <erp:DocumentTitle>AP_INV_20261015_01</erp:DocumentTitle>
        <erp:DocumentAccount>fin$/payables$/import$</erp:DocumentAccount>
      </typ:document>
      <typ:jobDetails>
        <erp:JobName>oracle/apps/ess/financials/payables/invoices/transactions,APXIIMPT</erp:JobName>
        <erp:ParameterList>（ジョブのパラメータをカンマ区切りで指定）</erp:ParameterList>
      </typ:jobDetails>
      <typ:notificationCode>30</typ:notificationCode>
      <typ:callbackURL>#NULL</typ:callbackURL>
      <typ:jobOptions>ExtractFileType=ALL,InterfaceDetails=1</typ:jobOptions>
    </typ:importBulkData>
  </soapenv:Body>
</soapenv:Envelope>

notificationCode の 30 は「メールとベルで、結果にかかわらず通知」を意味します。

BIP レポートを直接実行する（runReport）

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:pub="http://xmlns.oracle.com/oxp/service/PublicReportService">
  <soap:Header/>
  <soap:Body>
    <pub:runReport>
      <pub:reportRequest>
        <pub:attributeFormat>csv</pub:attributeFormat>
        <pub:parameterNameValues>
          <pub:item>
            <pub:name>P_LEDGER_ID</pub:name>
            <pub:values><pub:item>300000001234567</pub:item></pub:values>
          </pub:item>
        </pub:parameterNameValues>
        <pub:reportAbsolutePath>/Custom/Financials/XX_GL_JOURNALS.xdo</pub:reportAbsolutePath>
        <pub:sizeOfDataChunkDownload>-1</pub:sizeOfDataChunkDownload>
      </pub:reportRequest>
      <pub:appParams/>
    </pub:runReport>
  </soap:Body>
</soap:Envelope>

import base64
import sys
import xml.etree.ElementTree as ET

# 使い方：python decode_report.py response.xml output.csv
tree = ET.parse(sys.argv[1])
node = tree.getroot().find(".//{*}reportBytes")   # 名前空間に依存せず探す
if node is None or not (node.text or "").strip():
    raise SystemExit("reportBytes が見つかりません（SOAP Fault を確認してください）")

with open(sys.argv[2], "wb") as f:
    f.write(base64.b64decode(node.text))
print("保存しました:", sys.argv[2])

ErpIntegrationService の downloadESSJobExecutionDetails で受け取る ZIP も、同じように Base64 をデコードしてから展開します。

落とし穴とベストプラクティス

Base64 のまま扱う：中身はデコードしないと読めません。また Base64 は元のデータより約 3 分の 4 倍大きくなるため、大きなファイルではメモリと処理時間に注意します。
MTOM の応答を想定していない：ファイルを含む応答が MTOM（multipart/related）の添付として返ることがあります。SOAP ライブラリや OIC は自動で扱いますが、自作の HTTP クライアントでは添付部分の取り出しが必要です。OIC の ERP Cloud アダプタでは、25.02 以降の新しい接続は MTOM が既定です。
名前空間を無視して文字列で解析する：XML パーサーを使い、名前空間を正しく扱います。
未指定の引数を空のまま送る：notificationCode や callbackURL を使わないときは #NULL を指定します。
非推奨の操作を使い続ける：loadAndImportData などは、後継の操作に置き換えます。

SOAP Fault を必ずログに残す：faultstring などの内容と、呼び出し時刻・要求の内容を記録します（公式もサポート対応のために推奨しています）。
大量データは SOAP で直接やり取りしない：取込は FBDI（importBulkData）、抽出は BICC などを使います。

試験対策ポイント

対応する試験：OIC 模擬テスト（ERP Cloud アダプタによる FBDI 取込とコールバック、SOAP アダプタでの UCM ファイル取得）
覚えるポイント
- FBDI 自動化の中心は ErpIntegrationService の importBulkData。Financial Utilities Service は非推奨。
- notificationCode の 2 桁の意味（方法×条件）と、未使用時の #NULL。
- BIP による抽出は ESS ジョブ（BIPJobType）化して ErpIntegrationService で出力を取得するのが公式の案内。
- UsernameToken は SOAP ヘッダー、HTTP トークンは HTTP ヘッダー。
手を動かして確認：自動化演習：erpintegrations で取込ジョブを実行・監視する