# Postback API v2 クイックスタート

Postback API v2 は、次世代の Postback インジェストエンドポイントです。レガシー Postback API と同じ `/postback/v3/event/{database}/{table}` のパス契約を持ちますが、新しい `records.in.treasuredata.com` ホストから提供され、ヘッダーベース認証のみをサポートします。

Postback API v2 は、レガシー Postback API と同じユースケースに使用できます。カスタム Webhook、JS SDK や TD Logger を実行できない環境、または外部アプリケーションによってトリガーされるシングルレコードのインポートなどが該当します。

## レガシー Postback API との違い

|  | **レガシー Postback** | **Postback v2** |
|  --- | --- | --- |
| ホスト | `in.treasuredata.com` | `<region>.records.in.treasuredata.com` |
| `X-TD-Write-Key` ヘッダー | サポート | サポート |
| `Authorization: TD1 <key>` ヘッダー | — | サポート |
| `?td_write_key=<key>` URL パラメーター | サポート | **非サポート** |
| 最大リクエストボディサイズ | — | 1,048,064 バイト |
| パス | `/postback/v3/event/{db}/{table}` | `/postback/v3/event/{db}/{table}` |


レガシーの URL パス API キー（`?td_write_key=...`）は v2 では受け付けられません。切り替え前に、このキーを使用しているクライアントを以下の2つのヘッダー形式のいずれかに移行してください。

## セットアップ

- [Write API キーの確認](/products/my-settings/getting-your-api-keys)
- [リージョンの Postback API エンドポイントの確認](/apis/endpoints/endpoints) — v2 ホストは `<region>.records.in.treasuredata.com` です。
- 書き込みアクセス権を持つ TD データベースとテーブル。ここに API キーを使用してデータを書き込みます。


## 手順

### リクエストの送信

TD Write API キーをヘッダーとして追加し、データベースとテーブルを URL に指定し、リクエストボディにデータを含めます。JSON ペイロードとしてデータを送信してください。

| **パラメーター** | **説明** |
|  --- | --- |
| `database` | URL に宛先データベース名を指定します。英字・数字・_ のみ使用できます。 |
| `table` | URL に宛先テーブル名を指定します。英字・数字・_ のみ使用できます。 |


### 認証

v2 は2つのヘッダーベース認証方法をサポートしています。どちらか一方を選択してください。両方送信した場合は `Authorization` が優先されます。

```bash
# 1. Authorization ヘッダー（TD1 スキーム）
-H 'Authorization: TD1 123/abcdef•••••••••••••••••••••••0123456789'

# 2. X-TD-Write-Key ヘッダー
-H 'X-TD-Write-Key: 123/abcdef•••••••••••••••••••••••0123456789'
```

#### サンプルリクエスト

```bash
curl -i -X POST 'https://us01.records.in.treasuredata.com/postback/v3/event/db_test/table_1' \
-H 'Content-Type: application/json' \
-H 'Authorization: TD1 123/abcdef•••••••••••••••••••••••0123456789' \
-d '{"email":"firstname.lastname@business.com","telephone":"555-555-5540"}'
```

```bash
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 15 May 2026 00:23:32 GMT
Strict-Transport-Security: max-age=31536000
Content-Length: 2
Connection: keep-alive

{}
```

### ペイロードの制限

リクエストボディの上限は **1,048,064 バイト** です。上限を超えるリクエストは `413 Payload Too Large` で拒否されます。

### API キーの検証

レガシーエンドポイントと同様に、無効な API キーを使用したリクエストは同期的に `200 OK` を返します。キーの検証はレスポンス送信後に非同期で実行されます。無効なキーは、HTTP レイヤーではなくインジェストパイプライン内で認証エラーとして表面化します。

## 関連情報

- [レガシー Postback API クイックスタート](/apis/postback/quickstart)
- [Treasure Toolbelt](https://toolbelt.treasuredata.com/) — Treasure AI サービス向けコマンドラインインターフェース
- [JavaScript SDK クイックスタート](/products/customer-data-platform/integration-hub/streaming/td-javascript-sdk/quickstart)