はじめの設定 10 / 14

自社開発のサイトを API でつなぐ

自社で作ったサイトや、get1pct が直接つなげない CMS では、get1pct の API を使います。自社のサーバーが API で「オーナーが使うと決めた案」を受け取り、サイトに下書きとして保存して、その結果を get1pct に返します。get1pct の API が、あなたのサイトに書き込んだり公開したりすることはありません。

必須かどうか
任意(Growth・Pro)
作業をする場所
管理画面の「API」と、自社のサーバー

始める前に

  • 必要なもの: Growth か Pro のご契約と、API を呼ぶ自社のサーバーです。API はブラウザーからは呼びません。
  • キー: opct_ で始まるキーをご契約ごとに 1 つ発行します。Pro で追加したサイトも、同じキーで扱えます。
  • 持ち主の確認: 案を受け取って反映の結果を返すには、トップページの head に持ち主の確認の 1 行(<meta name="get1pct-verification" …>)が入っている必要があります。案の一覧を読むだけなら要りません。
  • Pro で追加したサイト: 持ち主の確認の 1 行は、サイトごとに違います。管理画面でサイトを切り替えてコピーし、それぞれのサイトのトップページに入れてください。
  • 同じサイトで WordPress や CMS をつないでいるとき: その場合は get1pct が直接反映するので、API での反映は受け付けません(application_conflict)。どちらか 1 つにしてください。
  • API の仕様: OpenAPI の JSON でも見られます。

この連携の基準

  • 渡すのは、オーナーご本人が「この案を使う」か、文を直して使うと決めた案だけです。キーだけでは案を承認できません。
  • 対象の項目は title・description・h1・body の 4 種類です。
  • 対象のページは、そのサイトの https の URL で、ポート・? ・# の無いものだけです。変更後の文に < > [ ] や NUL を含む案は渡しません。
  • 1 つの案には反映の ID(job)を 1 つだけ付けます。同じ案を何度受け取っても、同じ ID が返ります。この ID を自社の記録に残し、同じ案を二重に反映しないための目印にしてください。
  • 一度返した結果は上書きできません。draft_saved のあとに failed を返す、などはできません。通るのは同じ内容の再送だけです。published は前に返した draft_saved の版を指すときだけ受け付けます。
  • 案を受け取るときと結果を返すときは、毎回トップページを読み、持ち主の確認の 1 行があるかを確かめます。
  • get1pct は、API を呼んだ側が指定した URL へは接続しません。キーをどこかへ送ることもありません。サイトへの書き込みと公開は、すべて自社のサーバーで行います。

自社のサーバーでも、サイトの今の値が案の「変更前」(before)とそっくり同じときだけ書き換えてください。扱うのはあらかじめ許したページと項目の一覧にあるものだけにします。今の値が違うときはfailed の conflict を返します。

手順

手順 1持ち主の確認の 1 行をトップページに入れる

管理画面の「サイトの接続」を開きます。「持ち主の確認」の 1 行をトップページの head に入れて、公開します。この 1 行は秘密ではありません。

管理画面の「持ち主の確認」。トップページに入れる 1 行と「この 1 行をコピーする」のボタンがある
  1. 「持ち主の確認」に、入れる 1 行が出ています。
  2. 「この 1 行をコピーする」を押します。

手順 2API キーを発行する

管理画面の「API」を開きます。

管理画面の「API」。契約サイトを選ぶ欄、反映結果を記録できるキーにするチェック、キーを発行・更新と無効にするボタン、API 仕様を開くボタンがある
  1. 「契約サイト」で、ご契約のサイトを選びます。
  2. 案を受け取って結果を返す(POST・PUT を使う)なら、「自社サイトから改善案の反映結果を記録できるキーを発行する」にチェックを入れます。案を読むだけなら入れません。
  3. 「キーを発行・更新」を押すと、キーが 1 度だけ表示されます。前のキーはすぐに使えなくなります。
  4. 使わなくなったら「キーを無効にする」を押します。
  5. 「API 仕様を開く」で、OpenAPI の仕様を見られます。

表示されたキーは、すぐに自社のサーバーのシークレットの保管場所(環境変数を管理する仕組みなど)に入れてください。メールやチャット、ブラウザーで動くコード、Git には書かないでください。

手順 3サーバーから呼ぶ

すべてのリクエストに Authorization: Bearer opct_… を付けます。応答はいつも JSON で、Cache-Control: no-store が付きます。

curl -s https://get1pct.com/api/v1/projects \
  -H "Authorization: Bearer $GET1PCT_API_KEY"

{"projects":[{"id":"SITE_ID","host":"example.com","url":"https://example.com/"}]}

エンドポイント

どれも https://get1pct.com の下にあります。1 つのキーで呼べるのは 1 分に 60 回までです。超えると 429 の rate_limited を返します。回数は最初の呼び出しから 60 秒たつと数え直します。数え直すまでの秒数は、Retry-After ヘッダーで返します。

  • GET /api/v1/projects: キーで扱えるサイトの一覧(id・host・url)。Pro では追加したサイトも入ります。
  • GET /api/v1/projects/{id}/proposals: そのサイトの新しい案 50 件(日付の新しい順)。id・date・page・field・before・after・reason・status・applicationStatus。
  • POST /api/v1/projects/{id}/proposals/{proposalId}/application: 承認済みの案を反映の ID と一緒に受け取ります。本文は {"operation":"save_draft"} だけです。
  • PUT /api/v1/projects/{id}/proposals/{proposalId}/application: 反映の結果を返します。

POST と PUT の本文は Content-Type: application/json で送り、2,048 バイトまでです。POST と PUT を呼ぶには、管理画面で「自社サイトから改善案の反映結果を記録できるキーを発行する」にチェックを入れて発行したキーが要ります。

status の値は、shown(まだ決めていない)・approved(この案を使う)・edited(文を直して使う)・rejected(見送る)のどれかです。applicationStatus は、API で反映するときは claimed(受け取った)→ draft_saved → published と進むか、failed になります。反映していなければ none です。

反映の流れ

手順 1承認済みの案を探す

案の一覧から次の 2 つに当てはまる案を選びます。

  • status が approved か edited
  • applicationStatus が none か、コピーで使う案として出ている copy
curl -s https://get1pct.com/api/v1/projects/SITE_ID/proposals \
  -H "Authorization: Bearer $GET1PCT_API_KEY"

{"proposals":[{"id":"PROPOSAL_ID","date":"2026-11-17",
  "page":"https://example.com/about","field":"title",
  "before":"会社概要","after":"会社概要|創業 30 年の町工場",
  "reason":"…","status":"approved","applicationStatus":"none"}]}

手順 2反映の ID と変更を受け取る

curl -s -X POST https://get1pct.com/api/v1/projects/SITE_ID/proposals/PROPOSAL_ID/application \
  -H "Authorization: Bearer $GET1PCT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation":"save_draft"}'

{"application":{"id":"3f0c…(UUID)","claimedAt":1794900000000,"result":null,"published":null},
 "change":{"operation":"save_draft","page":"https://example.com/about","field":"title",
  "before":"会社概要","after":"会社概要|創業 30 年の町工場"}}

応答の application.result にすでに値が入っていれば、前に処理した案です。もう一度反映しないでください。

手順 3自社のサイトで下書きに保存する

change.page と change.field から、自社のサイトのどの記事のどの項目かを決めます。その項目の今の値が change.before とそっくり同じなら、change.after を下書きに保存します。反映の ID(application.id)は自社の記録に残します。

手順 4結果を返す

curl -s -X PUT https://get1pct.com/api/v1/projects/SITE_ID/proposals/PROPOSAL_ID/application \
  -H "Authorization: Bearer $GET1PCT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"3f0c…(POST で受け取った application.id)","status":"draft_saved","revision":"rev-1024"}'

# 保存しなかったとき
-d '{"id":"…","status":"failed","code":"conflict"}'
# 担当者が下書きを公開したあと
-d '{"id":"…","status":"published","draftRevision":"rev-1024","revision":"rev-1025"}'
  • draft_saved: 下書きに保存した。revision には、自社の版の ID を入れます(英数字と _ . : - で 128 文字まで。秘密の値は入れない)。
  • failed: 保存しなかった。code には、unsupported(扱えない項目)・conflict(今の値が変更前と違う)・rejected(自社の確認で断った)のどれかを入れます。
  • published: 下書きを担当者が公開した。draftRevision に前に返した版を、revision に公開した版を入れます。この報告を受けてもget1pct が何かを公開することはありません。

エラーの一覧

失敗すると、HTTP のステータスと {"error":{"code":"…"}} を返します。403 の forbidden には、理由を示す reason も付きます(例: {"error":{"code":"forbidden","reason":"daily_paused"}})。

  • invalid_request(HTTP 400): リクエストの形が違う(JSON でない、項目が足りない・多い、2,048 バイトを超える など)
  • unauthorized(HTTP 401): キーが無い・形が違う・無効にされた(作り直した古いキーも含む)
  • forbidden(HTTP 403): 契約が Growth・Pro でない/終わった(reason: plan_inactive)、反映の記録を許していないキーで POST・PUT を呼んだ(applications_disabled)、毎朝の案を止めているサイト(daily_paused)
  • ownership_required(HTTP 403): トップページの head に持ち主の確認の 1 行が見つからない
  • not_found(HTTP 404): サイト ID や案の ID が無い、ほかの方のもの
  • not_approved(HTTP 409): オーナーが「この案を使う」(または文を直して使う)を選んでいない案
  • application_conflict(HTTP 409): すでにほかの方法で反映済み・反映中、WordPress や CMS を接続しているサイト、反映の ID や報告が前と食い違う
  • unsupported_change(HTTP 422): このサイトの https のページでない、URL に ? や # がある、項目が title・description・h1・body 以外、変更後に < > [ ] がある など
  • unsupported_operation(HTTP 422): operation が save_draft 以外
  • rate_limited(HTTP 429): 1 つのキーで 1 分に 60 回を超えた(Retry-After ヘッダーの秒数だけ待つ)
  • unavailable(HTTP 503): get1pct 側の一時的な不具合(時間をおいて同じリクエストを送り直す)

うまくいかないとき

401 unauthorized が返る
ヘッダーが Authorization: Bearer opct_… の形になっているかと、キーの前後に空白や改行が入っていないかを確かめます。キーを作り直したときは、古いキーはすぐに使えなくなっています。
403 forbidden が返る
error.reason を見ます。plan_inactive なら、ご契約が Growth・Pro のままかを確かめます。applications_disabled なら、「反映結果を記録できるキー」として発行したかを確かめます。チェックを入れずに発行したキーでは、案を読むことしかできません。daily_paused なら、管理画面でそのサイトの毎朝の案を止めています。
403 ownership_required が返る
トップページ(https://あなたのドメイン/)の head に、管理画面に出ている 1 行がそのまま入っているかを確かめます。別のドメインへ転送されるトップページや、本文の中に置いた 1 行では、確認できません。Pro で追加したサイトでは、そのサイト用の 1 行を、そのサイトのトップページに入れます。
409 application_conflict が返る
次の 3 つを確かめます。同じサイトで WordPress や CMS をつないでいないか。すでに管理画面で「やった」を押した案ではないか。PUT の id が、POST で受け取った application.id と同じか。
429 rate_limited が返る
1 分に 60 回を超えています。Retry-After ヘッダーの秒数だけ待ってから送り直してください。

やめるとき

管理画面の「API」で「キーを無効にする」を押すと、そのキーはすぐに使えなくなります。自社のサーバーに保存したキーも消してください。ご契約が終わったときも、キーは使えなくなります(403 の forbidden)。キーが漏れたかもしれないときは、API キーの扱いと安全をご覧ください。

手順のとおりに進まないときは、お問い合わせから、対象のサイトの URL と、どの画面で止まったかをお知らせください。パスワードは送らないでください。