> For the complete documentation index, see [llms.txt](https://guides.advertising.webtoon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guides.advertising.webtoon.com/line-manga/client-support/process-and-timeline/offer-wall-ads/server-integration-guide.md).

# WAJ サーバー連携ガイド

ユーザーが広告主アプリでインストールまたはインアプリイベントを完了すると、広告主サーバーからWAPにポストバックを送信します。切り替えの種類に応じて、インストールAPIとアプリイベントAPIを区別して呼び出す必要があります。

## 連動前の確認事項

Webtoon Ads Platformで次の情報を発行してもらうか、協議した後に連動します。

* `postback_provider_code`と`PROVIDER_API_KEY`
* 認証キーの受け渡し方式(ヘッダー / ボディ / クエリパラメータ)とその名称(ヘッダー名・クエリパラメータ名・JSONパス)
* リクエストフィールド名

{% hint style="info" %}
**NOTE**

このドキュメントのパラメータ表とサンプルは、デフォルト値(メソッド `POST`、JSONボディ、camelCaseフィールド名、認証キーは `X-PROVIDER-API-KEY` ヘッダー)を使用しています。実際の連携時には、上記で協議したメソッド・認証キーの受け渡し方式・パラメータの受け渡し方式・フィールド名に変更してリクエストする必要があります。
{% endhint %}

## ランディングURL

ユーザーが広告に参加した際、WAPはランディングURLに`clickKey`を付与して広告主様のページへ遷移させます。広告主様は、受け取った`clickKey`の値を保持し、成果完了時のポストバック送信時に値を変更せずそのまま返却する必要があります。

| Name       | Type   | 必須 | 説明                      |
| ---------- | ------ | -- | ----------------------- |
| `clickKey` | string | Y  | クリックごとに発行される広告・ユーザー識別キー |
| `userId`   | string | N  | ユーザー識別子                 |

基本フィールド名基準ランディングURL例:

```
https://advertiser.example/path?clickKey={clickKey}&userId={userId}
```

## 処理フロー

<figure><img src="/files/2jArGBJ7ICljUKfUsVzF" alt=""><figcaption></figcaption></figure>

## ポストバックAPI

### 共通リクエスト情報

| 項目        | 値                                                                               |
| --------- | ------------------------------------------------------------------------------- |
| Base URL  | `https://wads-apis-jp.webtoons.com/event/s2s/{postback_provider_code}/postback` |
| Method    | GET または POST                                                                    |
| 認証キーの受け渡し | ヘッダー / ボディ / クエリパラメータのうち、協議した方式                                                 |
| パラメータ伝達   | query parameterまたはJSON bodyのうち協議した方式                                            |

`postback_provider_code`と`PROVIDER_API_KEY`は一組で発行されます。両方の値が有効であり、かつ正しい組み合わせで一致している必要があります。

以下は、リクエストメソッドに POST、伝達方式に JSON Body を使用する場合の例です。

### アプリイベント (in-app-event)

```
GET または POST https://wads-apis-jp.webtoons.com/event/s2s/{postback_provider_code}/postback/in-app-event
```

インストール後、アプリ内で発生したコンバージョンイベントをポストバックします。`eventCode`以降のパラメータは、事前に広告側へ登録されたコードと一致している場合のみ処理されます。

| Name        | Type    | 必須 | デフォルト    | 形式                           | 説明                                                                           |
| ----------- | ------- | -- | -------- | ---------------------------- | ---------------------------------------------------------------------------- |
| `clickKey`  | string  | Y  | -        | ランディングURLで受信した値              | 広告・ユーザー識別キー                                                                  |
| `eventCode` | string  | Y  | -        | 広告に登録されたイベントコード              | コードが一致した場合のみ成果を生成                                                            |
| `userId`    | string  | N  | -        | ランディングURLで受信した値              | ユーザー識別子                                                                      |
| `revenue`   | decimal | N  | -        | 小数点は.（dot）区分、例:9.99          | 購入価格(major unit)。currencyと一緒に転送する必要があります。購入型広告で使用                            |
| `currency`  | string  | N  | -        | 決済通貨コード、例:"USD"              | 購入通貨。revenueと一緒に送信する必要があります。対応通貨:USD, EUR, KRW, JPY, GBP, CNY, CAD, AUD, INR |
| `eventTime` | number  | N  | サーバー到着時刻 | epoch seconds, 例: 1783597257 | イベント発生時刻                                                                     |

```bash
curl -X POST 'https://wads-apis-jp.webtoons.com/event/s2s/{postback_provider_code}/postback/in-app-event' \
  -H 'X-PROVIDER-API-KEY: {PROVIDER_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{"clickKey":"{clickKey}","eventCode":"test","revenue":9.99,"currency":"USD","eventTime":1783597257}'
```

GETとquery parameter で協議した場合:

```bash
curl 'https://wads-apis-jp.webtoons.com/event/s2s/{postback_provider_code}/postback/in-app-event?clickKey={clickKey}&eventCode=test&revenue=9.99&currency=USD&eventTime=1783597257' \
  -H 'X-PROVIDER-API-KEY: {PROVIDER_API_KEY}'
```

### インストール (install) (オプション)

```
GET または POST https://wads-apis-jp.webtoons.com/event/s2s/{postback_provider_code}/postback/install
```

アプリインストール（初回起動）のコンバージョンを報告します。インストール成果の計測が不要な場合は、本APIの連携は不要です。※インストールAPIでは`eventCode`、`revenue`、`currency`パラメータは送信しません。

| Name          | Type   | 必須 | デフォルト    | 形式                           | 説明          |
| ------------- | ------ | -- | -------- | ---------------------------- | ----------- |
| `clickKey`    | string | Y  | -        | ランディングURLで受信した値              | 広告・ユーザー識別キー |
| `userId`      | string | N  | -        | ランディングURLで受信した値              | ユーザー識別子     |
| `installTime` | number | N  | サーバー到着時刻 | epoch seconds, 例: 1783597257 | インストール発生時刻  |

```bash
curl -X POST 'https://wads-apis-jp.webtoons.com/event/s2s/{postback_provider_code}/postback/install' \
  -H 'X-PROVIDER-API-KEY: {PROVIDER_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{"clickKey":"{clickKey}","installTime":1783597257}'
```

## 応答およびエラー

両APIの応答形式は同じです。

### 成功

ステータスコード「200 OK」は、リクエストが正常に受け付けられたことを示しますが、成果処理やリワード付与の完了を保証するものではありません。リワードの付与処理は非同期で行われます。同一の`clickKey`と`eventCode`の組み合わせに対して、リワードが重複して付与されることはありません。そのため、応答が得られなかった場合やタイムアウトが発生した場合は、同じパラメータで再試行を行っていただいて問題ありません。

```
HTTP/2 200
content-length: 0
```

### エラー

```json
{ "meta": { "code": 400001, "note": "Bad Request" }, "results": [] }
```

| HTTP | meta.code | 意味           | 原因                                                                         |
| ---- | --------- | ------------ | -------------------------------------------------------------------------- |
| 400  | 400001    | Bad Request  | 必須パラメータ(clickKey·eventCode)不足、またはパラメータ形式エラー(revenue・eventTime・currency など) |
| 401  | 401001    | Unauthorized | 認証失敗                                                                       |
| 403  | 403001    | Forbidden    | アクセス権限なし                                                                   |
| 404  | 404001    | Not Found    | 指定されたclickKeyに該当する広告参加(クリック)履歴なし                                           |

{% hint style="success" %}
連携に関するお問い合わせは、担当のアカウントマネージャーまでお問い合わせいただければ、\
詳しくご案内いたします。
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://guides.advertising.webtoon.com/line-manga/client-support/process-and-timeline/offer-wall-ads/server-integration-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.