メインコンテンツへスキップ

申請API

  • 更新
このAPIは、CSVテキストをもとに、カミレスの申請データを一括作成するREST APIです。CSVの各データ行が、申請API設定で指定したフォームテンプレートの申請データ1件として作成されます。主に、外部システムのデータをCSV形式でカミレスに取り込む用途を想定しています。


1. 事前準備

  • 取り込み先のフォームテンプレートに対して、申請API設定（設定キー、CSV列と入力欄のマッピング）を作成しておく
  • 実行ユーザーに ApplicationApi を実行できる権限を付与しておく（6. 権限を参照してください）


1-1. 申請ステータスの設定

このAPIで作成される申請レコードの申請ステータスを任意に設定したい場合は、以下のような申請ステータスマスターレコードを作成してください。
  • アクション: 申請API
  • 現在申請ステータス: 空
  • 更新後申請ステータス: 希望する申請ステータス


2. エンドポイント

項目 値
URL /services/apexrest/docutizeform/Application
メソッド POST
認証 SalesforceのアクセストークンをAuthorizationヘッダーにBearer形式で指定
Content-Type application/json

レスポンスのContent-Typeは application/json（UTF-8）です。

 

3. リクエスト

3-1. リクエストボディ

{
    "settingKey": "SAMPLE_SETTING",
    "csvText": "名前,住所,電話番号\n山田太郎,東京都新宿区1-1-1,03-1234-5678\n佐藤花子,大阪府大阪市2-2-2,06-9876-5432"
}
パラメータ 型 必須 説明
settingKey String  ✓ 申請API設定（ApplicationAPISetting__c.SettingKey__c）に対応する設定キー
csvText String ✓ CSV テキスト。CSV 列と入力欄の対応は申請API設定で定義する

未指定または空文字の場合は 400 Bad Request を返します。
 

3-2. curl 例

curl -X POST \
    "$INSTANCE_URL/services/apexrest/docutizeform/Application" \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "settingKey": "SAMPLE_SETTING",
        "csvText": "名前,住所,電話番号\n山田太郎,東京都新宿区1-1-1,03-1234-5678"
    }'
`
$INSTANCE_URL と $ACCESS_TOKEN は、お使いの環境に合わせて次の値に置き換えてください。
  • $INSTANCE_URL: Salesforce 組織のインスタンス URL（例: https://example.my.salesforce.com）
  • $ACCESS_TOKEN: 2. エンドポイント の手順で取得したアクセストークン
 

4. レスポンス

4-1. 成功時

成功時は HTTP ステータス 201 Created を返します。
{
    "success": true,
    "inputDataIds": ["a0x000000000001AAA", "a0x000000000002AAA"],
    "errors": []
}
 
フィールド 型 説明
success Boolean  処理結果。エラーがなければ true
inputDataIds List<Id> 作成された申請データ（InputData__c）の ID 一覧。CSV のデータ行と同じ順序
errors List<ErrorDetail> エラー情報。成功時は空配列
 

4-2. 失敗時

失敗時は、内容に応じて次の HTTP ステータスを返します。
HTTP ステータス 主なケース
400 Bad Request settingKey または csvText が未指定・空、CSV フォーマット不正（閉じられていないダブルクォート）、ヘッダーが空、重複ヘッダー
404 Not Found settingKey に対応する申請API設定が存在しない（実行ユーザーに申請API設定レコードの参照権限がない場合を含む）
422 Unprocessable Entity アクセス区分が設定された項目を含むフォームテンプレート、データ行が0件、マッピングで参照する列が CSV ヘッダーに存在しない、行単位のエラー（空行、列数不一致、型変換失敗、レコード登録失敗
500 Internal Server Error CSV が空、申請API設定のマッピング定義が不正、その他の内部エラー

行単位のエラー（422）の例:
{
    "success": false,
    "inputDataIds": [],
    "errors": [
        {
            "rowIndex": 1,
            "message": "行3: 対象オブジェクト Account の登録に失敗しました。対象レコード: a0Bxx0000000001AAA 詳細: 値を入力してください: [Name]"
        },
        {
            "rowIndex": 3,
            "message": "行5: オブジェクトAccountの項目Birthdateの型変換に失敗しました: Invalid date: abc"
        }
    ]
}
 
行に紐づかないエラー（400 / 404 / 500 等）の例:
{
    "success": false,
    "inputDataIds": [],
    "errors": [
        {
            "rowIndex": null,
            "message": "API setting not found: SAMPLE_SETTING"
        }
    ]
}
 
フィールド  型  説明
rowIndex Integer または null 0 始まりのデータ行インデックス（ヘッダー行は含まない）。行に紐づかないエラーは null
message  String  人間可読なエラーメッセージ。メッセージ内の「行N」は CSV ファイル上の行位置（1始まり、ヘッダー行を含む）
  • この API は CSV の全行を 1 つのトランザクションで処理します。そのため、1 行でもエラーがある場合はリクエスト全体がロールバックされ、レコードは 1 件も作成されません。

5. 制約と注意事項

  • アクセス区分が設定された対象項目を含むフォームテンプレートでは、この API は利用できません（422 エラー）。
  • 項目の保存先設定で、保存先項目としてテキスト型以外の型の項目を指定している場合は、CSV で渡す値もその型に合わせた形式である必要があります。型に合わない値を渡した行は 422 の行単位エラーになります。
    •   日付: yyyy-MM-dd 形式
    •   日付/時間: yyyy-MM-ddTHH:mm:ssZ 形式（UTC）、または yyyy-MM-dd HH:mm:ss 形式
    •   チェックボックス: false・0・空 はオフ、それ以外はオン
    •   数値・通貨・パーセント: 数値として解釈できる文字列
  • 1 リクエストあたりの行数・サイズに独自の上限は設けていませんが、Salesforce のガバナ制限（リクエストボディの最大サイズ、CPU 時間、DML 行数等）を超えるとエラーになります。ガバナ制限エラーが返ってきた場合は、CSV を分割して再実行してください。

5-1. 対応している入力型

入力型 注意事項
テキスト、テキストエリア、数値、チェックボックス、ラジオボタン、選択リスト、日付、パスワード、メールアドレス  
数式、条件式、関数 API 実行時には自動計算されず、CSV で渡した値がそのまま設定されます。また、作成された申請を画面で開いた際に値が再計算されることに注意してください
上記以外の入力型には対応していません。
入力型に関わらず、項目の保存先設定で、設定先項目としてテキスト型以外の型を指定している場合は、CSV で渡す値もその型に合わせた形式である必要があります。型に合わない値を渡した行は `422` の行単位エラーになります。
  • 日付: yyyy-MM-dd 形式
  • 日付/時間: yyyy-MM-ddTHH:mm:ssZ 形式（UTC）、または yyyy-MM-dd HH:mm:ss 形式
  • チェックボックス: false・0・空 はオフ、それ以外はオン
  • 数値・通貨・パーセント: 数値として解釈できる文字列


6. 権限

実行ユーザーには、少なくとも次の権限が必要です。
  • Salesforce API の実行権限を持つこと
  • ApplicationApi への Apex クラスアクセスを持つこと
  • 申請API設定（ApplicationAPISetting__c）の参照権限を持つこと
  • 申請データおよび対象オブジェクトのレコード作成に必要なオブジェクト権限・項目権限を持つこと（項目レベルセキュリティを含めユーザー権限で実行されます）
標準の権限セット例として、次の系統で ApplicationApi へのアクセスが付与されています。
  • docutize_Form_Admin
  • docutize_Form_User 系
  • docutize_Form_Applicant
  • docutize_Form_Community 形
 

7. 関連記事


 

Powered by Zendesk