Docs機能ガイド

API INTEGRATION

配布されたAPIキーで入力ページを発行

チームAPIキーと入力内容のJSONを使って、共有できる入力ページを作成します。このガイドでは、確認項目をJSONに直接指定する基本の発行方法を紹介します。

  1. 01試用案内を受領
  2. 02APIキーを設定
  3. 03JSONを送信
  4. 04入力ページ作成

01　α用のクライアントID・APIキーを受け取る

現在はクローズドαテスト中です。登録・ログインの案内から利用方法を確認できますが、公開α環境ではアカウント登録は不要です。配布された1組を利用してください。

クライアントIDは管理・問い合わせ用です。APIはキーから所属チームを判別するため、クライアントIDを別のヘッダーに指定する必要はありません。

02　APIキーを接続元に設定

APIキーを接続元で保管し、Authorizationヘッダーに指定します。入力ページ用の8桁パスコードや、レコードのユニークキーとは別です。

Authorization: Bearer wi_YOUR_API_KEY
Content-Type: application/json

APIキーを公開ページのJavaScriptやJSON本文に含めないでください。α用キーの期限は配布案内を確認してください。

03　入力ページの内容をJSONで用意

下のJSONを request.json として保存します。これは架空の企業・製品を使った例です。日時は例示のため、requested_at は発行日時、expires_at は実際に使う将来の期限に置き換えてください。

送信用JSONをダウンロード ／ キー付き結果サンプル

request.json · 依頼全体
{  "schema_version": "1.0",  "source": {    "system": "SampleSystem",    "company_code": "SAMPLE",    "company_name": "サンプル企業",    "company_short_name": "サンプル"  },  "request": {    "idempotency_key": "45613ba6-5f17-4f23-9179-a01fb7421c95",    "form_code": "product_inspection",    "title": "製品検査の入力依頼",    "requested_at": "2030-01-10T09:00:00+09:00",    "expires_at": "2030-01-17T18:00:00+09:00"  },  "recipient": {},  "work": {    "worklist_id": 1,    "worklist_code": "JOB-001",    "model_id": 1,    "model_code": "PRODUCT-A",    "pdct_works_id": 1,    "work_id": 1,    "row": 1,    "work_title": "寸法確認",    "component_id": 1,    "component_code": "PART-A"  },  "serials": [    {      "works_data_id": 1,      "serial_id": 1,      "base_serial_number": "SN-001"    }  ],  "form": {    "fields": [      {        "key": "length_mm",        "label": "長さ",        "type": "number",        "required": true,        "unit": "mm",        "min": 9.5,        "max": 10.5      },      {        "key": "remarks",        "label": "備考",        "type": "textarea",        "required": false      }    ]  },  "notifications": {    "email": null,    "mattermost": null,    "mqtt": null  }}
情報指定するもの
source / recipient接続元システム・依頼元・依頼先。発行元チームはAPIキーで特定され、依頼元の会社名・会社コードは登録情報で補正されます。α試用では recipient は {} にします。受注チームの指定は回答時にログインが必要になるため、今回の試用では使いません。
requestタイトル・日時・期限・発行要求の識別キー。
work / serials作業と対象。現行APIでは例にあるID項目も必須です。接続元で意味の一致する安定したIDを割り当て、別の対象へ使い回さないでください。
form.fields入力項目・入力型・必須条件・範囲など。1〜100項目。
notifications通知先。通知しない場合も、例のように3つのキーをnullで指定します。

対象は1〜1,000件で、同じ依頼内の works_data_id は重複させません。過去実績はInWorks内から参照するため、過去値のJSON送信は不要です。

新規発行では idempotency_key に新しいUUIDを設定します。同じ発行要求を通信エラー等で再送するときは、同じUUIDを使います。変更した内容で新しく発行する場合は別のUUIDが必要です。

04　JSONをAPIへ送信

POST /api/v1/requests に送信します。以下の接続先・APIキーを実際の値へ置き換え、request.json を保存したディレクトリで実行してください。このDocs画面からは送信しません。

# 接続先と、その環境で発行したチームAPIキーを設定します。
export INWORKS_BASE_URL='https://intelligence-works.pages.dev'
export INWORKS_API_KEY='wi_YOUR_API_KEY'

curl --request POST "$INWORKS_BASE_URL/api/v1/requests" \
  --header "Authorization: Bearer $INWORKS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

ローカル開発の接続先は http://localhost:8088、公開環境では利用環境のHTTPS URLを使います。上記のHTTPS URLが今回の公開α環境です。

05　発行結果を受け取り、ページを開く

成功すると、新規発行ではHTTP 201と次の形式のJSONが返ります。以下は説明用の値で、実際に使えるURL・パスコードではありません。

発行レスポンスの例
{  "external_request_id": "970b224a-91e9-4d55-97af-e264100ba85a",  "process_record_id": "iw_pro_lwsiSpHpTVWXr-JkEAuoWg",  "master": {    "node_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",    "version_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"  },  "public_url": "https://intelligence-works.pages.dev/request/EXAMPLE_TOKEN",  "passcode": "12345678",  "status": "active",  "expires_at": "2030-01-17T18:00:00+09:00",  "duplicate": false}
  • public_url：生成された入力ページのURL。
  • passcode：そのページを開くための8桁のパスコード。
  • external_request_id：状態や結果の取得に使う依頼ID。接続元で保存します。
  • master：発行時にひもづいたマスタと版の参照情報。
  • duplicate：同じ企業・同じ冪等キーの再送ではtrueとなり、HTTP 200で既存の発行結果を返します。

実際に返されたURLを開き、パスコードを入力すると、JSONで定義した「長さ」「備考」の入力画面が表示されます。入力担当者へはURLとパスコードを共有してください。APIキーは共有しません。

入力ページの発行でメールによる依頼案内が自動送信されるわけではありません。URLの案内は発行元で行います。

06　結果JSONとユニークキーを取得

同じAPIキーで GET /api/v1/requests/{external_request_id}/result を呼び出します。結果には工程・シリアル・確認結果のキーが付与され、既存のvaluesと業務IDも維持されます。下はキーの対応だけを抜き出した説明用サンプルです。

結果JSONのキー部分（抜粋）
{  "process_record_id": "iw_pro_lwsiSpHpTVWXr-JkEAuoWg",  "serials": [    {      "works_data_id": 1,      "serial_record_id": "iw_pro_lwsiSpHpTVWXr-JkEAuoWg_001",      "checks": [        {          "field_key": "length_mm",          "check_record_id": "iw_pro_lwsiSpHpTVWXr-JkEAuoWg_001_001"        },        {          "field_key": "remarks",          "check_record_id": "iw_pro_lwsiSpHpTVWXr-JkEAuoWg_001_002"        }      ]    }  ]}
キーの形式・採番・更新ルール

うまく発行できない場合

HTTP確認すること
401接続先とキーの環境、Bearerの指定、キーの期限・失効状態、企業の利用状態。
403企業の利用状態や操作権限。
409定義参照方式を使う場合の未同期など。応答のエラー内容を確認してください。
422必須項目、型、重複した項目キー・対象ID、期限など。
429月間発行上限など。企業管理画面の利用数を確認してください。

タイムアウトで発行結果が分からない場合は、同じ冪等キーで再送します。新しいUUIDで送り直すと、別の依頼として発行される可能性があります。

フォーム定義の例マスタ・版管理