トラッキングコードを登録後、BowNow APIをご利用いただけるようになります。
APIはRESTfulに設計されており、レスポンスボディ内にJSONで返却し、エラーを示すHTTPレスポンスステータスコードを返却します。

• 日単位の使用制限があります。詳しくは「使用制限」を参照ください。
• APIについては弊社ではサポートできませんのでご了承ください。

APIをコールするまでに必要な手順を説明します。

1. 「トラッキングコードを変更する」画面から認証情報を取得
2. 認証情報を使用してアクセストークンを取得
3. トークンを使用してAPIをコールする

1. 「トラッキングコードを変更する」画面から認証情報を取得

認証はトラッキングコード単位で行います。
左メニューの「設定」-「システムを設定する」画面から、トラッキングコード名を選択します。

遷移先の「コード情報」内の「トラッキングID」と「APIキー」が認証情報になります。

※ 当該認証情報を利用して、リード情報の作成/更新/削除などが実行することが可能となりますので、十分に注意して取扱ください。

※ APIキーが漏洩した可能性がある場合はAPIキーの変更を実施してください。APIキーの変更を実施した場合は発行済みのアクセストークン及びリフレッシュトークンが削除されます。

2. 認証情報を使用してトークンを取得

「アクセストークン発行」エンドポイントにてトークンを取得します。
発行されたアクセストークンの有効期限は短く設定されているので、同レスポンスに含まれる refresh_token を使用して、「アクセストークン更新」エンドポイントへコールすることで、認証状態を永続化することも可能です。

$ curl --location --request POST "https://api.bownow.jp/v1/auth/token" \
    --header "Tracking-ID: <トラッキングID>" \
    --header "Content-Type: application/json" \
    --data-raw "{
        "api_key": "<APIキー>"
    }"

各トークンの説明

アクセストークン

認証状態を維持するために使用します。 有効期限は6時間です。

リフレッシュトークン

アクセストークンの有効期限が切れた際に更新するために使用します。 有効期限は1ヶ月です。

クライアントトークン

複数クライアントでのログイン状態を保持するために使用します。

3. トークンを使用してAPIをコールする

BowNow REST APIは、トラッキングコードIDとクライアントトークン、アクセストークンを要求します。

$ curl --location --request POST "https://api.bownow.jp/v1/statuses/search" \
    --header "Tracking-ID: <トラッキングID>" \
    --header "Client-Token: <クライアントトークン>" \
    --header "Authorization: Bearer <アクセストークン>" \
    --header "Content-Type: application/json" \
    --data-raw "{
        "ids": [
            1,2,3,4,5
        ]
    }"

APIは一定期間内でのリクエスト数を制限しています。
制限を超過した場合は 429 Too Many Requests を返却します。

クォータ

クォータは、ライセンス単位で管理されます。
以下のように、プランごとにクォータが適用されます。

BowNowプラン名	1日単位のクォータ
フリープラン	1,000リクエスト
有料プラン	10,000リクエスト

ステータスコード

429 Too Many Requests

レスポンスボディ

{
    "message": "too_many_requests",
    "description": "The request limit has been exceeded."
}

1分間あたりの呼び出し上限

リクエストクライアントのIP単位で管理されます。
以下のように、レートが設定されます。

BowNowプラン名	レート
フリープラン	300リクエスト
有料プラン	300リクエスト

ステータスコード

429 Too Many Requests

レスポンスボディ (文字列での返却)

Retry later

APIはリクエスト内容が不正だった場合や、想定外のエラーが発生した場合に共通のエラーをレスポンスします。 エラー内容ごとにHTTPレスポンスステータスコードが割り当てられます。 message にはエラーの種別、descriptionにはエラー内容、errorsにはエラーが発生した原因をそれぞれ示しています。

HTTPレスポンスステータスコード	message	主な原因
400	bad_request	リクエストボディの項目が不正な値である。
401	unauthorized	認証されていないリクエストである。
403	forbidden	アクセスが拒否された。
404	not_found	指定されたリソースが存在しない。
422	unprocessable_entity	リクエストボディの構造自体に誤りがある (JSON内のカンマが不足しているなど) 。
423	locked	指定されたリソースがロック中で処理できない。
429	too_many_requests	期間内に上限を超えるリクエストを実行された。
500	internal_server_error	BowNow REST APIで理解できない例外が発生した。

---

BowNowで発生したデータ操作をWebhook通知することができます。
設定されたURLにPOSTでデータ (JSON形式) 送信されます。

• Webhookは 有効/無効問わず10件まで 登録可能です。
• フォームコンバージョンによるリード情報更新通知は、一律 変更 イベントとして通知されます。
• APIによる操作はWebhook通知の対象外となります。
• Webhookについては弊社ではサポートできませんのでご了承ください。

Webhookを設定するために必要な手順を説明します。

1. 「Webhookを設定する」画面からWebhookを作成する

Webhookの作成はトラッキングコード単位で行います。
左メニューの「設定」-「Webhookを設定する」画面よりWebhookを作成します。

項目	必須	説明
Webhook名	○	Webhookに名称を付けることができます。
対象URL	○	Webhook通知を送信するURLを設定します。HTTPSのURLであることが必須です。 「対象URL」に、クエリ (URL末尾の ? 以降) が含まれていてもリクエスト時には無視されます。
送信形式	○	Webhook通知内容の送信形式を設定します。詳しくは送信形式を参照ください。
通知する条件		Webhook通知のトリガとなるイベントを設定します。
状態		「無効」に設定した場合はWebhook通知されません。

2. Webhook通知を受け取る

「通知する条件」に該当する操作が実行されると、「対象URL」にBowNowから操作内容と共にPOSTリクエストが送信されます。
受け取った情報をSlackに連携、メールで送信、お客様のデータベースに登録して一覧で表示するなどさまざまな用途に使用することができます。
BowNowから送信されるPOSTリクエストのリクエストボディは「通知内容」を参照ください。

3. Webhookの通知結果を確認する

Webhook通知が送信されると、通知ログがBowNowに登録されます。
通知ログから、登録された「対象URL」への通知が成功しているか、また失敗した場合どのようなステータスコードがレスポンスされたかを確認することができます。
Webhookを登録したけど通知が来ない場合はこちらの通知ログをご確認ください。
詳細は「通知ログ」を参照ください。

Webhook通知の送信形式はJSON形式、Slack向け、Microsoft Teams向けの3種類から設定可能です。

JSON形式を選択すると、通知内容全体がJSON構造で送信されます。
Slack向け、Microsoft Teams向けを選択すると、各アプリのWebhookに対応した形式及びライセンスアカウントの使用言語に応じて通知が行われます。
たとえば、使用言語が英語の場合は通知内容が英語となります。
なお、Slack向け、Microsoft Teams向けを選択した場合、通知する条件でリード情報更新の一括登録・操作（新規登録／変更／削除）はご利用できません。

Slack向け通知を行う際、Slack側のデータ変数は以下にて作成及びメッセージ通知設定をしてください。
キー：text
データタイプ：テキスト

具体的な通知内容は通知内容を参照ください。

各Webhookイベントごとの通知内容について説明します。

共通項目

全Webhook通知で共通の通知項目を説明します。

項目	説明
event	Webhook通知のトリガとなったイベントです。
resource_name	操作対象のリソース名です。
message	Webhook通知のトリガとなったイベントの詳細です。 イベントにより、この項目が存在しない場合があります。
records	操作対象のリソースを特定する情報です。

リード情報更新

リード情報を更新した際に通知されます。
通知内容は下記の通りです。

JSON形式通知項目

項目	値	説明
event	・新規登録：create ・変更：update ・削除：destroy ・一括登録・操作（新規登録／変更／削除）：bulk
resource_name	lead
message		・一括登録・操作（新規登録／変更／削除）のみこの項目が含まれます ・具体的なmessageはmessage一覧を参照
records		更新対象の配列
records.sid	更新対象リードのsid（リード固有のid）
records.url	更新対象のリード詳細URL	・リード削除及び一括登録・操作の削除時はこの項目は含まれません

JSON形式通知サンプル

{
  "event": "bulk",
  "resource_name": "lead",
  "message": "Status bulk update has been executed.",
  "records": [
    {
      "sid": "sid_xxxxxxxxxxxxxxxxxxxx",
      "url": "https://bownow.jp/users/xxxxx/details"
    },
    {
      "sid": "sid_xxxxxxxxxxxxxxxxxxxx",
      "url": "https://bownow.jp/users/xxxxx/details"
    }
  ]
}

Slack、Microsoft Teams向け通知項目

項目	値	説明
共通タイトル	BowNow Webhook
イベントタイトル	リード情報が更新されました。
更新内容	・新規登録：登録 ・変更：変更 ・削除：削除
sid	更新対象リードのsid（リード固有のid）
リード詳細URL	更新対象のリード詳細URL	・リード削除及び一括登録・操作の削除時はこの項目は含まれません

Slack、Microsoft Teams向け投稿サンプル

BowNow Webhook

リード情報が更新されました。
更新内容：登録
sid：sid_xxxxxxxxxxxxxxxxxxxx
リード詳細URL：https://bownow.jp/users/xxxxx/details

一括登録・操作（新規登録／変更／削除）の通知仕様

一括登録・操作時は、更新対象データをまとめて一括で通知します。
一回の通知に含まれるレコード数は最大1000件です。
更新対象データが1000件を超える場合は、1000件ごとに分けて通知されます。

message一覧

message	通知対象操作
Status bulk update has been executed.	・リードを探すにて「ステータス」の変更による一括操作時 ・メールの詳細にて「ステータス」の変更による一括操作時 ・トラッキングコード変更にてステータス名の変更時
Status bulk delete has been executed.	・トラッキングコード変更にてステータスの削除時
Status bulk update has been executed by ABM template.	・ABMテンプレート開始時 ・ABMテンプレートの日次処理によるステータスの変更時
Group bulk update has been executed.	・リードを探すにて「グループ」の変更による一括操作時 ・メールの詳細にて「グループ」の変更による一括操作時 ・トラッキングコード変更にてグループ名の変更時
Group bulk delete has been executed.	・トラッキングコード変更にてグループの削除時
Responsible person bulk update has been executed.	・リードを探すにて「担当者」の追加、上書き、設定解除による一括操作時 ・メールの詳細にて「担当者」の追加、上書き、設定解除による一括操作時 ・アカウントの担当者名の変更時
Responsible person bulk delete has been executed.	・アカウントの削除時
Tag bulk update has been executed.	・リードを探すにて「タグ」の追加、上書き、設定解除による一括操作時 ・メールの詳細にて「タグ」の追加、上書き、設定解除による一括操作時 ・フォームの詳細にて「タグ」の追加、上書き、設定解除による一括操作時
Tag bulk delete has been executed.	・トラッキングコード変更にてタグの削除時
Old email distribution group bulk update has been executed.	・リードを探すにて「旧メール配信グループ」の追加、上書き、設定解除による一括操作時 ・メールの詳細にて「旧メール配信グループ」の追加、上書き、設定解除による一括操作時
Old email distribution group bulk delete has been executed.	・トラッキングコード変更にて旧メール配信グループの削除時
Lead sources bulk delete has been executed.	・トラッキングコード変更にてリード獲得元の削除時
Member registered form bulk update has been executed.	・リードを探すにて「会員登録済みのフォーム」の追加、上書き、設定解除による一括操作時
Bulk registration has been executed.	・リードを一括登録するよりリード新規登録及び変更時
Bulk delete has been executed.	・リードを探すにてリード情報の削除による一括操作時

フォームコンバージョン

リードがフォームコンバージョンした際に通知されます。
通知内容は下記の通りです。

JSON形式通知項目

項目	値	説明
event	・新規リード（新規登録のリード）：new_lead_cv ・既存リード（登録済みのリード）：existing_lead_cv
resource_name	contact
records		操作対象の配列
records.contact_sid	コンバージョンしたフォームのsid（フォーム固有のid）
records.contact_name	コンバージョンしたフォーム名
records.management_number	コンバージョンしたフォーム内の管理番号
records.contact_type	・通常フォーム：normal_form ・会員登録フォーム：member_registration_form ・連携フォーム：linking_form
records.lead_sid	コンバージョンしたリードのsid（リード固有のid）
records.lead_url	コンバージョンしたリードのリード詳細URL

JSON形式サンプル

{
    "event": "new_lead_cv",
    "resource_name": "contact",
    "records": [
        {
            "contact_sid": "sid_xxxxxxxxxxxxxxxxxxxx",
            "contact_name": "xxxxxxxxxxx",
            "management_number": "xxxxxxxxxxx"
            "contact_type": "normal_form",
            "lead_sid": "sid_xxxxxxxxxxxxxxxxxxxx",
            "lead_url": "https://bownow.jp/users/xxxxx/details"
        }
    ]
}

Slack、Microsoft Teams向け通知項目

項目	値	説明
共通タイトル	BowNow Webhook
イベントタイトル	・新規リード（新規登録のリード）：新規登録のリードがフォームコンバージョンしました。 ・既存リード（登録済みのリード）：登録済みのリードがフォームコンバージョンしました。
種類	・通常フォーム：通常フォーム ・会員登録フォーム：会員登録フォーム ・連携フォーム：連携フォーム
フォームID	コンバージョンしたフォームのsid（フォーム固有のid）
フォーム名	コンバージョンしたフォーム名
管理番号	コンバージョンしたフォーム内の管理番号
リードsid	コンバージョンしたリードのsid（リード固有のid）
リード詳細URL	コンバージョンしたリードのリード詳細URL

Slack、Microsoft Teams向け投稿サンプル

BowNow Webhook

新規登録のリードがフォームコンバージョンしました。
種類：通常フォーム
フォームID：sid_xxxxxxxxxxxxxxxxxxxx
フォーム名：xxxxxxxxxx
管理番号：xxxxxxxxxx
リードsid：sid_xxxxxxxxxxxxxxxxxxxx
リード詳細URL：https://bownow.jp/users/xxxxx/details

「Webhookを設定する」画面より登録したWebhook単位で通知ログを参照することができます。
Webhook通知に失敗した場合はHTTPレスポンスステータスコードが表示されます。
通知ログは直近10件のみの表示となります。
また、通知にはリトライ機能が存在しません。タイムアウト (30秒) が発生した場合、HTTPレスポンスステータスコードは表示されません。

Webhook通知の送信者がBowNowであることの署名をリクエストヘッダで送信します。 リクエストヘッダを検証することでリプレイ攻撃を防ぎ、不正なリクエストを弾くことができます。

リクエストヘッダ

リクエストヘッダ名	説明
BowNow-Signature	APIキー、BowNow-Request-Token、タイムスタンプ、リクエストボディを : 繋ぎで連結した文字列をSHA-256でハッシュ化した値をURLセーフなBase64形式にエンコードした値です。
BowNow-Request-Token	Webhook通知ごとに生成される一意なトークン (UUID) です。
BowNow-Timestamp	リクエスト時のUNIX時刻です。

検証方法

署名生成時と同じアルゴリズムで計算することで、リクエストを検証することができます。

1. 「トラッキングコードを変更する」画面からAPIキーを取得します。
2. ハッシュ化する文字列を : 繋ぎで生成します 。
3. SHA-256アルゴリズムでハッシュ化します。
4. URLセーフなBase64形式にエンコードします。
5. 生成した値と BowNow-Signature の値が一致することを確認します。

サンプルコード

header_signature = request.headers["BowNow-Signature"]
header_token = request.headers["BowNow-Request-Token"]
header_timestamp = request.headers["BowNow-Timestamp"]
api_key = "your_api_key"
signature = Digest::SHA256.hexdigest("#{api_key}:#{header_token}:#{header_timestamp}:#{request.body.read}")
encoded_signature = Base64.urlsafe_encode64(signature)
raise "Invalid request" if !(encoded_signature.eql?(header_signature))

---

アクセストークンリソースを操作します。

トラッキングコードに設定されているリードリソースを操作します。

リード一括登録を実行します。

APIを利用してリード一括登録を行うために必要な手順を説明します。

1. CSVヘッダを取得
   リード一括登録用CSVヘッダ取得にリクエストし、リード一括登録するためのCSVヘッダを取得します。
   このCSVヘッダを利用して、リード一括登録用のCSVを作成します。
   各項目にどのような値を設定するか確認したい場合は、BoｗNowにログインしリード一括登録画面よりサンプルをダンロードしてください。（各項目のバリデーションについてはマニュアルサイト参照）
   
2. 一括登録CSVをアップロード
   作成したCSVをリード一括登録にリクエストし、リード一括登録処理を開始します。
   このAPIではリード一括登録処理を受け付けた時点でレスポンスし、実際のリード登録処理は非同期で行われます。
   
3. リード一括登録処理の進行状況を確認
   リード一括登録ステータス取得に定期的にリクエストし、リード一括登録処理の進行状況を確認します。
   処理時間目安としては、1万件あたり20分になります。
   処理時間は利用状況により変動します。参考値となりますのでご留意ください。
   status=completedになれば処理完了です。
   has_error=trueの場合、リード登録でエラーが発生しているため、手順4を参照し、エラー内容を確認してください。
   has_uncreated_corporates=trueの場合、登録に失敗した企業が存在しているため、手順5を参照し、未登録企業を確認してください。
   
4. エラー内容を確認
   リード一括登録エラーCSV取得にリクエストし、エラーCSVを取得してエラー内容を確認します。
   
5. 未登録企業を確認
   リード一括登録未登録企業CSV取得にリクエストし、未登録企業CSVを取得して未登録企業を確認します。
   

※処理中のリード一括登録が完了するまで、次のリード一括登録は受け付けません。
※エラーCSVや未登録企業一覧CSVは登録日から2か月後に削除されます。