ReactiveCRM 統合ガイド

ReactiveCRMとの独自統合を構築したい企業（テナント）向けの技術ドキュメント：リードとクライアントの取り込み、取引の作成、マーケティングイベントの送信、データのエクスポート。

このドキュメントは外部統合で最も一般的に使用されるAPIのみを対象としています。内部参照データおよび管理者サービスエンドポイントは意図的に範囲外としています。

1. 統合の概要

典型的な統合フローは次のようになります：

テキスト

お客様のシステム（バックエンド / サーバーサイドプロキシ）
    |
    | 1. POST /api/auth/login  （アクセス + リフレッシュトークンを取得）
    v
ReactiveCRM
    | 2. 参照： GET /api/users/paged, GET /api/statuses, GET /api/stages, GET /api/lead-sources
    |    （ownerId、authorId、statusIdなどのUUIDを取得）
    v
    | 3. コア操作：
    |      POST /api/leads/create              — リードを作成
    |      POST /api/clients/create            — クライアントを作成
    |      POST /api/contacts/create           — 連絡先を作成
    |      POST /api/deals/create              — 取引を作成
    |      POST /api/dashboard/marketing/events — マーケティングイベントを送信
    |      POST /api/leads/import/batch         — リードを一括インポート
    v
    | 4. 読み取り / エクスポート：
    |      GET /api/leads/paged                 — フィルター付きページネーション読み取り
    |      GET /api/export/leads                — 全リードのNDJSONエクスポート

重要なセキュリティルール：エンドユーザーのブラウザからCRM APIを直接呼び出さないでください。CRMトークンと内部識別子はバックエンド（またはサーバーレス関数）に保持してください。

2. 認証

2.1. トークンの取得

認証エンドポイントはトークンを必要としません：

メソッド	URL	説明
`POST`	`/api/auth/login`	ユーザー名 + パスワードでログイン、アクセス + リフレッシュトークンを返却
`POST`	`/api/auth/refresh`	リフレッシュトークンを新しいトークンペアと交換
`POST`	`/api/auth/logout`	リフレッシュトークンを無効化

bash

curl -X POST "$CRM_BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "integration", "password": "secret123"}'

json

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "a8f3k2m9Qx7Tt1Vv...",
  "tokenType": "Bearer",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "firstName": "インテグレーション",
    "lastName": "ボット",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001"
  },
  "tenant": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Zunga Corp"
  }
}

2.2. トークン処理ルール

アクセストークン（token） — 1時間有効なJWT。すべてのリクエストに含めて送信：Authorization: Bearer <token>。
リフレッシュトークン（refreshToken） — 7日間有効なランダム文字列。新しいトークンペアの取得に使用します。
/api/auth/refreshのたびに、サーバーはリフレッシュトークンをローテーションします：古いトークンは削除され、新しいトークンが発行されます。両方の新しい値を保存してください。
期限切れのアクセストークンを含むリクエストは401を返します。その場合はリフレッシュして元のリクエストを再試行してください — 再度ログインしないでください。

2.3. 基本設定

テキスト

CRM_BASE_URL=https://crm.example.com

以下のすべての例では次のヘッダーを前提とします：

http

Authorization: Bearer <CRM_ACCESS_TOKEN>
Content-Type: application/json

3. ページネーションAPIの規約

GET /api/*/paged形式のすべてのリストエンドポイントは同じ規約を共有します：

パラメータ	タイプ	デフォルト	説明
`page`	整数	`0`	ページ番号、0始まり
`size`	整数	エンドポイント毎	ページサイズ
`sort`	文字列	`createdAt,desc`	`フィールド,方向`形式のソート。方向：`asc`または`desc`

ページネーション応答の形状

json

{
  "content": [ { "..." } ],
  "page": 0,
  "size": 20,
  "totalElements": 137,
  "totalPages": 7
}

日付フィルタリング

範囲にはフィールドFrom / フィールドToパラメータを使用（ISO 8601）：

テキスト

createdAtFrom=2026-01-01T00:00:00Z
createdAtTo=2026-01-31T23:59:59Z

ソート

常に?sort=フィールド,方向：

テキスト

?sort=createdAt,desc
?sort=name,asc

一部のフィルターフィールドには専用の範囲パラメータがあります（例：dealAmountFrom/dealAmountTo）。

フィルタリングのセマンティクス

すべてのフィルタリングとソートはサーバーサイドで実行されます（すべてをダウンロードしてクライアントサイドでフィルタリングする必要はありません）。
複数のフィルターはANDで組み合わされます。
テキスト（部分文字列）フィルターは大文字小文字を区別しない検索を使用します（ILIKE）。
汎用のsearchフィルターは複数のフィールドをORで横断検索します。

4. 参照（UUIDの取得）

エンティティを作成する前に、関連する参照データのUUIDを取得してください。主なものは：

4.1. ユーザー（`GET /api/users/paged`）

ownerId、authorId、developingManagerIdsに使用されます。

bash

curl "$CRM_BASE_URL/api/users/paged?page=0&size=50&sort=createdAt,asc" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

応答例（contentの抜粋）：

json

[
  {
    "id": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "firstName": "Roman",
    "lastName": "Posledovskiy",
    "username": "roman",
    "email": "roman@example.com",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001"
  }
]

4.2. ステータス（`GET /api/statuses`）

リード、取引、取引当事者クライアントのstatusIdに使用されます。配列を返します：

bash

curl "$CRM_BASE_URL/api/statuses" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

json

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "New",
    "entityType": "LEAD"
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "name": "In progress",
    "entityType": "STAGE"
  }
]

4.3. ステージ（`GET /api/stages`）

取引のstageIdに使用されます：

bash

curl "$CRM_BASE_URL/api/stages" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

4.4. リードソース（`GET /api/lead-sources`）

リードソースのツリーを返します。リードのleadSourceIdに使用されます：

bash

curl "$CRM_BASE_URL/api/lead-sources" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

json

[
  {
    "id": "cccc0001-0000-0000-0000-000000000001",
    "name": "Website",
    "children": [
      {
        "id": "cccc0001-0000-0000-0000-000000000002",
        "name": "Feedback form",
        "children": []
      }
    ]
  }
]

5. リード

5.1. リードの作成（`POST /api/leads/create`）

bash

curl -X POST "$CRM_BASE_URL/api/leads/create" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "ウェブサイトからの問い合わせ：相談",
    "ownerId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "authorId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "leadSourceId": "cccc0001-0000-0000-0000-000000000002",
    "statusId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "quality": "WARM"
  }'

リクエストフィールド：

フィールド	タイプ	必須	説明
`message`	文字列	いいえ	メッセージ / 問い合わせテキスト
`ownerId`	uuid	はい	責任者ユーザー
`authorId`	uuid	はい	リードを作成したユーザー
`clientId`	uuid	いいえ	関連クライアント
`contactId`	uuid	いいえ	関連連絡先
`leadSourceId`	uuid	いいえ	リードソースツリーノード
`statusId`	uuid	いいえ	ステータス
`quality`	enum	いいえ	`HOT`、`WARM`、`COOL`、`COLD`

201 Created応答例：

json

{
  "id": "22222222-2222-2222-2222-222222222222",
  "message": "ウェブサイトからの問い合わせ：相談",
  "status": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "New"
  },
  "quality": "WARM",
  "dealId": null,
  "createdAt": "2026-09-05T20:00:00Z",
  "updatedAt": "2026-09-05T20:00:00Z",
  "version": 0,
  "author": {
    "id": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "firstName": "Roman",
    "lastName": "Posledovskiy"
  },
  "owner": {
    "id": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "firstName": "Roman",
    "lastName": "Posledovskiy"
  }
}

返されたidを保管してください — マーケティングイベントのleadIdに必要です（セクション8参照）。

5.2. ページネーション読み取り（`GET /api/leads/paged`）

bash

curl "$CRM_BASE_URL/api/leads/paged?page=0&size=20&createdAtFrom=2026-09-01T00:00:00Z&sort=createdAt,desc" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

主なフィルター：

パラメータ	タイプ	モード	説明
`statusId`	uuid	完全一致	ステータスでフィルター
`leadSourceId`	uuid	完全一致	リードソースでフィルター
`quality`	enum	完全一致	`HOT`、`WARM`、`COOL`、`COLD`
`message`	文字列	ILIKE	メッセージ内の部分文字列
`search`	文字列	ILIKE (OR)	メッセージ、連絡先、メール、電話を横断検索
`contactEmail`	文字列	ILIKE	連絡先メールで検索
`contactPhone`	文字列	ILIKE	連絡先電話で検索
`company`	文字列	ILIKE	会社名で検索
`clientId`	uuid	完全一致	クライアントIDで検索
`createdAtFrom` / `createdAtTo`	日時	範囲	作成日で検索
`updatedAtFrom` / `updatedAtTo`	日時	範囲	更新日で検索
`createdBy`	uuid	完全一致	リード作成者で検索

関連取引用のフィルターもあります：dealStatusId、dealStageId、dealAmountFrom/dealAmountTo、dealProbabilityFrom/dealProbabilityTo。

ソート：createdAt、updatedAt、message、quality、ステータス/ソースなど（フィールド,方向形式）。

5.3. 単一リードの取得（`GET /api/leads/{id}`）

bash

curl "$CRM_BASE_URL/api/leads/$LEAD_ID" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

5.4. リードの一括インポート（`POST /api/leads/import/batch`）

多数のリードを一括取り込みするには、バッチエンドポイントを使用します。リードの配列を受け入れ、インポート履歴レコードを作成し、インポート全体のロールバックを可能にします。

bash

curl -X POST "$CRM_BASE_URL/api/leads/import/batch" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "leads-2026-09-05.csv",
    "leads": [
      {
        "message": "問い合わせ #1",
        "ownerId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
        "authorId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
        "quality": "WARM"
      },
      {
        "message": "問い合わせ #2",
        "ownerId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
        "authorId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
        "quality": "COOL"
      }
    ]
  }'

応答例：

json

{
  "importId": "44444444-4444-4444-4444-444444444444",
  "imported": 2,
  "total": 2,
  "skipped": []
}

imported — 作成された数。
skipped — index（0始まり）とreasonを含むスキップされた行の配列。

履歴とロールバック：

bash

# インポート履歴
curl "$CRM_BASE_URL/api/leads/import/history" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

# インポートのロールバック
curl -X POST "$CRM_BASE_URL/api/leads/import/rollback/$IMPORT_ID" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

5.5. クイックウェブサイトリード（`POST /api/site/leads`）

ウェブサイトフォーム用に、連絡先、その主電話番号とメール、リード、連絡先-リードリンク、マーケティングイベントを1つのリクエストで原子的に作成する単一の統合エンドポイントがあります — externalIdによる冪等性付き。

専用ガイドを参照：site-lead-multi-contract.md。

6. クライアントと連絡先

6.1. クライアントの作成（`POST /api/clients/create`）

bash

curl -X POST "$CRM_BASE_URL/api/clients/create" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "COMPANY",
    "name": "Romashka LLC",
    "taxId": "7700000001",
    "regNumber": "1234567890",
    "country": "RU",
    "phone": "+7-495-000-00-01",
    "email": "info@romashka.ru",
    "website": "https://romashka.ru",
    "ownerId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "authorId": "7a786a66-3617-48c1-921d-97f4aaefcd35"
  }'

主なフィールド：

フィールド	タイプ	対象	説明
`type`	enum	すべて	`INDIVIDUAL`または`COMPANY`（必須）
`name`	文字列	すべて	表示名（必須）
`firstName` / `lastName`	文字列	INDIVIDUAL	名/姓
`taxId`	文字列	COMPANY	税務ID（INN）
`regNumber`	文字列	COMPANY	登録番号
`legalAddress`	文字列	COMPANY	法的住所
`phone` / `email` / `website`	文字列	すべて	連絡先
`country`	文字列	すべて	ISO国コード
`ownerId`	uuid	すべて	責任者ユーザー
`authorId`	uuid	すべて	作成者
`developingManagerIds`	uuid[]	すべて	育成マネージャー

6.2. クライアントのページネーション読み取り（`GET /api/clients/paged`）

bash

curl "$CRM_BASE_URL/api/clients/paged?page=0&size=20&type=COMPANY&search=Romashka&sort=name,asc" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

主なフィルター：name、type（INDIVIDUAL/COMPANY）、country、taxId、email、phone、lastName（個人）、search（名前/税務ID/電話で）、createdAtFrom/createdAtTo、createdBy、developingManagerId。

6.3. 重複チェック（`GET /api/clients/duplicates`）

クライアントを作成する前に、類似のものが既に存在するか確認します：

bash

# 税務IDと名前で検索
curl "$CRM_BASE_URL/api/clients/duplicates?type=COMPANY&taxId=7700000001&name=Romashka" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

6.4. 連絡先の作成（`POST /api/contacts/create`）

bash

curl -X POST "$CRM_BASE_URL/api/contacts/create" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ivan",
    "lastName": "Petrov",
    "dateOfBirth": "1990-05-15",
    "gender": "MALE",
    "countryCode": "RU",
    "ownerId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "authorId": "7a786a66-3617-48c1-921d-97f4aaefcd35"
  }'

フィールド：firstName（必須）、lastName、patronymicName、dateOfBirth（date）、gender（MALE/FEMALE）、countryCode、ownerId、authorId。

6.5. 連絡先のページネーション読み取り（`GET /api/contacts/paged`）

bash

curl "$CRM_BASE_URL/api/contacts/paged?page=0&size=20&search=Petrov&sort=createdAt,desc" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

7. 取引

7.1. 取引の作成（`POST /api/deals/create`）

bash

curl -X POST "$CRM_BASE_URL/api/deals/create" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "サーバーハードウェア納品",
    "clientId": "9f128931-69fd-493a-9a08-be5be0e6603d",
    "statusId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "stageId": "dddd0001-0000-0000-0000-000000000001",
    "probability": 60,
    "amount": 150000.00,
    "ownerId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "authorId": "7a786a66-3617-48c1-921d-97f4aaefcd35"
  }'

主なフィールド：

フィールド	タイプ	必須	説明
`name`	文字列	はい	取引名
`clientId`	uuid	はい	クライアントID
`statusId`	uuid	いいえ	ステータス（ステージステータス）
`stageId`	uuid	いいえ	販売ステージ
`probability`	整数	いいえ	確率 0-100
`amount`	数値	いいえ	金額
`plannedAmount`	数値	いいえ	計画金額
`discountPercent`	整数	いいえ	割引 0-100
`startDate` / `expectedCloseDate`	日時	いいえ	日付
`ownerId`	uuid	いいえ	所有者
`leadId`	uuid	いいえ	関連リード
`contactId`	uuid	いいえ	関連連絡先
`productIds`	uuid[]	いいえ	製品（簡易形式）
`dealProducts`	配列	いいえ	取引明細（完全形式）
`dealParties`	配列	いいえ	取引当事者

7.2. 取引のページネーション読み取り（`GET /api/deals/paged`）

bash

curl "$CRM_BASE_URL/api/deals/paged?page=0&size=20&stageKind=OPEN&sort=createdAt,desc" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

主なフィルター：name（ILIKE）、clientId、clientName、statusId、stageId、stageKind（OPEN/WON/LOST）、ownerId、search、startDateFrom/startDateTo、expectedCloseDateFrom/expectedCloseDateTo、actualCloseDateFrom/actualCloseDateTo、createdAtFrom/createdAtTo。

8. マーケティングイベント（アトリビューション）

UTMタグ、広告識別子、トラフィックソースを送信するには次を使用します：

`POST /api/dashboard/marketing/events`

bash

curl -X POST "$CRM_BASE_URL/api/dashboard/marketing/events" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "lead_submitted",
    "occurredAt": "2026-09-05T20:00:00Z",
    "visitorId": "visitor-8b7f",
    "sessionId": "session-31ac",
    "leadId": "22222222-2222-2222-2222-222222222222",
    "externalId": "site-form-submit-20260905-000123",
    "source": "website",
    "channel": "paid",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "summer-consulting",
    "utmContent": "banner-a",
    "utmTerm": "crm consultation",
    "gclid": "EAIaIQobChMI-example",
    "landingUrl": "https://www.example.com/consultation",
    "referrer": "https://www.google.com/",
    "metadata": {
      "formName": "consultation",
      "pageType": "landing"
    }
  }'

応答例：

json

{
  "accepted": true,
  "duplicate": false,
  "eventId": "33333333-3333-3333-3333-333333333333"
}

ルール：

安定したexternalId（UUIDまたは一意のrequestId）を構築します。同じsource/テナントに対して同じexternalIdで再送信するとduplicate: trueが返ります — これはエラーではありません。
再試行時に新しいexternalIdを生成しないでください。
metadataに個人を特定できる情報（メール、電話、名前、メッセージ本文）を入れないでください。フォーム名やページタイプなどの技術的属性のみを許可します。

詳細はsite-leads-integration-guide.mdを参照してください。

9. データエクスポート（NDJSON）

エクスポートエンドポイントは、テナントのすべてのレコードをNDJSON形式（1行に1つのJSONオブジェクト、\n区切り）で返します。

エンドポイント	説明
`GET /api/export/leads`	全テナントリード
`GET /api/export/clients`	全テナントクライアント
`GET /api/export/contacts`	全テナント連絡先

bash

curl "$CRM_BASE_URL/api/export/leads" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

応答例（ラインストリーム）：

テキスト

{"id":"550e8400-e29b-41d4-a716-446655440001","message":"ウェブサイトからの問い合わせ","quality":"WARM","statusName":"New","createdAt":"2026-08-20T10:00:00+03:00","ownerName":"Ivan Ivanov","clientName":"Romashka LLC","contactFirstName":"Petr","contactLastName":"Petrov","leadSourceName":"Paid search"}
{"id":"550e8400-e29b-41d4-a716-446655440002","message":"電話","quality":"COOL","statusName":"In progress","createdAt":"2026-08-19T09:00:00+03:00","ownerName":"Maria Smirnova","clientName":null}

重要：NDJSONは有効なJSON配列ではありません。ReadableStreamを介して応答を1行ずつ読み取ってください（応答全体に対してJSON.parse()を呼び出さないでください）。

10. エンドツーエンド統合の例

次のシナリオは、ウェブサイトリードを作成し、連絡先とクライアントをリンクし、取引を作成し、マーケティングイベントを送信します。

bash

CRM_BASE_URL=https://crm.example.com
CRM_TOKEN="<access-token>"

# 1. ログイン
curl -s -X POST "$CRM_BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "integration", "password": "secret123"}' | tee /tmp/login.json

CRM_TOKEN=$(jq -r '.token' /tmp/login.json)

OWNER_ID=$(curl -s "$CRM_BASE_URL/api/users/paged?page=0&size=50" \
  -H "Authorization: Bearer $CRM_TOKEN" | jq -r '.content[0].id')

# 2. クライアントを作成
curl -s -X POST "$CRM_BASE_URL/api/clients/create" \
  -H "Authorization: Bearer $CRM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"type\": \"COMPANY\",
    \"name\": \"Romashka LLC\",
    \"taxId\": \"7700000001\",
    \"country\": \"RU\",
    \"ownerId\": \"$OWNER_ID\",
    \"authorId\": \"$OWNER_ID\"
  }" | tee /tmp/client.json

CLIENT_ID=$(jq -r '.id' /tmp/client.json)

# 3. 連絡先を作成
curl -s -X POST "$CRM_BASE_URL/api/contacts/create" \
  -H "Authorization: Bearer $CRM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"firstName\": \"Ivan\",
    \"lastName\": \"Petrov\",
    \"countryCode\": \"RU\",
    \"ownerId\": \"$OWNER_ID\",
    \"authorId\": \"$OWNER_ID\"
  }" | tee /tmp/contact.json

CONTACT_ID=$(jq -r '.id' /tmp/contact.json)

# 4. リードを作成
curl -s -X POST "$CRM_BASE_URL/api/leads/create" \
  -H "Authorization: Bearer $CRM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"ウェブサイトからの問い合わせ\",
    \"clientId\": \"$CLIENT_ID\",
    \"contactId\": \"$CONTACT_ID\",
    \"ownerId\": \"$OWNER_ID\",
    \"authorId\": \"$OWNER_ID\",
    \"quality\": \"WARM\"
  }" | tee /tmp/lead.json

LEAD_ID=$(jq -r '.id' /tmp/lead.json)

# 5. リードにリンクした取引を作成
curl -s -X POST "$CRM_BASE_URL/api/deals/create" \
  -H "Authorization: Bearer $CRM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Ivan Petrov 向け相談\",
    \"clientId\": \"$CLIENT_ID\",
    \"leadId\": \"$LEAD_ID\",
    \"contactId\": \"$CONTACT_ID\",
    \"amount\": 50000.00,
    \"ownerId\": \"$OWNER_ID\",
    \"authorId\": \"$OWNER_ID\"
  }"

# 6. マーケティングイベントを送信
curl -s -X POST "$CRM_BASE_URL/api/dashboard/marketing/events" \
  -H "Authorization: Bearer $CRM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"eventType\": \"lead_submitted\",
    \"occurredAt\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",
    \"leadId\": \"$LEAD_ID\",
    \"externalId\": \"request-$(uuidgen)\",
    \"source\": \"website\",
    \"channel\": \"direct\",
    \"landingUrl\": \"https://www.example.com/form\",
    \"metadata\": {\"formName\": \"consultation\"}
  }"

11. 冪等性とエラー処理

安定した識別子：各送信に対して独自のexternalId（UUIDまたはrequestId）を生成します。同じexternalIdを再送信しても重複を作成してはいけません（マーケティングイベントの場合、これはサーバーで処理されます — duplicate: true）。
同じ識別子で再試行：ネットワークエラーの場合、同じexternalIdで再試行してください。新しいものを生成しないでください。
盲目的に重複させない：作成リクエストがタイムアウトした場合、新しいものを作成する代わりに、最初に結果を確認してください（自身のrequestIdを使用するか、作成されたエンティティを見つける）。
400：無効なペイロード — 変更せずに再試行しても役に立ちません；データを修正してください。
401：アクセストークンの期限切れ — /api/auth/refreshを呼び出し、リクエストを再試行してください。
403：権限なし — ロールとテナントを確認してください。
5xx/タイムアウト：一時的なエラー — 同じexternalIdで再試行してください（リードの場合はキューを使用してください）。

12. クイックスタート

認証：POST /api/auth/loginで認証し、tokenとrefreshTokenを保存します。
追加：すべてのリクエストにAuthorization: Bearer <token>を追加します。401の場合は/api/auth/refreshで更新します。
参照の取得：参照（ユーザー/ステータス/ステージ/リードソース）を一度取得し、UUIDをキャッシュします。
エンティティの作成：論理的な順序で作成：クライアント → 連絡先 → リード → 取引。
ページネーションエンドポイントの使用：サーバーサイドのフィルタリングとソートで読み取りを行います。
エクスポート：NDJSONエンドポイントを使用し、ストリームを1行ずつ読み取ります。
一括取り込み：バッチエンドポイント（/api/leads/import/batch、/api/clients/import/batch）をロールバックサポート付きで使用します。
マーケティングアトリビューションの送信：POST /api/dashboard/marketing/eventsを安定したexternalIdで使用します。
保存しない：マーケティングイベントのmetadataにPIIを保存または渡さないでください。
詳細なAPIドキュメント：site-leads-integration-guide.mdを参照してください。

ReactiveCRM 統合ガイド

1. 統合の概要

2. 認証

2.1. トークンの取得

2.2. トークン処理ルール

2.3. 基本設定

3. ページネーションAPIの規約

ページネーション応答の形状

日付フィルタリング

ソート

フィルタリングのセマンティクス

4. 参照（UUIDの取得）

4.1. ユーザー（GET /api/users/paged）

4.2. ステータス（GET /api/statuses）

4.3. ステージ（GET /api/stages）

4.4. リードソース（GET /api/lead-sources）

5. リード

5.1. リードの作成（POST /api/leads/create）

5.2. ページネーション読み取り（GET /api/leads/paged）

5.3. 単一リードの取得（GET /api/leads/{id}）

5.4. リードの一括インポート（POST /api/leads/import/batch）

5.5. クイックウェブサイトリード（POST /api/site/leads）

6. クライアントと連絡先

6.1. クライアントの作成（POST /api/clients/create）

6.2. クライアントのページネーション読み取り（GET /api/clients/paged）

6.3. 重複チェック（GET /api/clients/duplicates）

6.4. 連絡先の作成（POST /api/contacts/create）

6.5. 連絡先のページネーション読み取り（GET /api/contacts/paged）

7. 取引

7.1. 取引の作成（POST /api/deals/create）

7.2. 取引のページネーション読み取り（GET /api/deals/paged）

8. マーケティングイベント（アトリビューション）

POST /api/dashboard/marketing/events

9. データエクスポート（NDJSON）

10. エンドツーエンド統合の例

11. 冪等性とエラー処理

12. クイックスタート

4.1. ユーザー（`GET /api/users/paged`）

4.2. ステータス（`GET /api/statuses`）

4.3. ステージ（`GET /api/stages`）

4.4. リードソース（`GET /api/lead-sources`）

5.1. リードの作成（`POST /api/leads/create`）

5.2. ページネーション読み取り（`GET /api/leads/paged`）

5.3. 単一リードの取得（`GET /api/leads/{id}`）

5.4. リードの一括インポート（`POST /api/leads/import/batch`）

5.5. クイックウェブサイトリード（`POST /api/site/leads`）

6.1. クライアントの作成（`POST /api/clients/create`）

6.2. クライアントのページネーション読み取り（`GET /api/clients/paged`）

6.3. 重複チェック（`GET /api/clients/duplicates`）

6.4. 連絡先の作成（`POST /api/contacts/create`）

6.5. 連絡先のページネーション読み取り（`GET /api/contacts/paged`）

7.1. 取引の作成（`POST /api/deals/create`）

7.2. 取引のページネーション読み取り（`GET /api/deals/paged`）

`POST /api/dashboard/marketing/events`