会計拡張機能

ベータ版APIの利用とテストについて 

注:このAPIはベータ版として一般公開中で、テストとフィードバックに基づき変更される場合があります。こちらのエンドポイントをご使用になると、DeveloperおよびDeveloper Betaの利用条件(英語)に同意いただいたものと見なされます。また、まだ安定性が十分ではないAPIのリスクをご承諾およびご理解いただいたことになります。 

このAPIはベータ版です。 

はじめに

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

HubSpot上にアプリ定義を作成する

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

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

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

Hubspotユーザーのアカウントへの接続

OAuth

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

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

OAuthとHubSpotの接続が確立されたら、PUT /crm/v3/extensions/accounting/user-accountエンドポイントへの呼び出しを追加して、外部会計システム用のユーザーアカウントに関する追加情報を提供いただく必要があります。

HubSpot会計拡張機能からは、さまざまな会計機能のために設定したエンドポイントに対して多数のWebhook呼び出しが実行されます。このようなWebhook呼び出しにおいて会計システム用のユーザーのアカウントIDがHubSpotから送信されるので、システム内でどのアカウントが使用されているかが分かります。OAuthの場合は接続確立時にユーザーのアカウントIDが不明なため、アカウント情報は追加の呼び出しによって提供する必要があります。

受け取ったOAuthアクセストークンを使用してPUT https://api.hubapi.com/crm/v3/extensions/accounting/user-accountエンドポイントを呼び出すと、OAuthトークンで接続されたシステム内のアカウントに関する情報をHubSpotに提示できます。ペイロードの例を次に示します。

JSON
// アカウントの詳細の例
{
  "accountId": "acct-app-123",
  "accountName": "My Coffee Shop Accounts",
  "currencyCode": "USD"
}

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

認証

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

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

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

Webhook

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

呼び出しの流れ

以下の図に、一般的な呼び出しの流れを示します。

plantuml-4

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

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から送信された場合)は、貴社からはcallbackUrlに対してエラーレスポンスを送信します。

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

エラーレスポンスの構造

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

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

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

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

JSON
// エラーの形式
{
  "@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つの通貨の間の為替レートをリクエストできる
  • 支払い条件- 支払い条件を調べることができる
  • 請求書のコメント- 作成する請求書にコメントを追加できる

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

アプリの「Webhook」設定の構成

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

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

/settingsに、必要な本文を付けて、PUTリクエストを送信します。設定は、いつでも更新(PUT)または表示(GET)できます。

テンプレートのURL

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

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

JSON
ACCOUNT_NAME
ACCOUNT_ID
INVOICE_ID
CUSTOMER_ID
PRODUCT_ID

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

ダミーのエンドポイント

設定の中で有効にされている各機能にはエンドポイントURLが必須で、エンドポイント自体も必要になります。しかし、連携の当初は各エンドポイントをまだ実装できていないかもしれません。エンドポイントを実装できるまではダミーの値を入力しておいてください(http://example.comなど)。

必須URL

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

  • getInvoiceUrl
  • getInvoicePdfUrl
  • searchCustomerUrl

機能のURL

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

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

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

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

  • getInvoiceUrl
  • getInvoicePdfUrl
  • searchCustomerUrl

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

請求書インポート(主要機能)

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

  • 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エンドポイント

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

getInvoiceUrl(必須)

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

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

JSON
// 請求書を取得するリクエスト
{
  "invoiceIds": List<string>
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}

JSONの例

JSON
// リクエストの例
{
  "invoiceIds": [
    "inv-1",
    "inv-2"
  ],
  "metadata": {
    "requestId": "test-req-id"
  },
  "accountId": "123146316464684"
}

2)HubSpotへのレスポンス:

    200(本文なし)

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

JSON
// 請求書作成のレスポンス
{
  "@result": "OK",
  "invoices": [
    {
      "invoiceId": string,
      "invoiceNumber": string,
      "currency": string,
      "amountDue": number,
      "balance": number,
      "dueDate": string,
      "customerId": string,
      "customerName": string,
      "invoiceLink": string,
      "status": string
    }
  ]
}

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

  • CREATED:顧客への送信待ち。
  • SENT:請求書は顧客に送信されました。
  • PAID:請求書に対して一部支払いを受け取りました。
  • CLOSED:請求書の全額が支払われました。
  • OVERDUE:請求書は期限が過ぎています - 期日が過去の日付になっています。
  • VOIDED:請求書は無効化されました。

JSONの例

JSON
// レスポンスの例
{
  "@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
// リクエストの例
{
  "invoiceId": "inv-1",
  "metadata": {
    "requestId": "test-req-id"
  },
  "accountId": "123146316464684"
}

2)HubSpotへのレスポンス:

    200(本文なし)

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

JSON
// レスポンスの構造
{
  "@result": "OK",
  "invoice": string (format: byte)
}

invoiceフィールドは、請求書PDFのBASE64エンコード(バイト)文字列です。

JSONの例:

JSON
// レスポンスの例
{
  "@result": "OK",
  "invoice": "U3dhZ2dlciByb2Nrcw=="
}

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

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

searchCustomerUrl(必須)

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

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によるページ送りが可能になります。pageNumber1から始まります。
  • pageSizeは、検索から返される結果の最大数です。
  • fieldTypesは、検索方法を記述する文字列のリストです。有効な値は、以下のとおりです。
    • EMAIL:Eメールアドレスに検索文字列が含まれる顧客を返します。
    • NAME:名前に検索文字列が含まれる顧客を返します。
    • ID:IDが検索文字列に一致する顧客を返します。検索文字列に指定されるIDは1つだけです。

JSONの例

JSON
// リクエストの例
{
  "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
// 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
// 例
{
  "@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。

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

JSON
// 税金検索のリクエスト
{
  "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によるページ送りが可能になります。pageNumber1から始まります。
  • pageSizeは、検索から返される結果の最大数です。
  • fieldTypeは、検索方法を記述する文字列です。有効な値は、以下のとおりです。
    • INVOICE_NUMBER:番号に検索文字列が含まれる請求書を返します。
    • CUSTOMER_NAME:名前に検索文字列が含まれる顧客の請求書を返します。

JSONの例:

JSON
// リクエストの例
{
  "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
// 請求書検索のレスポンス
{
  "@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
// レスポンスの例
{
  "@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。

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

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

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

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

JSONの例:

JSON
// リクエストの例
{
  "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:

JSON
// 製品検索のレスポンス構造
{
  "@result": "OK",
  "products": [
    {
      "unitPrice": {
        "amount": number,
        "taxIncluded": boolean
      },
      "taxExempt": boolean,
      "salesTaxType": {
        "code": string,
        "name": string
      },
      "name": string,
      "description": string,
      "id": string
    }
  ]
}

JSONの例:

JSON
// 製品検索のレスポンス
{
  "@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。

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

JSON
// 税金検索のリクエスト
{
  "searchRequest": {
    "fieldType": "NAME_PARTIAL",
    "query": string,
  },
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}

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

JSONの例:

JSON
// 税金検索のリクエスト
{
  "searchRequest": {
    "fieldType": "NAME_PARTIAL",
    "query": "VAT",
  },
  "accountId": "123146316464684",
  "metadata": { 
    "requestId": "test-req-id" 
  }
}

2)HubSpotへのレスポンス:

    200(本文なし)

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

JSON
// レスポンスの構造
{
  "@result": "OK",
  "taxes": [
    {
      "code": string,
      "percentage": number,
      "name": string
    }
  ]
}

JSONの例:

JSON
// レスポンスの例
{
  "@result": "OK",
  "taxes": [
    {
      "code": "tax-1",
      "percentage": 13.5,
      "name": "Reduced VAT Rate"
    }
  ]
}

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

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

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

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

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

JSON
// 為替レートのリクエスト
{
  "sourceCurrencyCode": string,
  "targetCurrencyCode": string,
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}

JSONの例:

JSON
// リクエストの例
{
  "sourceCurrencyCode": "USD",
  "targetCurrencyCode": "EUR",
  "accountId": "123146316464684",
  "metadata": { 
    "requestId": "test-req-id" 
  }
}

2)HubSpotへのレスポンス:

    200(本文なし)

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

JSON
// 為替レートのレスポンス
{
  "@result": "OK",
  "sourceCurrencyCode": string,
  "targetCurrencyCode": string,
  "exchangeRate": number,
}

JSONの例:

JSON
// レスポンスの例
{
  "@result": "OK",
  "sourceCurrencyCode": "USD",
  "targetCurrencyCode": "EUR",
  "exchangeRate": 0.910847,
}

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

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

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

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

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

JSON
// 条件のリクエスト
{
  "accountId" : string,
  "customerId": Optional<string>,
  "metadata": { 
    "requestId": string 
  }
}

2)HubSpotへのレスポンス:

    200(本文なし)

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

JSON
// 条件のレスポンス
{
  "@result": "OK",
  "terms": [
    {
      "name": string,
      "id": string,
      "dueDays": integer
    }
  ]
}

JSONの例

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

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

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

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

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

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

JSON
// 顧客作成のリクエスト
{
  "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
// リクエストの例
{
  "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
// 顧客作成のレスポンス
{
  "@result": "OK",
  "id": string
}

JSONの例

JSON
// レスポンスの例
{
  "@result": "OK",
  "id": "new-cust-123"
}

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

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

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

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

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

JSON
// 請求書作成のリクエスト
{
    "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
// リクエストの例
{
  "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
// 請求書作成のレスポンス
{
  "@result": "OK",
  "id": string
}

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

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