Scoutello API
Scoutello APIは、組織の連絡先、タスク、プロトコル、商談、プロジェクト、マイルストーン、イベントを双方向で同期するサーバー間APIです。読み取り専用の送信メール履歴、割り当て可能なメンバーの検索、エンティティに対応したタグの検出も提供します。このバージョンでは、増分GET/listルートと冪等性のある一括アップサートが同期の基本機能です。削除操作やWebhookは提供していません。
APIのベースURL:
https://admin.scoutello.com/api/v1
組織設定 → Developer/APIにも表示されます。OpenAPIドキュメント:
https://admin.scoutello.com/api/v1/openapi.json
キーの作成と保護
モジュール構成が可能な組織では、キーに必要なスコープに加えてCRMモジュールも有効にする必要があります。有効なキーで、未導入のモジュールを有効にすることはできません。CRMへのアクセスが利用できない場合、リクエストはエラーコードmodule_not_activeを伴うHTTP 403を返します。組織の管理者はサブスクリプションでCRMを確認または有効化できます。アクセスを有効にしてから再試行してください。
組織の管理者は、組織設定 → Developer/APIでインテグレーションとAPIキーを作成できます。完全なキーが表示されるのは一度だけです。ダイアログを閉じる前にシークレットマネージャーへコピーしてください。Scoutelloでは完全なキーを再表示できません。
- 外部システムと環境ごとに、個別のインテグレーションとキーを使用する。
- そのシステムに必要なスコープだけを付与する。
- キーをブラウザコード、URL、ソース管理、ログ、サポートメッセージ、クライアント側ストレージに決して保存しない。
- 定期的にキーをローテーションする。有効なインテグレーションをローテーションすると、置き換え後のキーは直ちに使用でき、以前のキーは外部システムが停止せずに切り替えられるよう、最長15分間有効です。以前に設定された有効期限がある場合はその期限も適用されるため、以前のキーがより早く使用できなくなることがあります。
- キーが漏えいした可能性がある場合は、ローテーション前にインテグレーションを一時停止する。一時停止すると、そのインテグレーションのすべてのキーが一時的に拒否されます。一時停止中にローテーションしても重複有効期間はありません。以前のキーは無効なままとなり、置き換え後のキーもインテグレーションを再開するまで無効です。
- 外部システムとの接続を解除する際は、インテグレーション全体を完全に取り消す。取り消すと、そのインテグレーションのすべてのキーが無効になり、元に戻すことはできません。
認証済みのすべてのリクエストでキーを送信します。
Authorization: Bearer YOUR_API_KEY
Bearer認証を推奨します。Authorizationを設定できないクライアントでは、代わりにx-api-keyを使用できます。両方のヘッダーを送信しないでください。両方のヘッダーに異なる値が含まれるリクエストは拒否されます。
このAPIはバックエンドクライアント向けであり、クロスオリジンのブラウザアクセスは有効になっていません。
キーを設定した後にGET /whoamiを使用すると、ユーザーの個人データを取得せずに、インテグレーション、組織、スコープ、キーの制限を確認できます。
スコープ
| スコープ | 許可される操作 |
|---|---|
contacts.read | 連絡先の一覧表示と取得。組織アカウントの連絡先およびアクセス権を持つメンバーの連絡先は除外されます。 |
contacts.write | 連絡先のアップサートを検証して適用します。 |
tasks.read | 非公開タスクの一覧表示と取得。 |
tasks.write | タスクのアップサートを検証して適用します。 |
protocols.read | 非公開プロトコルの一覧表示と取得。 |
protocols.write | プロトコルのアップサートを検証して適用します。 |
opportunities.read | 商談の一覧表示と取得。 |
opportunities.write | 商談のアップサートを検証して適用します。 |
projects.read | プロジェクトの一覧表示と取得。 |
projects.write | プロジェクトおよび参加者のアップサートを検証して適用します。 |
milestones.read | プロジェクトマイルストーンの一覧表示と取得。 |
milestones.write | マイルストーンのアップサートを検証して適用します。 |
members.read | 承認済みメンバーを、メンバーの Customer ID、User ID、表示名のみで一覧表示します。 |
events.read | イベントと基本スケジュールの一覧表示と取得。 |
events.write | イベントのアップサートを検証して適用します。 |
mails.read | 組織所有の送信済みメールおよび送信失敗したメールの履歴を読み取ります。 |
mail-drafts.read | この連携に固有のスタンドアロンメール承認用下書きと配信ステータスを読み取ります。 |
mail-drafts.write | 人による承認のためにメールの下書きを作成または修正します。承認や送信は行いません。 |
tags.read | 対応するエンティティ種別で選択可能なタグを検出します。 |
この API が非公開タスクや非公開プロトコルを返すことはありません。スコープが不足している場合は認可エラーが返され、空の結果として扱われることはありません。
メンバーではない CRM 連絡先は、Scoutello ログインに紐付いている場合でも読み取りおよび参照が可能です。レスポンスに含まれるのは組織の CRM フィールドのみで、User の ID 情報やアクセス権フィールドは含まれません。役割、権限、招待、承認、組織アカウントのいずれかの状態にある連絡先は引き続き非表示です。ログインに紐付いた連絡先の編集は禁止されています(protected_contact)。CRM フィールドに変更がない場合も同様です。タスクまたはプロトコルから既存の読み取り可能な連絡先を参照するには、contacts.write により、externalId、scoutelloId、および任意の externalUpdatedAt のみを使って外部リンクを設定できます。リンクメタデータのみを後から更新する場合は、externalId と任意の externalUpdatedAt を使用します。リンク設定後は、初期設定用の scoutelloId を省略してください。これによって連絡先やその User が変更されることはありません。承認済みメンバーの割り当てには、別の members.read プロジェクションを使用します。
新しいキーでは sctl_api_ プレフィックスを使用し、contacts.write のみで開始します。それ以外のスコープはすべて明示的なオプトインであり、キーの作成時またはローテーション時に組織管理者が付与する必要があります。既存の認証情報では現在のスコープが維持され、そのまま有効です。
プロジェクトに関連付けられた連絡先とメール下書き
連絡先の upsert では、projectScoutelloId / projectExternalId と companyScoutelloId / companyExternalId の任意のペアを指定できます(各ペアから1つを選択)。連絡先、会社との関係、プロジェクトメンバーシップは、アイテムごとにアトミックに保存されます。プロジェクトメンバーシップの追加には projects.write が必要です。参照を省略した場合、その他の関係とメンバーシップは維持されます。連絡先詳細の再取得結果には、projects.read が付与されている場合に projectParticipations が含まれます。営業プロジェクトのエージェントは、連絡先を再利用する場合でも、プロジェクト参照を明示的に含める必要があります。
スタンドアロンの下書きでは、ワークフローの実行を伴わず、既存の人による承認システムを使用します。
| メソッド | パス | 用途 |
|---|---|---|
| GET | /mail-drafts | ページ分割された、インテグレーションが所有する下書き。projectScoutelloId と status を任意のフィルターとして指定できます。 |
| GET | /mail-drafts/{scoutelloId} | 現在のバージョン、レビューリンク、コンテンツハッシュ、承認/送信ステータス、最終的なメール ID。 |
| GET | /mail-drafts/external/{externalId} | 安定したインテグレーション外部 ID の検索。 |
| POST | /mail-drafts/batch-upsert | 下書き準備の検証または適用。 |
下書きの準備には mail-drafts.write、contacts.read、projects.write が必要です。参照された連絡先は、プロジェクト参加者になります。承認者は、承認済みの組織メンバーで、メール編集権限を持っている必要があります。送信者の選択には、そのメンバーに既に許可されている組織または個人の送信者設定が使用されます。任意の From アドレスは受け付けられません。
{
"mode": "validate",
"records": [{
"externalId": "sales:indoor:outreach:museum:v1",
"expectedVersion": 0,
"project": { "externalId": "sales:indoor" },
"contact": { "externalId": "sales:indoor:museum:person" },
"approverScoutelloUserId": "ACCEPTED_MEMBER_USER_ID",
"senderScope": "organization",
"content": {
"to": ["verified-recipient@example.com"],
"subject": "Indoor tour proposal",
"body": "The intended email copy only.",
"notes": "Internal research and review context; not sent."
}
}]
}
すべての検証結果を確認してから、mode: "apply" で再実行してください。結果として返された ID を読み取り、reviewUrl、draftVersion、contentHash、status、dispatchStatus、mailScoutelloId を取得します。expectedVersion: 0 は作成時にのみ使用し、改訂には現在返されているバージョンを使用してください。コンテキストと承認者は変更できません。レビュー済みまたは送信済みの下書きでは、変更されたコンテンツは拒否されます。同一の再試行では、元の下書きが返されます。
下書きはプロジェクト/連絡先のメールタブと、ダッシュボードの承認通知に表示されます。APIによる準備では、通知メールを含め、メールは送信されません。既存のワークフロー通知メールの動作に変更はありません。割り当てられた担当者は、宛先、件名、本文、サポート対象の添付ファイルを編集し、バージョンを保存してから 承認して送信 できます。インテグレーションから承認や送信を実行することはできません。配信に失敗した場合や、配信結果が不明な場合に、無条件で再試行されることはありません。プロトコルベースの下書きを変換する場合は、プロトコルを保持し、置き換え先との相互参照を追加してください。
MCPアクセス
同じScoutello APIキーとスコープを、ストリーミング可能なHTTP MCPエンドポイントで使用できます。
https://admin.scoutello.com/api/v1/mcp
MCPクライアントがAuthorization: Bearer YOUR_API_KEYを送信するように設定します。従来の/api/mcp URLはパスの互換性エイリアスとして引き続き使用できますが、新しいクライアントではバージョン付きエンドポイントを使用してください。以前のsctl_mcp_認証情報は受け付けられません。Scoutello APIインテグレーションキーに置き換えてください。
MCPツールはRESTコントラクトに直接対応し、同じランタイムスキーマ、テナントチェック、インテグレーションのライフサイクル、レート制限、サービスメソッドを使用します。たとえば、contacts_list、contacts_get、contacts_get_by_external_id、contacts_batch_upsertは、連絡先に関する4つのルートに対応します。同じパターンがタスク、プロトコル、商談、プロジェクト、マイルストーン、イベントにも適用されます。メールではmails_listとmails_get、メンバーではmembers_list、タグではtags_listを使用します。
サーバーは、現在のキーのスコープで許可されているツールのみを公開します。contacts.readを持つキーでは連絡先の読み取りツールを検出できますが、contacts_batch_upsertは検出できません。contacts.writeを持つキーでは一括アップサートツールを使用できますが、読み取りツールは使用できません。whoamiは常に利用できます。書き込みツールはREST版と同じ即時効果を持つため、適用せずにバッチを確認する場合はmode: "validate"を使用してください。
MCPもサーバー間通信であり、オリジンをまたぐブラウザーアクセスを有効にするものではありません。JSON-RPCトランスポートには専用URLが必要です。そのため、認証とデータの動作は共有されていても、個別のRESTリソースURLを共有することはできません。
クライアント設定、検証、ツールマッピング、トラブルシューティングの手順については、MCPインテグレーションガイドを参照してください。
レコードの読み取り
連絡先、タスク、プロトコル、商談、プロジェクト、マイルストーン、イベントでは、同じ読み取りルートを使用します。
GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}
他の同期リソースについては、contactsをtasks、protocols、opportunities、projects、milestones、またはeventsに置き換えてください。externalIdは、このインテグレーションによってレコードがリンクされている場合に、読み取りDTOに表示されます。
リストレスポンスのエンベロープは次のとおりです。
{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}
limit は 1 以上 100 以下である必要があります。結果は、公開 API 表現が変更された実効時刻、次に Scoutello ID の順で並びます。統合リンクのメタデータが変更された場合、この実効時刻は返されたエンティティの updatedAt より後になることがあります。カーソルは不透明です。変更せずに保存・送信し、内容から意味を推測しないでください。
最初のレスポンスで、その走査における snapshotAt が確定します。別の増分読み取りを開始する前に、nextCursor が hasMore になるまで追従してください。これにより、ページネーション中にレコードが変更されても、現在の走査が不安定になることを防げます。
増分同期では、すべてのカーソルページを取得してから、その走査の snapshotAt を最新到達時刻として保存します。次の走査では、ISO 8601 形式の updatedSince 値として渡してください。下限は包括的であるため、完了したスナップショットを再試行すると境界上のレコードが返されることはありますが、取りこぼすことはありません。
単一レコードレスポンスのエンベロープは次のとおりです。
{
"data": {},
"requestId": "request-id"
}
単一コンタクトのレスポンスには relations 配列も含まれます。各関係には、Scoutello の関係 ID、作成時刻、種別、メモ、および connectedFrom と
connectedTo のコンタクト参照が保持されます。コンタクト参照には、Scoutello ID と、この統合に外部 ID が存在する場合はその外部 ID が含まれます。API の組織アクセスに関するプライバシー境界によって除外されたコンタクトは、関係を通じて公開されません。
コンタクト一覧レスポンスは簡潔な形式で、関係は含まれません。関係の詳細が必要な場合は、いずれかの単一コンタクト用ルートを使用してください。
作業フィルターとカーソルのスコープ
コンタクト一覧では、search、type(person、company、supplier、other)、status、および tagIds を指定できます。検索語はトリミングされ、大文字と小文字を区別せず、最大 200 文字かつ空白で区切られた 10 トークンまでに制限されます。各トークンは、firstName、lastName、または companyName の少なくともいずれかに含まれている必要があります。lastName に保存されている旧会社名も対象です。% や _ などの文字はリテラルとして照合されます。タグは いずれか 1 つ以上 の一致で、1~50 個の ID を指定できます。指定したすべてのフィルターは AND 条件で結合されます。REST ではタグ ID を同じパラメーターの繰り返しとしてエンコードし、MCP では配列を指定します。
GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two
コンタクトカーソルは、組織、統合、およびすべてのフィルターに紐付けられます。各ページでフィルターを維持してください。フィルターを変更すると、カーソルは拒否されます。タグの順序や重複、検索トークンの順序・大文字小文字・空白は、実効的なフィルターに影響しません。
作業一覧ルートでは、以下の追加フィルターを使用できます。それ以外のリソースとフィールドの組み合わせは拒否されます。
| リソース | フィルター |
|---|---|
| タスク | projectScoutelloId、milestoneScoutelloId、status、statusType、priority、parentState、blockedState、assignedScoutelloUserId、dueBefore、dueAfter |
| プロトコル | projectScoutelloId、milestoneScoutelloId、status(draft または final) |
| 商談 | projectScoutelloId、stage、ownerScoutelloUserId |
| プロジェクト | status、assignedContactScoutelloId |
| マイルストーン | projectScoutelloId、status、assignedContactScoutelloId、dueBefore、dueAfter |
dueBefore は排他的、dueAfter は包含的です。タスクの期限またはマイルストーンの終了日を比較します。該当する日付がないレコードは一致しません。タイムゾーン情報を含む ISO 日時を指定してください。すべてのフィルターはページネーションの前に適用されます。カーソルを続行する場合は、updatedSince を含め、まったく同じフィルターと同じ組織/インテグレーションを指定してください。ページサイズは変更できます。このリリース後、以前のスコープなしカーソルは保存済みの最新処理済みタイムスタンプから再開する必要があります。
プロジェクト、マイルストーン、割り当て、メモ
GET /members(MCP members_list)は標準のページネーションを使用し、members.read が必要です。scoutelloId(メンバーの Customer ID)、scoutelloUserId(User ID)、displayName を返します。表示されるのは、ロールを持つ承認済み組織メンバーのみです。この検索でメールアドレスや権限が公開されることはありません。
タスクでは assignedScoutelloUserIds、商談では ownerScoutelloUserId を使用します。プロジェクトとマイルストーンでは assignedContacts: [{"scoutelloId":"member-customer-id"}] を使用します。割り当てには、認証情報の組織に所属する承認済みメンバーが必要です。割り当てを省略すると既存の割り当ては変更されません。[] を指定すると割り当てが解除されます。プロジェクト、マイルストーン、タスク、プロトコルのインポートは通知なしで実行され、割り当て通知やその他の連絡は送信されません。
イベント assignedContacts では、読み取り可能な CRM 連絡先と、メンバーの Customer ID で指定された承認済みメンバーを使用できます。承認済みメンバーは通常の CRM 連絡先参照や外部リンクのリンク先としては利用できません。チームの担当者を指定するには、メンバー割り当てフィールドを使用してください。
name と projectScoutelloId または projectExternalId のいずれかを使用してマイルストーンを作成します。description(Markdown)、status(open、in_progress、completed、closed)、nullable な startDate/endDate、order(デフォルトは 0)、および assignedContacts に対応しています。終了日は開始日より前に設定できません。各マイルストーンには、インテグレーションのスコープ内で安定した外部リンクがあります。プロジェクトは API 経由では変更できません。作成時および更新時には、名前と説明が組織の言語にローカライズされます。
タスクとプロトコルでは、プロジェクト、マイルストーン、商談への参照を <entity>ScoutelloId または <entity>ExternalId として指定できます。たとえば milestoneExternalId のように指定します。各リレーションでは、null によるクリア時も含め、どちらか一方の表記のみを使用します。すべてのリレーションは、認証情報に紐付く組織に属している必要があります。マイルストーンのみを指定した参照からはプロジェクトが推測されます。指定したプロジェクトが競合する場合、またはマイルストーンを保持したままプロジェクトを明示的にクリアしようとした場合は拒否されます。プロジェクトが設定された関連商談は、作業のプロジェクトと一致している必要があります。リレーションを省略すると現在の値が保持されます。明示的な null は、残りのコンテキストが有効な場合にリレーションをクリアします。読み取り結果には、両方の ID 表記とタスクの割り当てが含まれます。
タスク計画とワークフロー
タスクの status は、固定された列挙値ではなく、タスクで有効なワークフローにおけるステータスの不変キーです。tasks.read スコープを使用して GET /task-workflows で、組織およびプロジェクトで利用可能なワークフローを読み取ります。各ステータスには、キー、ラベル、ライフサイクル type(backlog、unstarted、started、completed、または cancelled)、色、順序、デフォルトフラグ、およびアーカイブ状態が含まれます。プロジェクトの項目には、組織のワークフローを継承しているかどうかが示されます。ワークフロー設定は引き続きダッシュボードで管理します。
タスクでは、nullable な priority(low、medium、high、または urgent)および estimatedEffortMinutes に加えて、nullable な startDate と dueDate を指定できます。タスクの読み取り結果には、非正規化された statusType、親参照、簡略化されたサブタスク参照、および blockedBy / blocks 参照が含まれます。
parentTaskScoutelloId または parentTaskExternalId のいずれかを使用して、1階層のサブタスクを作成または更新します。null を使用すると、トップレベルタスクに昇格します。依存関係には、blockedBy および blocks 内で、{ "scoutelloId": "..." } または { "externalId": "..." } の参照配列を使用します。関係フィールドを省略すると既存の関係が保持され、空の依存関係配列を指定すると、その方向の依存関係がすべて解除されます。API は、入れ子になったサブタスク、親子間の依存関係、組織をまたぐ依存関係、重複、自分自身への参照、直接または推移的な循環を拒否します。
タスクリストのフィルターでは、完全一致するワークフロー status、ライフサイクル statusType、priority、parentState(top_level、subtask、または parent)、および blockedState(blocked、blocking、または unblocked)を指定できます。
プロトコルでは、status: "draft" | "final" も指定できます(新しいレコードのデフォルトは final)。新しいプロトコルには、type、date、および連絡先、または有効なプロジェクト/マイルストーンのコンテキストのいずれかが必要です。contactExternalId: null は、プロジェクト/マイルストーンのコンテキストが残っている場合に限り、連絡先を解除します。これにより、顧客を仮定せずに社内プロジェクトのメモを作成および読み取れます。下書き/確定はメモの状態を表すものであり、通信を送信することはありません。非公開のタスクとプロトコルには引き続きアクセスできません。
プロジェクト参加者
プロジェクト participants には、contact 参照をキーとする追加的なアップサートを含めます。例:
{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}
参加者は、プロジェクトに関連付けられた見込み客/顧客を表します。担当メンバーには割り当てを使用します。参加者を省略した場合、空の配列を指定した場合、参加者フィールドを省略した場合は、既存のデータが保持されます。null により、role、notes、または groupScoutelloId が解除されます。1つのペイロード内で解決済みの連絡先が重複している場合、拒否されます。グループは、選択したプロジェクトにあらかじめ所属している必要があります。読み取り結果には、participantGroups(ID/名前)と、参加者 ID、連絡先、役割、メモ、グループ ID が含まれます。参加者の削除とグループの作成は、現在ダッシュボードで利用できます。
レコードの一括アップサート
リソースの一括ルートを使用して、最大100件のレコードを書き込みます。
POST /contacts/batch-upsert
Content-Type: application/json
{
"mode": "apply",
"records": [
{
"externalId": "record-123",
"externalUpdatedAt": "2026-09-01T11:45:00.000Z",
"type": "person",
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com"
}
]
}
タスクの一括処理では、親子関係と依存関係を適用する前にタスクレコードを解決します。この2段階の処理により、親タスク、ブロッカー、またはブロックされるタスクから、同じ一括処理内で作成される別のタスクを、レコードの順序に関係なく外部 ID で参照できます。
各リソースのフィールドとバリデーション制約には、OpenAPI ドキュメントを使用してください。すべてのレコードには、1~200文字の安定した externalId が必要です。これは不透明な技術識別子として扱い、メールアドレス、名前、API シークレット、その他の個人データは使用しないでください。externalUpdatedAt は任意ですが、送信元システムが信頼できる変更日時を提供する場合は、強く推奨されます。
リクエスト本文の上限は 1 MiB です。mode のデフォルト値は apply です。
applyは、受け付けたレコードを検証して書き込みます。validateは、書き込みを行わずに同じ検証と照合を実行し、would_*の結果を返します。
コンタクトのインポートでは、リクエストで matchByEmail に true を設定できます。デフォルトは false です。外部 ID は、より安全な識別境界です。
省略したフィールドは現在の値を保持します。明示的な null は null 許容フィールドをクリアし、空の割り当て配列またはタグ配列を指定すると、その関連付けがクリアされます。プロジェクトの participants は追加型のアップサートです。空の配列を指定しても名簿は変更されません。コンタクト、タスク、商談、イベントのタグ書き込みでは、Scoutello のタグ ID を使用します。関連付けの外部 ID は、現在のインテグレーションに属するリンクを通じてのみ解決されます。一方、所有者または担当者に使用する Scoutello ユーザー ID は、現在の組織で承認されたメンバーを識別する必要があります。
商談の作成にはアカウントまたはコンタクトが必要で、失注した商談には失注理由が必要です。金額は整数のセント単位で指定します。プロジェクトとイベントの名前および説明は、組織で設定された言語で読み書きされます。イベントの書き込みでは、明示的な日付と、除外日を指定した日次、週次、月次の繰り返しに対応しています。公開済みの公開範囲レベルには、引き続き Scoutello の法務準備状況ゲートが適用されます。API では、イベントのチケット販売、参加者、メディア、テンプレート、ニュースレター、コラボレーション、その他の高度なイベント管理機能は公開されていません。
タグを検索
tagIds を指定する前に、タグエンドポイントを使用してください。
GET /tags?entity=events&type=category
entity は必須で、contacts、tasks、opportunities、または events を受け付けます。これは対応する保存済みタグの関連性にマッピングされます。type は任意で、category または attribute を受け付けます。選択可能なカテゴリは組織所有またはグローバルのいずれかで、選択可能な属性は Scoutello が管理する厳選済みのグローバル属性セットから取得されます。結果には scoutelloId、組織の言語にローカライズされた名前、type、および relevancy が含まれます。組織をまたぐタグ ID、誤った関連性のタグ ID、選択不可能なタグ ID を指定すると、該当するバッチ項目は拒否されます。
送信メール履歴を読む
メール履歴は読み取り専用です。
GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}
sent または failed のステータスにある、組織が所有するメールのみが返されます。レスポンスには、保存済みの一般的なヘッダーと本文、BCC、ステータスとタイムスタンプ、プロジェクト/イベント/ニュースレターへの参照、添付ファイルのIDと種類、受信者全体の配信・開封・クリック・バウンス・苦情・拒否の統計が含まれます。下書き、キュー内またはスケジュール済みのメール、受信者ごとの行、レンダリング済みスナップショット、プロバイダーから返された生のエラー、添付ファイルのダウンロードURLは一切公開されません。後から受信者への配信状況が更新されると、メールの実効同期タイムスタンプが更新され、再び差分読み取りの対象になります。メールを書き込むためのルートはありません。
適用結果は、created、updated、linked、unchanged、stale_ignored、または rejected になる場合があります。検証には would_create、would_update、would_link、would_leave_unchanged、would_ignore_stale、または rejected を使用します。バッチリクエストが有効であれば、個々のレコードが拒否された場合でもHTTP 200が返されるため、必ずすべての項目とレスポンスの概要を確認してください。失敗の調査を Scoutello サポートに依頼する際は、レスポンスの requestId を保持してください。
タイムスタンプと競合
externalUpdatedAt が存在する場合、Scoutello はそれを使用して古い変更を拒否し、バッチの他の処理は失敗させません。stale_ignored の結果は、その古いペイロードに対して確定した結果です。新しいバージョンを送信するかどうかを判断する前に、現在のレコードを取得してください。
タイムスタンプはUTCのISO 8601値として扱ってください。元の精度を保持し、同期ジョブが実行された時刻をソースレコードの変更時刻の代わりに使用しないでください。
冪等性
冪等性の境界は、連携と externalId です。Scoutello は正規化されたペイロードハッシュと任意の externalUpdatedAt 値を比較するため、同じレコードを再試行しても重複は作成されず、unchanged が返される場合があります。
externalUpdatedAt を使用する場合、同じタイムスタンプとペイロードは unchanged、より古いタイムスタンプは stale_ignored、同じタイムスタンプで異なるペイロードの場合はバージョン競合になります。タイムスタンプを一度も受け付けていないリンクでは、同じタイムスタンプなしのペイロードは引き続き unchanged となり、変更されたペイロードは到着順に適用されます。リンクがタイムスタンプを受け付けた後は、externalUpdatedAt を省略した変更済みペイロードはバージョン競合として拒否されるため、バージョン管理されていないデータがバージョン管理済みの状態を上書きすることはありません。そのため、ソースの変更タイムスタンプを強く推奨します。
監査証跡
受け付けられた API による作成、更新、リンクのみの同期アクションは、Scoutello の変更履歴に、ソースを Public API として表示し、担当するインテグレーションに関連付けられます。運用実行サマリーには、トラブルシューティング用にリクエスト ID と集計結果数が保持されます。レコードのペイロードや API シークレットは保持されません。
エラーと再試行
リクエストレベルのエラーには、次のエンベロープを使用します。
{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}
HTTP 429 と一時的な 5xx レスポンスは、指数バックオフとジッターを使用して再試行します。Retry-After が存在する場合は、その値に従います。ネットワーク障害は、Scoutello がリクエストを受け付けた後に発生している可能性があります。同じバッチを再送しても安全です。各レコードは、外部 ID と正規ペイロードによって冪等になります。リクエストを変更せずに、認証、認可、検証、バージョン競合、または個別の rejected の結果を自動的に再試行しないでください。
推奨される双方向同期ループ
- セットアップ時に
/whoamiを呼び出し、想定される組織とスコープを確認します。 - 前回完了したハイウォーターマーク以降に変更されたすべてのページを読み取り、それらの変更を外部システムに冪等に適用します。
- 安定した外部 ID とソース側の変更日時を使用して、外部の変更を
/batch-upsertに送信します。 - すべてのページと項目の結果を処理してから、チェックポイントを保存します。
- ソースシステムの所有権ルールに従って競合を解決します。空のレコードを送信して削除を再現しないでください。
Scoutello は、この初期バージョンでは公開削除ルートを意図的に提供していません。文書化されたライフサイクル操作が導入されるまでは、削除またはアーカイブのポリシーを API の外部で処理してください。
人によるレビュー用のソーシャル投稿
ソーシャル API は、指定されたレビュー担当者向けに投稿を準備します。投稿を承認または公開することはできません。REST と MCP は、同じスコープとサービスを使用します。
| スコープ | /api/v1 配下のエンドポイント |
|---|---|
social-channels.read | GET /social-channels |
social-posts.read | GET /social-posts、GET /social-posts/{scoutelloId} |
social-post-drafts.read | GET /social-post-drafts、GET /social-post-drafts/{scoutelloId}、GET /social-post-drafts/external/{externalId} |
social-post-drafts.write | POST /social-post-drafts/batch-upsert、POST /social-media/uploads、POST /social-media/uploads/{assetId}/finalize |
新しいスコープは明示的に付与する必要があります。既存の認証情報に追加のアクセス権が付与されることはありません。members.read を使用してメンバーユーザー ID を確認し、投稿権限(newsletter.edit)を持つレビュー担当者を選択します。下書きには CRM の連絡先やプロジェクトは必要ありません。
{
"mode": "apply",
"records": [{
"externalId": "campaign:autumn:launch",
"expectedVersion": 0,
"approverScoutelloUserId": "REVIEWER_USER_ID",
"content": {
"title": "Autumn launch",
"publishMode": "schedule",
"scheduledAt": "2026-10-01T09:00:00+02:00",
"variants": [{
"channelId": "CHANNEL_SCOUTELLO_ID",
"content": "Explore the autumn collection.",
"settings": {},
"mediaIds": ["FINALIZED_ASSET_ID"]
}]
}
}]
}
承認後の公開には publishMode: "now" と scheduledAt: null を使用します。各
チャネルバリアントには、完全なテキスト、設定、順序付きメディア ID が含まれます。
チャネル検出では、対応形式、上限、設定が返されます。現在対応している
チャネルは、LinkedIn のプロフィール/ページ、Facebook、Instagram、Threads です。
Instagram ではメディアが必須です。1 つのバリアントには、画像または動画を最大 10 個まで指定できます。
バッチでは、既存の 1 MiB のリクエスト上限内で、一意の外部 ID を最大 100 個まで指定できます。mode: "validate" は、下書きを保存せず、
アセットをアップロードせず、通知を作成せず、処理をキューに追加せずに、参照とバージョンを確認します。適用結果には、
ID、レビューリンク、バージョン、レコードごとの結果が含まれます。一部の失敗によって、
正常に処理された他の項目がロールバックされることはありません。通知に失敗した場合は、保存済みの
レビュー URL を含む警告が返されます。
保留中の下書きを修正する前に、現在の draftVersion を取得します。同一内容の
再試行は冪等であり、その後に行われた人手による編集が保持されます。レビュアーは既存の
提案上で変更できません。承認または却下の後に別の提案を作成する場合は、新しい外部 ID を使用します。
下書きの読み取りは呼び出し元のインテグレーションに限定されます。投稿履歴には、ダッシュボード、
スクリプト、従来の Scoutello 投稿を含む、組織内で永続化された Scoutello 作成キャンペーンがすべて含まれます。
外部チャネルの履歴はインポートされません。
リストでは、標準の limit、cursor、updatedSince パラメーターを使用します。投稿と
下書きでは、channelId、status、after、before、search も使用できます。後続のカーソルページでも
すべてのフィルターを保持してください。日付フィルターは公開時刻に適用されます
(即時公開の保留中下書きでは作成時刻)。下書きの status フィルターは承認
ステータスを対象とし、投稿の status はキャンペーンまたはチャネル配信ステータスに
一致します。読み取り結果には、最後に確認された配信状態、チャネルごとの失敗、公開リンク、
照合のタイムスタンプが表示されます。下書きの増分読み取りには、キャンペーンの配信状況の変更も反映されます。
メディアをアップロードする
POST /social-media/uploadsを、clientUploadId、filename、contentType、size(バイト単位)および元のバイト列の小文字の16進数sha256とともに呼び出します。対応形式はPNG、JPEG、WebP、MP4、WebM、QuickTime、M4Vです。アップロード上限は500 MiBです。- 返された
upload.urlに対して、HTTPPUTで元のバイト列を、そのヘッダーを使用して送信します。アップロードURLの有効期限は15分です。同じファイルの再試行にはclientUploadIdを再利用します。期限切れのセッションや別のファイルには新しいIDが必要です。 {}のJSON本文でPOST /social-media/uploads/{assetId}/finalizeを呼び出します。確定処理ではサイズ、種類、シグネチャ、チェックサムを検証し、非公開コピーを固定して、mediaIds用のアセットIDを返します。確定処理は繰り返し実行しても安全です。
アップロードの所有権は組織とインテグレーションに紐付けられます。下書きでは、その組織の確定済みアセットを参照できます。プレビューURLは一時的なものです。更新するには、下書きを再取得します。確定済みオブジェクトに対してアップロードURLが発行されることはありません。
人によるレビューと配信
レビュアーにはダッシュボード通知が届き、PostingsまたはレビューURLから投稿を開けます。編集すると、別の不変バージョンが作成されます。承認では、表示されているバージョンとコンテンツハッシュが使用され、メンバーシップ、チャネル、アセットが再確認されたうえで、永続的なキャンペーンが1件アトミックに作成されます。提案された時刻を過ぎている場合、レビュアーは新しい時刻を明示的に保存するか、承認時の公開を選択する必要があります。
キューの再試行では、キャンペーンとそのプラットフォーム側の受付情報が再利用されます。承認済みのキャンペーンは、その場で編集できません。ダッシュボードからキャンセルしても、承認履歴とメディアは保持されます。キャンセルによって実行中の配信が中断されることはありません。承認と実際のプラットフォーム配信を区別するには、下書きまたはキャンペーンをポーリングします。