開発者向けAPI

1. 概要

REST APIで管理中のドメインのネームサーバー（NS）設定を変更できます。 当社でドメインを管理しているお客様は、追加料金なしで利用できます。ドメインの登録料・更新料以外にAPI利用料はかかりません。

ドメイン名の新規登録・更新・移管・廃止は管理画面からのみ行えます。APIでは、ドメイン情報の参照とネームサーバー設定の変更ができます。

2. 認証（APIキー）

ログイン後の管理画面にある「APIキー」ページから発行できます。 シークレットは発行直後に一度だけ表示されます。安全な場所に保管してください。

2-1. リクエスト方法

以下のいずれかのHTTPヘッダーを指定してください。

# 推奨: X-API-Keyヘッダー
curl https://simple-domain.jp/api/v1/external/domains \
  -H "X-API-Key: sd_live_aB3XyZ...REDACTED..."

# または Authorization: ApiKey
curl https://simple-domain.jp/api/v1/external/domains \
  -H "Authorization: ApiKey sd_live_aB3XyZ...REDACTED..."

2-2. キーの形式

2-3. スコープ（権限）

3. レート制限

すべてのAPIキーに同じレート制限を適用します。上限を超えた場合は、HTTP 429 Too Many RequestsとRetry-Afterヘッダーを返します。

業務上の理由で制限の緩和が必要な場合は、お問い合わせからご相談ください。個別に検討します。

4. 主要エンドポイント

APIで利用できるエンドポイントは次のとおりです。

ドメイン名の新規登録・更新・移管・廃止は管理画面からのみ行えます。

5. レスポンス例

5-1. 成功時（200 OK）

GET /v1/external/domains/example.jp

{
  "name": "example.jp",
  "registered_at": "2026-08-01T09:30:00Z",
  "expires_at": "2027-08-01T09:30:00Z",
  "nameservers": ["ns1.simple-domain.jp", "ns2.simple-domain.jp"],
  "auto_renew": true,
  "whois_privacy": true,
  "status": "active"
}

5-2. エラー時（4xx / 5xx）

PUT /v1/external/domains/example.jp/nameservers
HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "code": "INVALID_NAMESERVER",
    "message": "Nameserver does not resolve: ns1.example.com",
    "request_id": "req_01HKJX7P3F8YQ"
  }
}

request_idは、当社へのお問い合わせ時に必要です。すべての応答にX-Request-Idヘッダーとしても付与されます。

6. Webhook通知

ドメインの状態変化をHTTPS POSTで通知します（通常5分以内に配送）。通知先のエンドポイントは管理画面から登録できます。

6-1. ペイロード例

POST https://your-server.example.com/webhooks/simple-domain
Content-Type: application/json
X-SD-Event-Id: evt_01HKJX7P3F8YQ
X-SD-Event-Type: domain.expiring_soon
X-SD-Signature: t=1730000000,v1=5257a869e7ec...
X-SD-Delivery-Id: del_01HKJXAAKB2VR

{
  "id": "evt_01HKJX7P3F8YQ",
  "event": "domain.expiring_soon",
  "created_at": "2026-08-01T00:00:00Z",
  "data": {
    "domain": "example.jp",
    "expires_at": "2026-08-08T00:00:00Z",
    "days_remaining": 7
  }
}

6-2. 署名検証

X-SD-Signatureヘッダーはt=<unix timestamp>,v1=<HMAC-SHA256 hex>形式です。 ペイロードと発行時に表示されたシークレットを使って検証してください（Stripe Webhookと同じ方式です）。 タイムスタンプと現在時刻の差が5分以上ある場合は、リプレイ攻撃のおそれがあるため拒否してください。 署名はリクエスト本文（raw body）に対して検証し、冪等キーには本文のidフィールド（X-SD-Event-Idヘッダーと同じ値）を使用してください。各ヘッダーは本文の値を転記したもので、個別には署名されません。

6-3. 配信失敗時のリトライ

受信側が2xx以外を返した場合は、次のスケジュールで再送します。

• 1回目：即時
• 2回目：30秒後
• 3〜6回目：5分後・30分後・2時間後・12時間後（指数バックオフとジッターを使用）
• 7回目以降：DLQに移動し、管理画面からの手動再送のみ可能

10回連続で失敗するとエンドポイントを自動停止し、メールでお知らせします。

7. SDK・コード例

7-1. curl

# 保有ドメイン一覧
curl https://simple-domain.jp/api/v1/external/domains \
  -H "X-API-Key: $SD_API_KEY"

# ドメイン詳細 (現在の NS を確認)
curl https://simple-domain.jp/api/v1/external/domains/example.jp \
  -H "X-API-Key: $SD_API_KEY"

# ネームサーバー変更
curl -X PUT https://simple-domain.jp/api/v1/external/domains/example.jp/nameservers \
  -H "X-API-Key: $SD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nameservers": [
      "ns1.example.com",
      "ns2.example.com"
    ]
  }'

7-2. Python

import os
import requests

api_key = os.environ["SD_API_KEY"]
headers = {"X-API-Key": api_key}

# 一覧取得
r = requests.get("https://simple-domain.jp/api/v1/external/domains", headers=headers)
r.raise_for_status()
for d in r.json()["domains"]:
    print(d["name"], d["expires_at"])

7-3. Node.js

const apiKey = process.env.SD_API_KEY;

const res = await fetch("https://simple-domain.jp/api/v1/external/domains", {
  headers: { "X-API-Key": apiKey }
});
const data = await res.json();
console.log(data.domains);

8. エラーコード一覧（抜粋）

9. お問い合わせ

• 仕様に関する質問・動作不具合：X-Request-Idを添えてお問い合わせフォームからご連絡ください。
• 緊急障害・セキュリティインシデント：abuse-report@coper.tech

※ 仕様は予告なく変更する場合があります。最新の仕様は本ページでご確認ください。