> ## Documentation Index
> Fetch the complete documentation index at: https://docs.utage-system.com/llms.txt
> Use this file to discover all available pages before exploring further.
# LINE友だちをシナリオ登録
> **プレビュー機能。仕様は今後変更される可能性があります。**
LINE友だちを指定シナリオの読者として登録します。
`allow_duplicates` が `false`（デフォルト）の場合、配信解除されていない同一の友だち×シナリオの読者が既に存在すると409を返します（配信解除済みは重複とみなさず新規作成）。`allow_duplicates` を `true` にすると重複チェックをスキップします。
このエンドポイントは分間レート制限（60回/分）の対象外で、独自の時間/月間上限で制御されます。
`POST`
```
https://api.utage-system.com/v1/accounts/{account_id}/line/friends/{friend_id}/readers
```
読者作成はバーストが発生しやすいため、このエンドポイントは分間レート制限（60回/分）の対象外です。代わりに時間単位・月間単位の作成上限で制御されます。
この機能はプレビュー版です。仕様が変更される場合があります。
## OpenAPI
````yaml POST /accounts/{account_id}/line/friends/{friend_id}/readers
openapi: 3.0.3
info:
title: UTAGE API
description: |
UTAGEのパブリックAPIです。ファネル、配信アカウント、シナリオ、メディアなどのリソースをプログラムから操作できます。
## 認証
すべてのリクエストにAPIキーによるBearer認証が必要です（要素タイプエンドポイントを除く）。
```
Authorization: Bearer {api_key}
```
APIキーはUTAGE管理画面から発行できます。
## レート制限
リクエスト数には以下の制限があります。
| 分間上限 | 日間上限 |
|----------|----------|
| 60リクエスト/分 | 10,000リクエスト/日 |
レスポンスヘッダーで現在の使用状況を確認できます。
| ヘッダー | 説明 |
|----------|------|
| X-RateLimit-Limit | 分間の上限値 |
| X-RateLimit-Remaining | 分間の残りリクエスト数 |
| X-RateLimit-Reset | 制限がリセットされるUNIXタイムスタンプ |
上限を超えた場合は `429 Too Many Requests` が返されます。
## エラーレスポンス
エラー時は以下の形式で返されます。
```json
{
"error": {
"code": "error_code",
"message": "エラーメッセージ"
}
}
```
version: '1.0'
contact:
name: UTAGE サポート
servers:
- url: https://api.utage-system.com/v1
description: UTAGE API
security:
- BearerAuth: []
tags:
- name: ファネル
description: ファネルの作成・更新・一覧取得
- name: ステップ
description: ファネル内のステップの作成・更新・並び替え
- name: ページ
description: ステップ内のページの作成・更新・取得・削除
- name: 配信アカウント
description: 配信アカウントの作成・一覧取得
- name: シナリオ
description: シナリオの作成・一覧取得
- name: メディア
description: 動画・音声・通常メディアの一覧取得とアップロード
- name: 要素タイプ
description: ファネルページ・HTMLメールの要素タイプ定義、LINEメッセージタイプ・配信条件タイプの取得（認証不要）
- name: ファネル統計
description: ファネルの集計データ・登録者・登録経路の取得（プレビュー）
- name: 配信メッセージ
description: 配信メッセージの作成・更新・テスト送信・配信統計、置き換え文字の取得（プレビュー）
- name: 読者
description: 読者の作成・更新・取得、ラベル・配信履歴・開封/クリック履歴の取得（プレビュー）
- name: LINE
description: LINE友だち・カスタム送信者・1対1チャット・テンプレートの操作（プレビュー）
- name: ラベル・共通読者・登録経路
description: ラベル・共通読者・アクション・登録経路の操作（プレビュー）
paths:
/accounts/{account_id}/line/friends/{friend_id}/readers:
post:
tags:
- LINE
summary: LINE友だちをシナリオ登録
description: >
**プレビュー機能。仕様は今後変更される可能性があります。**
LINE友だちを指定シナリオの読者として登録します。
`allow_duplicates` が
`false`（デフォルト）の場合、配信解除されていない同一の友だち×シナリオの読者が既に存在すると409を返します（配信解除済みは重複とみなさず新規作成）。`allow_duplicates`
を `true` にすると重複チェックをスキップします。
このエンドポイントは分間レート制限（60回/分）の対象外で、独自の時間/月間上限で制御されます。
operationId: createLineFriendReader
parameters:
- $ref: '#/components/parameters/AccountId'
- name: friend_id
in: path
required: true
description: LINE友だちID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- scenario_id
properties:
scenario_id:
type: string
description: 登録先シナリオID
has_step_immediately:
type: boolean
default: false
description: 登録直後のステップ配信の対象にする
has_step_scheduled:
type: boolean
default: false
description: 登録以降のステップ配信の対象にする
has_reminder:
type: boolean
default: false
description: リマインダ配信の対象にする
allow_duplicates:
type: boolean
default: false
description: 重複登録を許可する
responses:
'201':
description: 登録された読者
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: >-
読者詳細（line_friend_id / line_display_name / line_picture_url
/ is_line_blocked を含む）
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: 配信解除されていない同一の友だち×シナリオの読者が既に存在します（details.reader_id に既存読者IDを含む）。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: conflict
message: すでに登録されています
'422':
$ref: '#/components/responses/ValidationError'
'429':
description: >
読者作成のリソース上限を超過しました。分間レート制限とは別枠で、時間/月間/累計の上限に応じて以下のコードを返します。
- `hourly_limit_exceeded`: 1時間の作成上限に達した
- `monthly_limit_exceeded`: 月間の作成上限に達した（`details.retry_after`
に再試行可能になる日時（`Y-m-d H:i:s` 形式の文字列）を含む）
- `total_limit_exceeded`: 累計の作成上限に達した
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: monthly_limit_exceeded
message: 月間の作成上限に達しました
details:
resource_type: reader
retry_after: '2026-06-20 00:00:00'
components:
parameters:
AccountId:
name: account_id
in: path
required: true
description: アカウントID
schema:
type: string
responses:
Unauthorized:
description: 認証エラー。APIキーが無効または未指定。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: unauthorized
message: 認証に失敗しました
NotFound:
description: 指定されたリソースが見つかりません。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: not_found
message: リソースが見つかりません
ValidationError:
description: バリデーションエラー。リクエストパラメータが不正。
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: validation_error
message: バリデーションエラーが発生しました
schemas:
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: エラーコード
message:
type: string
description: エラーメッセージ
details:
type: object
nullable: true
description: エラーの補足情報（retry_afterやフィールド別エラー等）。エラー種別により含まれる場合があります。
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: APIキーをBearerトークンとして指定
````