# TacoLink セットアップガイド
このファイルをClaude Codeに渡してください。
Claudeがあなたの環境に合わせて、セットアップから記事入稿までを案内します。
---
## このファイルを受け取ったClaude（AI）へ
あなたはWordPressユーザーのセットアップを支援します。
以下の手順に沿って、対話しながら1つずつ進めてください。
ユーザーが「何をすればいいかわからない」状態であることを前提にしてください。
---
## 1. TacoLinkとは
WordPressの物販アフィリエイトリンク管理プラグインです。
- Amazon・楽天・Yahoo!のボタンを1つの商品カードにまとめて表示する
- 商品の検索・登録をREST API経由で行える（Claudeから自動操作可能）
- クリック計測・セール自動検知・リンク切れチェック・価格自動更新を搭載
- 無料
## 2. セットアップの全体像
完了すべき設定は3つです。順番に進めてください。
1. **TacoLinkのインストールと設定**（WordPress管理画面での作業）
2. **WordPress REST APIの認証設定**（アプリケーションパスワードの発行）
3. **認証情報の保存**（Claudeがアクセスできる場所に置く）
---
## 3. TacoLinkのインストール
### 3-1. プラグインのインストール
1. https://michiblog.website/company/tacolink/ からzipをダウンロード
2. WordPress管理画面 > プラグイン > 新規追加 > プラグインのアップロード
3. zipを選択してインストール → 有効化
### 3-2. 各モールのAPIキー設定
WordPress管理画面 > TacoLink設定 で、使うモールのAPIキーを入力します。
**楽天（必須）**
- 楽天ウェブサービス（https://webservice.rakuten.co.jp/）でアプリを登録し、以下を取得：
- アプリID（Application ID）
- アクセスキー（楽天ではアプリIDと同じ値のことが多い）
- アフィリエイトID（楽天アフィリエイトで確認）
- TacoLink設定の「楽天」タブに3つとも入力
**Yahoo!（任意）**
- Yahoo!デベロッパーネットワーク（https://developer.yahoo.co.jp/）でアプリを登録し、Client IDを取得
- バリューコマースのLinkSwitchを利用する場合：バリューコマースの管理画面からLinkSwitchのスクリプトURLをコピーし、TacoLink設定の「Yahoo!」タブの「LinkSwitch スクリプトURL」欄にそのままペースト（URLから必要な値を自動抽出します）
- TacoLink設定の「Yahoo!」タブに入力
**Amazon（任意）**
- もしもアフィリエイト経由（既定）：もしもの各種IDを入力
- 本家PA-API経由：Access Key / Secret Key / Tracking IDを入力
- TacoLink設定の「Amazon」タブで切替
---
## 4. WordPress REST APIの認証設定
ClaudeがWordPressのREST APIを使うために、アプリケーションパスワードを発行します。
1. WordPress管理画面 > ユーザー > プロフィール
2. ページ下部の「アプリケーションパスワード」セクション
3. 新しいアプリケーションパスワード名に「Claude」と入力
4. 「新しいアプリケーションパスワードを追加」をクリック
5. 表示されたパスワードをコピーして控える（この画面を閉じると二度と表示されない）
控えるもの：
- **WordPressのユーザー名**（ログインに使っているもの）
- **アプリケーションパスワード**（上で発行したもの）
- **サイトURL**（例: `https://example.com`）
---
## 5. 認証情報の保存
### Claudeへの指示
ユーザーの環境に合わせて保存方法を決めてください。以下の順で確認します。
1. プロジェクト内に既存の `.env` や `CLAUDE.md` があるか確認する
2. 他のAPIキーをどう管理しているか（キーチェーン / `.env` / 環境変数 等）をユーザーに聞く
3. ユーザーの既存の方式に合わせて、以下の3つの値を保存する：
- `WP_SITE_URL`（サイトURL）
- `WP_USERNAME`（WordPressユーザー名）
- `WP_APP_PASSWORD`（アプリケーションパスワード）
**まだAPIキーの管理方式がない場合（初めてClaude Codeを使うユーザー）：**
プロジェクトルートに `.env` ファイルを作成し、`.gitignore` に `.env` を追加する方法を案内してください。最もシンプルで、他のツールとも互換性があります。
### 保存方法の例
**`.env`ファイルの場合（推奨デフォルト）：**
```
WP_SITE_URL=https://example.com
WP_USERNAME=ユーザー名
WP_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
```
`.gitignore` に `.env` を追加すること。
**macOSキーチェーンの場合：**
```bash
security add-generic-password -s "my-wp" -a "WP_SITE_URL" -w "https://example.com" -U
security add-generic-password -s "my-wp" -a "WP_USERNAME" -w "ユーザー名" -U
security add-generic-password -s "my-wp" -a "WP_APP_PASSWORD" -w "パスワード" -U
```
**環境変数の場合（`.zshrc` / `.bashrc`）：**
```bash
export WP_SITE_URL="https://example.com"
export WP_USERNAME="ユーザー名"
export WP_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx"
```
保存方法が決まったら、接続テストを行います：
```bash
curl -s -u "ユーザー名:パスワード" "https://example.com/wp-json/wp/v2/users/me"
```
ユーザー情報のJSONが返ればOKです。`rest_not_logged_in` が返った場合はユーザー名かパスワードが間違っています。
---
## 6. TacoLink REST API仕様
認証はすべてHTTP Basic認証です。`Authorization: Basic base64(ユーザー名:パスワード)` ヘッダーを付けます。
### POST `/wp-json/tacolink/v1/generate`
商品を検索して自動登録し、記事に挿入するブロックコメントを返します。
記事に商品カードを入れるときはこのエンドポイントだけ使えばOKです。
**リクエスト：**
```json
{
"keyword": "商品名やキーワード",
"malls": ["amazon", "rakuten"],
"hint": "メーカー名（任意。候補の精度が上がる）"
}
```
- `keyword`（必須）：商品の検索キーワード
- `malls`（任意）：検索対象モール。既定は `["amazon", "rakuten"]`。楽天とYahoo!はAPIで商品を検索する。Amazonは商品検索ではなくキーワードベースの検索結果リンクを生成する（Amazon側のAPI検索は未実装）
- `hint`（任意）：メーカー名など。検索候補の中でhintを含む商品を優先する
**レスポンス：**
```json
{
"item_id": 123,
"block_comment": "",
"reused": false,
"needs_review": false,
"has_image": true,
"refreshed": false,
"candidates": {}
}
```
- `block_comment`：記事のHTMLにそのまま挿入するブロックコメント
- `reused`：`true`のとき、同じキーワードの既存商品を再利用した（再度APIを叩かない）
- `needs_review`：`true`のとき、`hint`に一致する候補が見つからなかった。`candidates`にモール別の検索結果が付くので、ユーザーに正しい商品を確認してもらう
- `has_image`：商品画像が取得できたかどうか
- `refreshed`：`true`のとき、既存商品のデータが空だったため再取得した
- `candidates`：`needs_review`が`true`のときのみ付与。モール別の検索結果候補一覧
**使用例（curl）：**
```bash
curl -s -u "ユーザー名:パスワード" \
-X POST "https://example.com/wp-json/tacolink/v1/generate" \
-H "Content-Type: application/json" \
-d '{"keyword": "AirPods Pro", "malls": ["amazon", "rakuten"]}'
```
### GET `/wp-json/tacolink/v1/items`
登録済み商品の一覧を取得します。
**クエリパラメータ：**
- `s`（任意）：検索文字列
**レスポンス：**
```json
{
"items": [
{ "id": 123, "title": "AirPods Pro 第2世代", "keyword": "AirPods Pro" }
]
}
```
### その他のエンドポイント
以下のエンドポイントも存在しますが、通常の記事入稿フローでは `/generate` だけで完結します。
- `POST /wp-json/tacolink/v1/search` — モール別の商品検索（`keyword`必須、`mall`で指定。1モールずつ）。候補を表示してユーザーに選ばせたい場合に使用
- `POST /wp-json/tacolink/v1/items` — 商品の手動登録。`/search` の結果を使って個別に登録する場合に使用
- `POST /wp-json/tacolink/v1/link-check` — 登録済み商品のリンク切れチェック（`limit`/`offset`で範囲指定）
---
## 7. 記事に商品カードを挿入する方法
### 手順
1. `/generate` で商品を登録し、`block_comment` を受け取る
2. 記事のHTML本文の中に `block_comment` をそのまま挿入する
3. WordPress REST APIで記事を投稿または更新する
### ブロックコメントの挿入位置
記事HTML内の任意の場所に挿入できます。
```html
この商品がおすすめです。
価格や在庫は自動で更新されます。
```
### WordPress REST APIでの記事投稿
```bash
curl -s -u "ユーザー名:パスワード" \
-X POST "https://example.com/wp-json/wp/v2/posts" \
-H "Content-Type: application/json" \
-d '{
"title": "記事タイトル",
"content": "記事の本文HTML（ブロックコメント含む）",
"status": "draft"
}'
```
- `status`：`draft`（下書き）または `publish`（公開）
- 既存記事の更新：`POST /wp-json/wp/v2/posts/{記事ID}`
---
## 8. 記事執筆＋商品登録の統合フロー
Claudeが記事を書きながら商品カードも入れる場合の推奨フローです。
1. 記事の構成を決める（見出し・本文の流れ）
2. 記事内で紹介する商品のキーワードをリストアップする
3. 各キーワードで `/generate` を呼び、`block_comment` を取得する
4. 記事HTML内の適切な位置にブロックコメントを挿入する
5. WordPress REST APIで記事を投稿する（まず `draft` で確認を推奨）
### 複数商品の一括登録例
```
キーワード: "AirPods Pro" →
キーワード: "Anker 充電器" →
キーワード: "SONY WH-1000XM5" →
```
### needs_reviewが返ったとき
`hint`パラメータを指定した場合に、hintに一致する候補が検索結果に見つからないと`needs_review: true`が返ります。このとき`candidates`にモール別の検索結果候補が付いてくるので、ユーザーに候補を提示して正しい商品を選んでもらってください。
`hint`を指定しなかった場合は検索結果の1位が自動選択され、`needs_review`は常に`false`です。
---
## 9. 動作環境
| 項目 | 要件 |
|---|---|
| WordPress | 6.0以上 |
| PHP | 7.4以上 |
| 対応テーマ | テーマ非依存（SWELL・AFFINGER6で動作確認済み） |