会計拡張機能

概要エンドポイント

はじめに

このページでは、HubSpotでの会計拡張機能の連携に関するさまざまな手順について説明します。

HubSpotでアプリ定義を作成する

連携機能をハブユーザーのアカウントに接続するには、スポットハブ上に連携用のアプリ定義を作成する必要があります。ここでは、連携においてユーザーアカウントとの接続を初めて確立する際にスポットユーザーに対して表示される、ロゴやテキストなどの詳細情報を入力できます。また、ユーザーのハブスポットアカウントに対しどのような権限（スコープ ）を要求するかも定義できます。

作業を開始する際の手順は、次のとおりです。HubSpotの開発者ツールの使い方に関する概要も参照してください。

  1. 開発者アカウントを取得する
  2. 開発者アカウント上にアプリ定義を作成する（英語 ）
  3. 作成したアプリに変更を加え、使用するスコープに会計（会計 ）を追加する必要があります。 HubSpotとのコンタクトの同期に対応する計画がある場合は、コンタクト（コンタクト ）スコープも追加する必要があります。

ハブスポットユーザーのアカウントへの接続

OAuth

HubSpot ユーザーのアカウントに接続するには、連携機能からHubSpotに対し OAuth接続リクエストを行う必要があります。 HubSpotへの接続を開始する方法については、 OAuthの利用をご参照ください。

ユーザーアカウントの詳細

OAuth とHubSpotの接続が確立されたら、外部会計システムでのユーザーアカウントに関する追加情報が必要になります。この情報を取得するには、 PUTリクエストをエンドポイント/crm/v 3/extensions/accounting/user - accountに送信します。

さらに、これらのWebhook呼び出しの一部として追加のリクエストを行い、会計システム内のユーザーのアカウント IDを HubSpotに提供する必要もあります。この情報を提供するには、 PUTリクエストをエンドポイント HTTPS://API.HUBAPI.COM/CRM/V3/EXTENSIONS/ACCOUNTING/USER-ACCOUNTに送信します。

このリクエストには、前のリクエストで返されたOAuthアクセストークンを含める必要があります。これにより、そのトークンに関連付けられた、システム内のアカウントに関する情報が HubSpotに提供されます。ペイロードの例を次に示します。

// Example account details { "accountId": "acct-app-123", "accountName": "My Coffee Shop Accounts", "currencyCode": "USD" }

/user英語 - accounts （ ） APIを使用することにより、基本的な CRUD操作を実行できるうになります。顧客がアプリをインストール/アンインストールする際は、このAPIを呼び出して、どのアカウントが使用可能か、あるいは使用できなくなったかを HubSpotに通知する必要があります。

認証

HubSpot に対するAPIリクエストの認証は、 2種類あります。

  1. 開発者APIキー ：開発者キーは、 API会計拡張機能の場合は （/ settingsエンドポイント ）経由で貴社の HubSpotアプリに関連する設定の管理に使用します。
  2. OAuth トークン： OAuthトークンは、 HubSpotユーザーに代わって発行するリクエスト会計拡張機能の場合は （/ callbackおよび/userエンドポイント - accounts ）に使用する必要があります。会計拡張機能に使用する OAuthトークンをリクエストする際には、会計（会計 ）スコープを要求する必要があります。

詳細については、認証のドキュメントをご参照ください。

ウェブフック

貴社のサーバーに対してHubSpotから処理の実行や情報の取得のためのリクエストを送信する際には、エンドポイントに対する Webhook呼び出しとして行われます。以下の項では、 Webhook呼び出しの流れと、 HubSpotが呼び出すエンドポイントを貴社のサーバー上で設定する方法について説明します。

呼び出しの流れ

以下の図は、一般的な呼び出しの流れです。

プランツムル

呼び出しの手順は次のとおりです。

1. HubSpot からWebhookを受信する

設定したURLに APIリクエストが届き始めます。各リクエストの本文は、 JSONペイロードです。 Webhookのエンドポイントで取得しているリクエストが実際に HubSpot X - HubSpotから送信されたことを保証するために、 -ヘッダーには、貴社アプリのクライアントシークレットと、送信するリクエスト本文を連結した文字列に対する Signature SHA -256ハッシュが示されます。 Webhook署名の検証については、こちらのページ （英語 ）をご覧ください。

2. Webhookの受信確認を行う

貴社のサーバー側で、Webhookを受信し、 JSONペイロードの形式とリクエストの署名が適切であることを検証します。リクエストが有効な場合にはステータスコード 200、または無効な場合は 400を返してください。

要求された処理をサーバー側で実行する前に、Webhookの受信確認を行う必要があるのでご注意ください。

3. 処理の結果をHubSpotに送信する

要求された処理を完了したら、サーバーから結果をHubSpotに送信します。

HubSpot からのWebhookリクエストペイロードにはメタデータオブジェクトが含まれていて、メタデータオブジェクトには callbackUrlフィールドがあります。結果は、 callbackUrlエンドポイントに対し POSTを実行して送信してください。 OAuthアクセストークンは、リクエストで送信された accountIdにリンクされている HubSpotユーザーアカウントのものを使用してください。

4. HubSpotが結果を受信確認する

HubSpot 側で結果が受信および検証された場合にはステータスコード200、またはエラーがあった場合は 400が返されます。

結果のエラーをHubSpotに送信する場合

HubSpot から送信されたWebhookリクエストを無効と見なした場合 （例えば、すでに存在する顧客の作成を求めるリクエストが HubSpotから送信された場合 ）コールバックは、貴社からはUrlに対してエラーレスポンスを送信します。

コールバックエンドポイントへのレスポンスには、必ず@ resultフィールドを含めることにより、リクエストされたタスクの正常完了または失敗を表す OKかエラーのいずれかを値で示してください。

エラーレスポンスの構造

全てのコールバックエンドポイントは、5つのフィールドが格納された同じ形式のエラー JSONオブジェクトを受け取ります。

  • @ result: (文字列) エラーの場合、値は「エラー」。
  • message: (文字列) 発生したエラーに関するテキストによる説明。
  • category: (文字列) エラーのタイプ。次の値のうちのいずれかです。
    • CUSTOMER_ALREADY_EXISTENCE:すでに存在する顧客であるため、作成できません
    • VALIDATION_INVALID_INPUT ：テキストフィールドに無効な文字または記号が含まれています。例えば、貴社のシステムではサポートされない記号など （™）が顧客の名前に含まれています。
    • ライセンスの有効期限:貴社のシステム上で顧客のトライアルまたはライセンスが期限切れになったため、リクエストが拒否されました。
    • TAX_INFO_MISSING:必須の税金情報がないため、操作を完了できません。
    • OBJECT_ALREADY_EXISTING:オブジェクトがすでに存在しています。
    • CONNECTED_ACCOUNT_ERROR例 ：アカウントに問題があるため、リクエストが拒否されました （アカウントがすでに存在しない、要求された処理の実行権限がない ）。
    • VALIDATION_ERROR ： （前述のどのエラーカテゴリーにも該当しない理由により ）入力の検証に失敗しました。例えば、受信したリクエストが無効な JSONでした。
    • UNEXPECTED_ERROR:貴社システム側のサーバーエラーを表します (httpステータスコード 500など)。
    • INFULL_INVISITION ：請求書に記載されている数の品目の在庫がありません。コンテキストフィールドに値を入力して、請求書内のどの製品が不足しているかを示すと共に、残りの在庫数を含めてください。例えば、製品IDシューズが-123の在庫が残り 3シューズ個だけで、請求書上では-123の商品項目の必要数が 5になっている場合、次のようなエラーを返してください。

      {
      "@ result ": "エラー",
      "message ":ご依頼の数量を満たす在庫がありません。 "",
      "category ":"不十分な在庫",
      "timestamp ":" 2020 -03 -31 T 10: 15: 30 Z ",
      "context": {
      "shoe-123": ["3"]
      }
      }
  • タイムスタンプ： （文字列） エラーが発生した日時のISO 8601表記、またはエポックミリ秒のいずれか。
  • context: (map [string, string []])() エラー状態に関する追加情報任意。ユーザーが対処しやすいエラーメッセージをHubSpot insufficientが作成する際に使用されます。このフィールドの使用例については、_INVENTORYを参照してください。

以下にエラーレスポンスの例を示します。

// Error format { "@result": "ERR", "message": "The customer you are trying to create already exists.", "category": "CUSTOMER_ALREADY_EXISTS", "timestamp": "2020-03-31T10:15:30Z" }

Webhookエンドポイントの設定

サーバーにWebhookを送信するエンドポイントを HubSpotに提示すためには、貴社のアプリで「設定」する必要があります。この設定には、アプリが対応している「会計機能」や、 HubSpotからの Webhook送信先となる機能の URLが含まれます。 HubSpotによる処理ごとに、異なるエンドポイント設定が必要となります。

会計機能

会計拡張機能として構築するアプリには、ユーザー向けに利用できるさまざまな機能が用意されています。全ての機能に対応する必要はありませんが、どの機能に対応しているかを明示する必要があります。

主要機能

アプリでは、以下の主要機能のうちの少なくとも1つに対応する必要があります。

  • 請求書作成- ユーザーは、HubSpotから会計システム内の請求書を作成できます
  • 請求書インポート- ユーザーは、会計システムからHubSpotに請求書をインポートできます

請求書作成の副次機能

アプリが請求書作成に対応している場合、任意で以下の副次機能に対応できます。

  • 顧客作成 - 請求書作成の一部として顧客を作成できる
  • 税金 - 税金を検索できる
  • 為替レート - 2つの通貨間の為替レートをリクエストできる
  • 支払い条件 - 支払い条件を調べることができる
  • 請求書のコメント - 作成する請求書にコメントを追加できる
  • 請求書割引 - 請求書単位の割引を、請求書に追加することが可能かどうかを明示できる請求書割引に対応しない場合、見積もりから請求書を作成することは許可されません。HubSpotの見積もりには割引が含まれる可能性があり、作成する請求書に割引情報を含めることができない場合は、情報の誤りが生じる恐れがあるためです。

※これらの副次機能は請求書作成にのみ当てはまるため、アプリが請求書作成に対応しない場合、これらの内のいかなる副次機能も有効にすることはできません。

アプリの「Webhook」設定

アプリが対応している機能と、各機能のURL @ info: whatsthisを指定する必要があります。

https://api.hubapi.com/crm/v3/extensions/accounting/settings

/settings （英語 ）に、必要な本文を付けて、 PUTリクエストを送信します。設定は、いつでも更新 （プット）または表示 （ゲット）できます。

テンプレートのURL @ info: whatsthis

HubSpot CRMでは、顧客に対してディープリンクを表示しています。リンクを正しくかつ素早く表示するために、テンプレート URLのご提供をお願いいたします。

次のトークンがあります。

JSON 
ACCOUNT_NAME
ACCOUNT_ID
INVOICE_ID
CUSTOMER_ID
PRODUCT_ID

例貴社サービス上の請求書へのリンク: https://acountingservice.com/invoice/$?{ACCOUNT_ID} invoiceId =${INVOICE_ID}

ダミーのエンドポイント

HubSpotでは、有効化されている各機能の設定において、エンドポイント URLの特定が必須です。また、エンドポイント自体も必要です。。しかし、初めて連携を行う場合には、各エンドポイントをまだ実装できていない可能性があります。エンドポイントを実装できるまでは、ダミーの値を入力しておいてください （ http://example.comなど ）。

必須URL @ info: whatsthis

次のURL @ info: whatsthisは、必ず設定する必要があります。

  • getInvoiceUrl
  • getInvoicePdfUrl
  • searchCustomerUrl

機能のURL @ info: whatsthis

機能と関連するエンドポイントURL @ info: whatsthisを以下に示します。

  • 請求書作成 - createInvoiceUrl、 searchProductUrl
  • 請求書インポート - searchInvoiceUrl
  • 顧客作成 - createCustomerUrl
  • 税金 - searchTaxUrl
  • 為替レート - exchangeRateUrl
  • 支払い条件 - getTermsUrl
  • 請求書のコメント - この機能に関連するURLはありません
  • 請求書割引 - この機能に関連するURLはありません

Webhookエンドポイントの実装順序

Webhookエンドポイントを段階的に実装する場合は、必須の URLを任意の順序で実装してください。

  • getInvoiceUrl
  • getInvoicePdfUrl
  • searchCustomerUrl

これらが完了したら、対応している機能のURL @ info: whatsthisの実装を進めることができます。

請求書インポート（主要機能 ）

アプリが請求書インポートに対応していない場合は、この項を省略できます。それ以外の場合は、次のエンドポイントURL @ info: whatsthisの実装が必須です。

  • searchInvoiceUrl

請求書作成（主要機能 ）

アプリが請求書作成に対応している場合には、この主要機能に必要なURLを次の順序で実装してください （請求書作成時にはこの順序でエンドポイントが呼び出されます ）。

  1. searchProductUrl
  2. createInvoiceUrl

請求書作成（副次機能 ）

次の副次機能の、全てに対応する、何も対応しない、もしくは一部に対応することが可能です。全てに対応する場合、以下の順序で実装します。

  1. searchTaxUrl
  2. exchangeRateUrl
  3. getTermsUrl
  4. createCustomerUrl
  5. createInvoiceUrl

HubSpotでの連携のテスト

テスト用HubSpotアカウントを作成する

まず、開発者アカウント内からテスト用HubSpotアカウントを作成します。テストアカウントでは、会計連携を含め、 HubSpotのほとんどの機能をテストできます。

詳細は、テストアカウントの作成方法（英語 ）をご覧ください。

テストアカウントへのアプリのインストール

テストHubSpotアカウントが作成されたら、次にテストアカウントにアプリをインストールする必要があります。テストアカウント上にアプリがインストールされたことを確認するには、接続されたアプリのページに移動します

詳細は、アプリの認証とインストール（英語 ）をご参照ください。

請求書を作成する

上の請求書は、取引から作成されます。HubSpotの上部ナビゲーション領域から HubSpotの取引は、営業チームが特定のコンタクトまたは会社との間で進めている商取引を表します。取引は、セールス UIを選択し、取引を選択した後、 []取引を作成ボタンを押すことにより作成されます。取引を作成したら、作成した取引の概要画面が自動的に表示されます。この画面の右側に、 []請求書セクションがあります。 []請求書を作成をクリックし、作成する請求書の詳細を入力します。請求書作成フローのさまざまな段階で、 HubSpotからの Webhook呼び出しが届きます。

Webhookエンドポイント

以下に、/への呼び出しを設定できるWebhook設定エンドポイントを示します。各Webhookエンドポイントへの JSONペイロード送信と、コールバックの形式が示されています。個々のコールバックエンドポイントに関する詳細については、「エンドポイント」の項目をご覧ください。

getInvoiceUrl （必須 ）

請求書を取得できるエンドポイントを示すURL @ info: whatsthis。

1)サービスへのリクエストの JSON:

JSON 
// Get Invoices Request
{
  "invoiceIds": List<string>
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}

JSONの例

JSON 
// Example Request
{
  "invoiceIds": [
    "inv-1",
    "inv-2"
  ],
  "metadata": {
    "requestId": "test-req-id"
  },
  "accountId": "123146316464684"
}

2) HubSpotへのレスポンス:

    200 （本文なし ）

3コールバックエンドポイントへのリクエスト) HubSpot （/ callback/invoices /）{requestId} JSON ：

JSON 
// Customer Create Response
{
  "@result": "OK",
  "invoices": [
    {
      "invoiceId": string,
      "invoiceNumber": string,
      "currency": string,
      "amountDue": number,
      "balance": number,
      "dueDate": string,
      "customerId": string,
      "customerName": string,
      "invoiceLink": string,
      "status": string
    }
  ]
}

ステータスフィールドは、次のうちのいずれか1つを値とする文字列です。

  • 作成日:顧客への送信待ち。
  • 送信済み：請求書は顧客に送信されました。
  • 支払済：請求書に対して一部支払いを受け取りました。
  • クローズ：請求書の全額が支払われました。
  • 期限切れ請求書は期限が過ぎています：- 期日が過去の日付になっています。
  • 無効化された：請求書は無効化されました。

JSONの例

JSON 
// Example Response
{
  "@result": "OK",
  "invoices": [
    {
      "invoiceId": "inv-1",
      "invoiceNumber": "INV-123",
      "currency": "USD",
      "amountDue": 100.5,
      "balance": 50,
      "dueDate": "2020-03-31",
      "customerId": "cust-123",
      "customerName": "John Smith",
      "invoiceLink": "https://myapp.com/invoices/1243a2",
      "status": "OVERDUE"
    }
  ]
}

4)サービスへのレスポンスの JSON:

    200、または 400とエラー情報

getInvoicePdfUrl （必須 ）

請求書PDFを取得できるエンドポイントを示す URL。

1)サービスへのリクエストの JSON:

JSON 
// Example Request
{
  "invoiceId": "inv-1",
  "metadata": {
    "requestId": "test-req-id"
  },
  "accountId": "123146316464684"
}

2) HubSpotへのレスポンス:

    200 （本文なし ）

3コールバックエンドポイントへのリクエスト) HubSpot （/ callback/invoice - pdf{requestId} /） JSON ：

JSON 
// Response Structure
{
  "@result": "OK",
  "invoice": string (format: byte)
}

請求書フィールドは、請求書PDFの BASE 64エンコード （バイト ）文字列です。

JSONの例:

JSON 
// Example Response
{
  "@result": "OK",
  "invoice": "U3dhZ2dlciByb2Nrcw=="
}

4)サービスへのレスポンスの JSON:

    200、または 400とエラー情報

searchCustomerUrl （必須 ）

顧客検索を実行できるエンドポイントを示すURL @ info: whatsthis。

1)サービスへのリクエストの JSON:

JSON 
// searchCustomerUrl
{
  "pageNumber": Optional<int>,
  "pageSize": Optional<int>,
  "searchRequests": [
    {
      "query": string,
      "fieldTypes": [string]
    }
  ],
  "metadata": {
    "requestId": string
  },
  "accountId": string
}

searchRequestsに複数の検索語がある場合は、 or結合として処理してください。大文字小文字の区別は、貴社プラットフォームの既定の設定に従ってください。貴社のシステム上で Johnと JOHNが 2人の異なる顧客として区別される場合は、検索においても大文字と小文字を区別する必要があります。そうでない場合、大文字と小文字を区別しない設定にします。

  • pageNumberは、検索から返される結果のページ番号です。これにより、 HubSpot UIによるページ送りが可能になります。 pageNumberは 1から始まります。
  • pageSizeは、検索から返される結果の最大数です。
  • fieldTypesは、検索方法を記述する文字列のリストです。有効な値は、以下のとおりです。
    • メール： Eメールアドレスに検索文字列が含まれる顧客を返します。
    • 氏名：名前に検索文字列が含まれる顧客を返します。
    • ID ：が検索文字列に一致する顧客を返します。検索文字列に指定される IDは 1つだけです。

JSONの例

JSON 
// example request
{
  "searchRequests": [
    {
      "query": "Amy",
      "fieldTypes": [
        "NAME", "EMAIL"
      ]
    },
    {
      "query": "Birds",
      "fieldTypes": [
        "EMAIL"
      ]
    }
  ],
  "metadata": {
    "requestId": "tests-req-id"
  },
  "accountId": "123146316464684"
}

2) HubSpotへのレスポンス:

    200 （本文なし ）

3コールバックエンドポイントへのリクエスト) HubSpot （/ callback/customer - search{requestId} /） JSON ：

JSON 
// request to hubspot 
{
  "@result": "OK",
  "customers": [
    {
      "id": int,
      "name": string,
      "emailAddress": string,
      "billingAddress": {
        "lineOne": Optional<string>,
        "city": Optional<string>,
        "countrySubDivisionCode": Optional<string>,
        "postalCode": Optional<string>,
        "country": Optional<string>
      }
    },
    ...
  ]
}

JSONの例

JSON 
// example
{
  "@result": "OK",
  "customers": [
    {
      "id": "1",
      "name": "Amy's Bird Sanctuary",
      "emailAddress": "Birds@company.com",
      "billingAddress": {
        "lineOne": "4581 Finch St.",
        "city": "Bayshore",
        "countrySubDivisionCode": "CA",
        "postalCode": "94326",
        "country": null
      }
    },
    {
      "id": "58",
      "name": "Bobby",
      "emailAddress": "bobby@company.com"
    }
  ]
}

4)サービスへのレスポンスの JSON:

    200、または 400とエラー情報

searchInvoiceUrl （請求書作成機能が有効な場合は必須 ）

請求書検索を実行できるエンドポイントを示すURL @ info: whatsthis。

1)サービスへのリクエストの JSON:

JSON 
// Search Taxes Request
{
  "request": {
    "queryType": Optional<{
      "fieldType": string (INVOICE_NUMBER|CUSTOMER_NAME),
      "queryValues": List<string>,
    }>,
    "orderBy": string (DUE_DATE),
    "orderDirection": string (ASC|DESC),
    "pageNumber": Optional<integer>,
    "pageSize": Optional<integer>
  },
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}
  • pageNumberは、検索から返される結果のページ番号です。これにより、 HubSpot UIによるページ送りが可能になります。 pageNumberは 1から始まります。
  • pageSizeは、検索から返される結果の最大数です。
  • fieldTypeは、検索方法を記述する文字列です。有効な値は、以下のとおりです。
    • INVOICE_NUMBER:番号に検索文字列が含まれる請求書を返します。
    • CUSTOMER_NAME:名前に検索文字列が含まれる顧客の請求書を返します。

JSONの例:

JSON 
// Example request
{
  "request": {
    "queryType": {
      "fieldType": "CUSTOMER_NAME",
      "queryValues": [
        "Amy"
      ],
    },
    "orderBy": "DUE_DATE",
    "orderDirection": "DESC",
    "pageNumber": 1,
    "pageSize": 20
  },
  "accountId": "123146316464684",
  "metadata": { 
    "requestId": "test-req-id" 
  }
}

2) HubSpotへのレスポンス:

    200 （本文なし ）

3コールバックエンドポイントへのリクエスト) HubSpot （/ callback/invoice - search{requestId} /） JSON ：

JSON 
// Search Invoice Response
{
  "@result": "OK",
  "invoices": [
    {
      "invoiceId": string,
      "invoiceNumber": string,
      "currency": string,
      "amountDue": number,
      "balance": number,
      "dueDate": string,
      "customerId": string,
      "customerName": string,
      "invoiceLink": string,
      "status": string
    }
  ]
}

JSONの例:

JSON 
// Example response
{
  "@result": "OK",
  "invoices": [
    {
      "invoiceId": "inv-1",
      "invoiceNumber": "INV-123",
      "currency": "USD",
      "amountDue": 100.5,
      "balance": 50,
      "dueDate": "2020-03-31",
      "customerId": "cust-123",
      "customerName": "John Smith",
      "invoiceLink": "https://myapp.com/invoices/1243a2",
      "status": "OVERDUE"
    }
  ]
}

4)サービスへのレスポンスの JSON:

    200、または 400とエラー情報

searchProductUrl （請求書作成機能が有効な場合は必須 ）

製品検索を実行できるエンドポイントを示すURL @ info: whatsthis。

1)サービスへのリクエストの JSON:

// searchProductUrl { "pageNumber": Optional<int>, "pageSize": Optional<int>, "searchRequests": [ { "query": string, "fieldType": [string] } ], "metadata": { "requestId": string }, "accountId": string }

searchRequestに複数の検索語がある場合は、または結合として処理してください。大文字小文字の区別は、貴社プラットフォームの既定の設定に従ってください。貴社のシステム上でとシューズが2つの異なる製品として区別される場合は、検索においても大文字と小文字を区別する必要があります。そうでない場合、大文字と小文字を区別しない設定にします。

  • pageNumberは、検索から返される結果のページ番号です。これにより、 HubSpot UIによるページ送りが可能になります。 pageNumberは 1から始まります。
  • pageSizeは、検索から返される結果の最大数です。
  • fieldTypesは、検索方法を記述する文字列のリストです。有効な値は、以下のとおりです。
    • NAME_FULL:名前が検索文字列に一致する製品を返します。
    • NAME_PARTIAL:名前に検索文字列が含まれる製品を返します。
    • ID ：が検索文字列に一致する製品を返します。検索文字列に指定される IDは 1つだけです。

JSONの例:

// Example request { "searchRequests": [ { "query": "PROD-1", "fieldType": "ID" }, { "query": "Shoes", "fieldType": "NAME_PARTIAL" }, { "query": "Cotton Pants", "fieldType": "NAME_FULL" } ], "metadata": { "requestId": "tests-req-id" }, "accountId": "123146316464684" }

2) HubSpotへのレスポンス:

    200 （本文なし ）

3コールバックエンドポイントへのリクエスト) HubSpot （/ callback/product - search{requestId} /） JSON ：

// Product Search Response Structure { "@result": "OK", "products": [ { "unitPrice": { "amount": number, "taxIncluded": boolean }, "taxExempt": boolean, "salesTaxType": { "code": string, "name": string }, "name": string, "description": string, "id": string } ] }

JSONの例:

// Product Search Response { "@result": "OK", "products": [ { "unitPrice": { "amount": 10.99, "taxIncluded": false }, "taxExempt": false, "salesTaxType": { "code": "tax-1", "name": "Local Sales Tax" }, "name": "Marketing Services", "description": "Website design, Online advertising and SEO.", "id": "PROD-1" }, { "unitPrice": { "amount": 49.99, "taxIncluded": false }, "taxExempt": false, "salesTaxType": { "code": "tax-1", "name": "Local Sales Tax" }, "name": "Running Shoes", "description": "Special shoes aimed at running.", "id": "PROD-2" }, { "unitPrice": { "amount": 20.99, "taxIncluded": false }, "taxExempt": false, "salesTaxType": { "code": "tax-1", "name": "Local Sales Tax" }, "name": "Cotton Pants", "description": "Cotton pants, a fashion favorite for a stylish look.", "id": "PROD-3" } ] }

4)サービスへのレスポンスの JSON:

    200、または 400とエラー情報

searchTaxUrl 税金機能が有効な場合は必須()

税金検索を実行できるエンドポイントを示すURL @ info: whatsthis。

1)サービスへのリクエストの JSON:

JSON 
// Search Taxes Request
{
  "searchRequest": {
    "fieldType": "NAME_PARTIAL",
    "query": string,
  },
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}

fieldTypeは常に NAME_PARTIAL:名前に検索文字列が含まれる税金を返します。

JSONの例:

JSON 
// Search Taxes Request
{
  "searchRequest": {
    "fieldType": "NAME_PARTIAL",
    "query": "VAT",
  },
  "accountId": "123146316464684",
  "metadata": { 
    "requestId": "test-req-id" 
  }
}

2) HubSpotへのレスポンス:

    200 （本文なし ）

3コールバックエンドポイントへのリクエスト) HubSpot （/ callback/tax - search{requestId} /） JSON ：

JSON 
// Response structure
{
  "@result": "OK",
  "taxes": [
    {
      "code": string,
      "percentage": number,
      "name": string
    }
  ]
}

JSONの例:

JSON 
// Example response
{
  "@result": "OK",
  "taxes": [
    {
      "code": "tax-1",
      "percentage": 13.5,
      "name": "Reduced VAT Rate"
    }
  ]
}

4)サービスへのレスポンスの JSON:

    200、または 400とエラー情報

exchangeRateUrl （為替レート機能が有効な場合は必須 ）

為替レートを照会できるエンドポイントを示すURL @ info: whatsthis。

1)サービスへのリクエストの JSON:

JSON 
// Exchange Rate Request
{
  "sourceCurrencyCode": string,
  "targetCurrencyCode": string,
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}

JSONの例:

JSON 
// Example request
{
  "sourceCurrencyCode": "USD",
  "targetCurrencyCode": "EUR",
  "accountId": "123146316464684",
  "metadata": { 
    "requestId": "test-req-id" 
  }
}

2) HubSpotへのレスポンス:

    200 （本文なし ）

3コールバックエンドポイントへのリクエスト) HubSpot （/ callback/exchange - rate{requestId} /） JSON ：

JSON 
// Exchange Rate Response
{
  "@result": "OK",
  "sourceCurrencyCode": string,
  "targetCurrencyCode": string,
  "exchangeRate": number,
}

JSONの例:

JSON 
// Example response
{
  "@result": "OK",
  "sourceCurrencyCode": "USD",
  "targetCurrencyCode": "EUR",
  "exchangeRate": 0.910847,
}

4)サービスへのレスポンスの JSON:

    200、または 400とエラー情報

getTermsUrl （支払い条件機能が有効な場合は必須 ）

支払い条件を取得できるエンドポイントを示すURL。特定の顧客の支払い条件をリクエストする際に customerIdフィールドを送信します。しかし、 HubSpotユーザーが新しい請求書の作成の一部として新規顧客を作成する場合、 customerIdは送信されません。

1)サービスへのリクエストの JSON:

JSON 
// Terms Request
{
  "accountId" : string,
  "customerId": Optional<string>,
  "metadata": { 
    "requestId": string 
  }
}

2) HubSpotへのレスポンス:

    200 （本文なし ）

3コールバックエンドポイントへのリクエスト) HubSpot （/ callback/terms /）{requestId} JSON ：

// Terms Response { "@result": "OK", "terms": [ { "name": string, "id": string, "dueDays": integer } ] }

JSONの例

//example JSON { "@result": "OK", "terms": [ { "name": "Net 30", "id": "net-30", "dueDays": 30 } ] }

4)サービスへのレスポンスの JSON:

    200、または 400とエラー情報

createCustomerUrl （顧客作成機能が有効な場合は必須 ）

新しい顧客を作成できるエンドポイントを示すURL @ info: whatsthis。

1)サービスへのリクエストの JSON:

JSON 
// Customer Create Request
{
  "customerCreationRequest": {
    "name": string,
    "emailAddress": string,
    "companyName": Optional<String>,
    "billingAddress":{
      "lineOne": Optional<String>,
      "city": Optional<String>,
      "countrySubDivisionCode": Optional<String>,
      "postalCode": Optional<String>,
      "country": Optional<String>
    }
  },
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}

JSONの例

JSON 
// Example Request
{
  "customerCreationRequest": {
    "name": "Amy's Bird Sanctuary",
    "emailAddress": "Birds@birds.com",
    "companyName": "HubSpot",
    "billingAddress": {
      "lineOne": "25 First Street",
      "city": "Cambridge",
      "countrySubDivisionCode": "MA",
      "postalCode": "02141",
      "country": "United States"
    }
  },
  "metadata": {
    "requestId": "test-req-id"
  },
  "accountId": "123146316464684"
}

2) HubSpotへのレスポンス:

    200 （本文なし ）

3コールバックエンドポイントへのリクエスト) HubSpot （/ callback/customer - create{requestId} /） JSON ：

JSON 
// Customer Create Response
{
  "@result": "OK",
  "id": string
}

JSONの例

JSON 
// Example Response
{
  "@result": "OK",
  "id": "new-cust-123"
}

4)サービスへのレスポンスの JSON:

    200、または 400とエラー情報

createInvoiceUrl （請求書作成機能が有効な場合は必須 ）

請求書を作成できるエンドポイントを示すURL @ info: whatsthis。

1)サービスへのリクエストの JSON:

JSON 
// Invoice Create Request
{
    "invoiceCreationRequest": {
    "customerId": Optional<String>,
    "invoiceLines": [
      {
        "productId": string,
        "description" : string,
        "qty": int,
        "unitPrice": {
          "amount": double,
          "taxIncluded": boolean
        },
        "amount": double
      }
    ],
    "createDate": date
    "dueDate": date,
    "salesTermId": Optional<string>,
    "customerMessage": Optional<String>,
    "privateMessage": Optional<String>
  },
  "customerCreationRequest": Optional<{
    "name": string,
    "emailAddress": string,
    "companyName": Optional<String>,
    "billingAddress":{
      "lineOne": Optional<String>,
      "city": Optional<String>,
      "countrySubDivisionCode": Optional<String>,
      "postalCode": Optional<String>,
      "country": Optional<String>
    }
  }>,
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}

JSONの例

JSON 
// Example Request
{
  "invoiceCreationRequest": {
    "customerId": null,
    "invoiceLines": [
      {
        "productId": "PROD-3",
        "description": "Description to include in the invoice, overriding the product's default description",
        "qty": 3,
        "unitPrice": {
          "amount": 20.99,
          "taxIncluded": false
        },
        "amount": 4
      }
    ],
    "createDate": "2020-03-31T10:15:30Z",
    "dueDate": "2020-04-30T10:15:30Z",
    "salesTermId": "net-30",
    "customerMessage": "Message included on the invoice",
    "privateMessage": "Note attached to the invoice that only the accounting system user can see"
  },
  "customerCreationRequest": {
    "name": "Amy's Bird Sanctuary",
    "emailAddress": "Birds@birds.com",
    "companyName": null,
    "billingAddress": {
      "lineOne": null,
      "city": null,
      "countrySubDivisionCode": null,
      "postalCode": null,
      "country": null
    }
  },
  "metadata": {
    "requestId": "test-req-id"
  },
  "accountId": "123146316464684"
}

2) HubSpotへのレスポンス:

    200 （本文なし ）

3コールバックエンドポイントへのリクエスト) HubSpot （/ callback/invoice - create{requestId} /） JSON ：

JSON 
// Invoice Create Response
{
  "@result": "OK",
  "id": string
}

4)サービスへのレスポンスの JSON:

    200、または 400とエラー情報

参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。