外部から単位を送るしくみ(連携先の作り手向け)

外部の学習・受験のしくみ(研修の記録など)から、会員の 継続教育の単位 をパレット認定へ直接送れます。団体のオーナーが発行した 連携トークン を使います。スタンダードプランの機能です。

しくみ

• 送り先(「送信先の URL」)は、管理画面の 「外部連携」 に出ます。
• 1 回の送信で、1 人・1 件の記録を送ります(HTTP の POST、本文は JSON)。
• 認証は、連携トークンを Authorization: Bearer <トークン> で付けます。
• 送った記録は 承認済み として入ります(連携を繋いだのは団体自身なので、会員の自己申告とは扱いを分けています)。

本文の項目

項目	内容
email	会員のメールアドレス(会員はメールアドレスで見つけます。大文字・小文字は区別しません)
credentialName	資格の名前(パレット認定の資格の名前と同じもの)
grade	級(資格に級があるとき)
activityName	受講・活動の名前(200 文字まで)
occurredOn	受講した日(YYYY-MM-DD)
units	単位数(0 より大きく 999 以下)
externalRef	連携先での記録の ID(必須)。同じ値で送り直しても、二重には数えません

返ってくる結果

結果	意味
201(登録した)	記録を積みました
送り直し(duplicate)	同じ externalRef の記録が、すでにあります(二重には積みません)
400	本文が JSON として読めない・項目が足りない
401	トークンが無い・正しくない(失効したトークンを含む)
403	団体の利用が停止している・スタンダードプランでない
404	会員・資格が見つからない、その会員にその資格の有効な認定がない
409	退会した会員、またはその認定で数えられる期間より前の受講日
429	送りすぎ(同じ送り元から 1 分に 120 回まで)
503	一時的に登録できない。時間をおいて送り直す

作るときに気をつけること

• externalRef は必ず付けます。送り直しのたびに二重に単位が積まれるのを防ぎます。
• 積めるのは、その認定の継続教育の期間の中の記録だけです。
• トークンは平文で保存されません。発行した画面でしか見られないので、安全に保管します。

関連する記事

• 外部連携の画面の見方
• 外部連携を使えない・トークンを発行できないとき