# 即焼きレスキュー 注文 API ドキュメント

> 即焼きレスキューの DVD・Blu-ray の制作を、他社のサービスやプログラムから注文できる API です。動画の URL と届け先を送ると、その場で注文が確定し、制作・発送まで行います。登録すれば、どなたでもお使いいただけます。

- ベース URL: `https://api.sokuyaki.com/v1/`
- このドキュメントの HTML 版: https://app.sokuyaki.com/developers/docs
- 概要: https://app.sokuyaki.com/developers
- アカウント（API キーの発行・チャージ）: https://app.sokuyaki.com/account

## はじめかた

1. [アカウントのページ](https://app.sokuyaki.com/account) で、Google アカウントか、メールアドレスとパスワードで登録します。
2. 請求先（ご注文者様の名前・住所・メールアドレス）を登録します。ご注文の受付と発送の通知のメールは、このメールアドレスに届きます。
3. テスト用の API キーを発行し、下の「注文を作る」を試します。テスト用のキーは、残高を使わず、注文も作りません。
4. 即焼きクレジットをチャージし（カード・銀行振込）、本番用の API キーで注文します。

## お支払い（即焼きクレジット）

- API のご注文の代金は、前払いの残高「即焼きクレジット」からお支払いいただきます。チャージの手数料や割増はありません。
- 残高が足りないご注文は、作られません（エラー 402）。
- 料金は、サイトからのご注文と同じです（税込・送料込）。金額は [見積のページ](https://app.sokuyaki.com/quote) で、条件を入れて確かめられます。同じ内容のディスクを 15 枚以上ご注文いただくと、その行が半額になります。
- ご注文のキャンセルや不具合で払い戻すときは、即焼きクレジットの残高にお戻しします。

## メールと領収書

どちらも、アカウントの請求先のメールアドレスに届きます。

| メール | 届くとき | 中身 |
| --- | --- | --- |
| ご注文の受付（領収書） | 注文を作ったとき | 適格請求書発行事業者の登録番号が入っていて、インボイスとしてお使いいただけます。 |
| 発送の通知 | 発送したとき | 追跡 URL が入っています。 |

- 届け先のお客様には、メールは届きません。

## 呼び出しと認証

URL は `https://api.sokuyaki.com/v1/` です。すべての呼び出しに `Authorization: Bearer {API キー}` を付けます。本文と応答は JSON（UTF-8）です。

| 呼び出し | 中身 |
| --- | --- |
| `POST /orders` | [注文を作る](#create)。成功は 201 で、注文番号・金額の明細・残高を返します。 |
| `GET /orders/{reference}` | [注文を見る](#show)。注文の状態と、発送の追跡 URL を返します。 |
| `GET /balance` | [残高を見る](#balance)。即焼きクレジットの残高を返します。 |

## 注文を作る（`POST /orders`）

### 本文の項目

| 項目 | 型 | 必須 | 中身 |
| --- | --- | --- | --- |
| `reference` | string | 必須 | 呼ぶ側の注文 ID（英数字と . _ - の 1〜64 文字）。同じ値・同じ内容をもう一度送ると、新しい注文を作らずに、同じ注文を返します（二重注文の防止）。失敗に終わった値は、使い直せます。 |
| `speed` | string | 必須 | `通常便`・`お急ぎ便`・`超お急ぎ便`・`超お急ぎ便 午前中` のどれか。超お急ぎ便 午前中は、翌日の午前中に届かない郵便番号では選べません（エラー 400）。 |
| `sender_hide` | boolean |  | `true` にすると、宛名ラベルの発送元が、アカウントの請求先（ご注文者様）になります。お急ぎ便・超お急ぎ便だけで選べます。1 回のご注文につき、追加の料金がかかります。 |
| `shipping` | object | 必須 | 届け先。宛名ラベルに入る長さで送ってください（超えると、エラー 400）。名前は 18 文字まで、住所は、都道府県・市区町村・番地・建物名・会社名を合わせて 56 文字までです（建物名と会社名は、それぞれ区切りの 1 文字を足して数えます）。 |
| `shipping.name` | string | 必須 | 名前。 |
| `shipping.company` | string |  | 会社名・部署名。宛名ラベルでは、建物名の後ろに印字します。 |
| `shipping.postcode` | string | 必須 | 郵便番号（7 桁）。 |
| `shipping.prefecture` | string | 必須 | 都道府県（「東京都」の形）。 |
| `shipping.city` | string | 必須 | 市区町村。 |
| `shipping.address_1` | string | 必須 | 番地。 |
| `shipping.address_2` | string |  | 建物名・部屋番号。 |
| `shipping.phone` | string | 必須 | 電話番号。 |
| `items` | array | 必須 | ディスクの行（1〜20 行）。1 行が、1 本の動画を収めたディスクです。 |
| `items[].disc` | string | 必須 | `DVD` か `Blu-ray`。 |
| `items[].video_url` | string | 必須 | 動画の https の URL。ご注文のときに当店が取りに行くので、認証なしで取得できる URL にしてください（期限つきの URL で構いません）。 |
| `items[].quantity` | integer |  | 同じ内容で作る枚数（省くと 1）。 |
| `items[].aspect_ratio` | string |  | `16:9`（省いたとき）か `4:3`。4:3 は DVD だけで選べます。 |
| `items[].reduction` | string |  | 映像をセーフティエリア内に縮小する。`しない`（省いたとき）・`90%`・`80%` のどれか（有料）。 |
| `items[].black_margin` | boolean |  | `true` にすると、動画の前後に 5 秒間の黒い画面を入れます（有料）。 |
| `items[].loop` | boolean |  | `true` にすると、最後まで再生したあと、自動で最初から再生し直します（有料）。 |
| `items[].gift_wrap` | object |  | ギフトラッピング（有料）。するときは `{"color": "Pink", "seal": true}` の形で、`color` は `Pink` か `Green`、`seal` は発送前に封のシールを貼るか（`false` なら、シールを同封します）。Green は在庫が無くなり次第、ミッドナイトブルーに変わります。 |

ご注文は、成功の応答（201）の時点で確定しています（サイトからのご注文と同じく、すぐに制作に入ります）。応答が返るまでの時間は、動画の大きさによって数秒〜数分です。呼び出しの待ち時間（タイムアウト）は、30 分にしてください。

リクエスト（cURL）:

```bash
curl -X POST https://api.sokuyaki.com/v1/orders \
  -H "Authorization: Bearer soku_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-20261012-001",
    "speed": "お急ぎ便",
    "sender_hide": true,
    "shipping": {
      "name": "山田 花子",
      "postcode": "100-0001",
      "prefecture": "東京都",
      "city": "千代田区",
      "address_1": "千代田1-1",
      "address_2": "サンプルビル 101",
      "phone": "03-1234-5678"
    },
    "items": [
      {
        "disc": "DVD",
        "video_url": "https://example.com/movies/profile.mp4",
        "quantity": 2,
        "reduction": "90%"
      }
    ]
  }'
```

リクエスト（Python）:

```python
import requests

res = requests.post(
    "https://api.sokuyaki.com/v1/orders",
    headers={"Authorization": "Bearer soku_live_xxxxxxxx"},
    json={
      "reference": "order-20261012-001",
      "speed": "お急ぎ便",
      "sender_hide": True,
      "shipping": {
        "name": "山田 花子",
        "postcode": "100-0001",
        "prefecture": "東京都",
        "city": "千代田区",
        "address_1": "千代田1-1",
        "address_2": "サンプルビル 101",
        "phone": "03-1234-5678"
      },
      "items": [
        {
          "disc": "DVD",
          "video_url": "https://example.com/movies/profile.mp4",
          "quantity": 2,
          "reduction": "90%"
        }
      ]
    },
    timeout=1800,
)
print(res.status_code, res.json())
```

リクエスト（PHP）:

```php
$ch = curl_init("https://api.sokuyaki.com/v1/orders");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer soku_live_xxxxxxxx",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => '{
      "reference": "order-20261012-001",
      "speed": "お急ぎ便",
      "sender_hide": true,
      "shipping": {
        "name": "山田 花子",
        "postcode": "100-0001",
        "prefecture": "東京都",
        "city": "千代田区",
        "address_1": "千代田1-1",
        "address_2": "サンプルビル 101",
        "phone": "03-1234-5678"
      },
      "items": [
        {
          "disc": "DVD",
          "video_url": "https://example.com/movies/profile.mp4",
          "quantity": 2,
          "reduction": "90%"
        }
      ]
    }',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 1800,
]);
$res = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", json_encode($res, JSON_UNESCAPED_UNICODE);
```

成功の応答（201）:

```json
{
  "reference": "order-20261012-001",
  "order": 81234,
  "amount": 7300,
  "lines": [
    { "name": "DVD 制作（お急ぎ便）", "qty": 2, "unit": 2600, "amount": 5200 },
    { "name": "セーフティエリア縮小（90%）", "qty": 2, "unit": 900, "amount": 1800, "sub": true },
    { "name": "発送元をご注文者様にする（1 回のご注文につき）", "qty": 1, "unit": 300, "amount": 300 }
  ],
  "balance": 42700
}
```

## 注文を見る（`GET /orders/{reference}`）

### 応答の項目

| 項目 | 型 | 必須 | 中身 |
| --- | --- | --- | --- |
| `status` | string |  | `processing`（制作中）・`completed`（発送済み）・`cancelled`（キャンセル）・`refunded`（払い戻し）。 |
| `refunded` | integer |  | 払い戻した金額の合計（即焼きクレジットの残高に戻っています）。 |
| `tracking_urls` | array |  | 発送の追跡 URL（発送のときに入ります）。発送の通知のメールは請求先にだけ届くので、届け先のお客様へのお知らせにお使いください。 |

リクエスト:

```bash
curl https://api.sokuyaki.com/v1/orders/order-20261012-001 \
  -H "Authorization: Bearer soku_live_xxxxxxxx"
```

応答（200）:

```json
{
  "reference": "order-20261012-001",
  "order": 81234,
  "status": "completed",
  "amount": 7300,
  "refunded": 0,
  "tracking_urls": ["https://jizen.kuronekoyamato.co.jp/jizen/servlet/crjz.b.NQ0010?id=0000-0000-0000"]
}
```

## 残高を見る（`GET /balance`）

### 応答の項目

| 項目 | 型 | 必須 | 中身 |
| --- | --- | --- | --- |
| `balance` | integer |  | 即焼きクレジットの残高（円）。 |

リクエスト:

```bash
curl https://api.sokuyaki.com/v1/balance \
  -H "Authorization: Bearer soku_live_xxxxxxxx"
```

応答（200）:

```json
{ "balance": 42700 }
```

## エラー

エラーの応答は、`error`（種類）と `message`（説明）を持ちます。

| 状態 | error | 場合と、すること |
| --- | --- | --- |
| 400 | `invalid` | 入力の誤り。`errors` に、項目（`field`）ごとの説明が入ります。請求先が未登録のときも、このエラーです。 |
| 401 | `unauthorized` | API キーが違います。 |
| 402 | `insufficient_balance` | 残高が足りません。`amount`（要る額）と `balance`（残高）が入ります。チャージしてから、同じ内容で送り直してください。 |
| 404 | `not_found` | その reference の注文がありません。 |
| 409 | `in_progress` `reference_reused` | 同じ reference の注文を処理している最中です（少し待って、同じ内容で送り直してください）。または、その reference は、別の内容の注文に使われています。 |
| 422 | `video_rejected` | 受けられない動画があります。`items` に、行の番号（`index`。0 から）と理由（`reason`）が入ります。注文は作られず、残高も減りません。 |
| 429 | `test_limit` | テスト用のキーの、1 日の回数（20 回）を超えました。 |
| 503 | `unavailable` | 注文を作れなかったか、作れたかを確かめられませんでした。同じ reference・同じ内容で送り直してください。注文ができていればその注文を返し、できていなければ作ります（二重の注文にはなりません）。 |

通信が途中で切れたとき・500 番台の応答のときも、同じ reference・同じ内容で送り直してください。reference を変えて送り直すと、注文が 2 つになることがあります。

エラーの応答（422）:

```json
{
  "error": "video_rejected",
  "message": "受けられない動画があります",
  "items": [
    { "index": 0, "reason": "duration", "message": "動画の長さ（82.50 分）が、DVD 1 枚の収録の上限の 70 分を超えています。…" }
  ]
}
```

## 動画の条件

次の動画は、ディスクを作れないので、注文の前に断ります（エラー 422）。

| reason | 場合 |
| --- | --- |
| `format` | 動画ではない（ファイル名の拡張子が、動画のものではない。パワーポイントなど）。 |
| `metadata` | 動画の情報を読めない（データが壊れている・空）。 |
| `size` | 30GB を超えている。 |
| `duration` | 長さが、ディスク 1 枚の上限（DVD は 70 分未満、Blu-ray は 100 分未満）を超えている。動画を分けるサービスはありません。 |
| `fetch` | URL から取得できない（https でない・接続できない・エラーの応答・取得に 25 分以上かかる）。 |

### おすすめの形式

- MP4（H.264）。ファイル名（URL の最後か、応答の Content-Disposition）に、.mp4 などの拡張子が要ります。
- 解像度は、DVD なら 1280x720 か 960x720、Blu-ray なら 1920x1080。これより大きくしても、仕上がりの画質は上がりません。
- 横長・SDR。縦長の動画は左右に余白ができ、HDR の動画は色味が変わることがあります。

## テスト用のキー

`soku_test_` で始まるキーで `POST /orders` を呼ぶと、入力の確認・金額の計算・動画の取得と確認までを行い、残高を引かず、注文を作りません（取得した動画は、すぐに消します）。成功の応答は 200 で、`"test": true` と、金額の明細・読み取った動画の情報（長さ・解像度）を返します。残高が無くても使えますが、1 アカウントにつき 1 日 20 回までです。

## API で注文できないもの

複数の動画を 1 枚に収めるディスク、盤面・表紙の印刷、オリジナルデータの保存、emoshot、ISUM（結婚式の楽曲）の申請代行は、API では注文できません。[サイトからご注文](https://sokuyaki.com/order/) ください。

## 利用規約

- API キーは、他人に知らせないでください。キーを使った注文は、そのアカウントの注文として扱います。漏れたときは、アカウントのページでキーを消してください。
- 著作権などの権利を持たない動画、法令や公序良俗に反する内容の動画は、ご注文いただけません。
- API やサイトに過大な負荷をかける呼び出し、当店や第三者に損害を与える使い方は、お断りします。そのときは、予告なく API キーを止めることがあります。
- 即焼きクレジットは、最後のチャージかご利用から 2 年で失効します。チャージした残高の、現金での払い戻しはできません（法令で定められた場合を除きます）。
- 制作・納期・返品などの条件は、サイトからのご注文と同じです（[特定商取引法に基づく表記](https://sokuyaki.com/about-us/)）。
- API の内容は、変えることがあります。変更は、このページでお知らせします。

ご質問は、[support@sokuyaki.com](mailto:support@sokuyaki.com) までお寄せください。