対象月の請求書を取得する
選択した月の請求明細を返します。
https://api2.transloadit.com/ bill/ {billYearMonth}指定された月の請求データを取得します。
レスポンスの請求フィールドを使用する前に、ok === "BILL_FOUND" であることを確認してください。請求書が存在しない場合や検索に失敗した場合は、HTTP 200 とともに error: "BILL_NOT_FOUND" が返されるため、HTTP ステータスだけでは請求書が見つかったとは判断できません。
billYearMonth パスパラメーターの形式は YYYY-MM です。たとえば、2019 年 3 月の請求書を取得するには、2019-03 を使用します。
リクエスト例
BILL_YEAR_MONTH に、リソースの値をパーセントエンコードせずに設定してください。
解約済みの Workspaces では、新しい Bearer トークンを作成できません。このエンドポイントは、既存の有効な Auth Key で引き続き利用できます。以下のトークン設定手順の代わりに、署名付きの請求情報取得レシピを使用してください。このキーには、このエンドポイントで必要なスコープが付与されている必要があります。
サーバー側のシェルで、curl を使用し、適切な Bearer トークンを TRANSLOADIT_TOKEN に設定して、このリクエストを実行してください。トークンが必要な場合は、以下の設定手順を展開してください。
Bearer トークンが必要ですか?
curl と jq を使用できる信頼できるサーバー側のシェルで、TRANSLOADIT_KEY と TRANSLOADIT_SECRET にそれぞれ Auth Key と Auth Secret を設定してください。両方の認証情報と生成されるトークンは秘密にしてください。この設定手順をブラウザーのコード内で実行しないでください。
まず、このエンドポイントで必要なスコープを持つトークンを作成します。Auth Key には、それらのスコープがあらかじめ付与されている必要があります。
if ! TOKEN_RESPONSE="$(curl --fail-with-body -sS \
--request POST \
--url 'https://api2.transloadit.com/token' \
--user "${TRANSLOADIT_KEY:?Set TRANSLOADIT_KEY}:${TRANSLOADIT_SECRET:?Set TRANSLOADIT_SECRET}" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'aud=api2' \
--data-urlencode 'scope=billing:read')"; then
printf '%s\n' "$TOKEN_RESPONSE" >&2
exit 1
fi
TRANSLOADIT_TOKEN="$(printf '%s' "$TOKEN_RESPONSE" |
jq -er '.access_token | strings | select(length > 0)')" || exit 1
このシェルを開いたままにして、以下のリクエストを実行してください。トークンが有効な間は再利用してください。
curl --fail-with-body -sS --request GET --get \
--url "https://api2.transloadit.com/bill/${BILL_YEAR_MONTH:?Set BILL_YEAR_MONTH}" \
--header "Authorization: Bearer ${TRANSLOADIT_TOKEN:?Set TRANSLOADIT_TOKEN}" \
--data-urlencode 'params={}'
認証
このエンドポイントは、署名付きの params または Bearer トークンを受け付けます。設定手順については、認証を参照してください。
Auth Key または Bearer トークンに必要なスコープ: billing:read。
Signature 付きリクエストには、signature と、将来の時刻を示す params.auth.expires タイムスタンプの両方が必要です。Bearer トークンには、どちらも必要ありません。
パスパラメーター
billYearMonth(パスセグメント)、必須。パターン:^[0-9]{4}-(?:0[1-9]|1[0-2])$
クエリパラメーター
params(JSON 文字列)。JSON エンコードされたオブジェクトで、サポートされるキーは以下のとおりです。signature(文字列)。署名付きリクエストでは必須です。Bearer トークンを使用する場合は、このフィールドを省略してください。
署名対象の params フィールド内でサポートされるキー
この一覧の認証フィールドは、署名付きリクエストに適用されます。Bearer トークンを使用する場合は、params.auth と、それとは別の signature フィールドを省略できます。以下の認証方式ごとのリクエストパラメーターを比較してください。
完全な JSON スキーマ
params: このオブジェクトでは、一覧に記載されているフィールドのみが受け付けられます。
| フィールド | 型と説明 |
|---|---|
params.署名付きリクエストでは必須。Bearer トークンを使用する場合は任意 | 請求リクエスト用の Transloadit API キーと Signature Authentication のメタデータを含みます。
|
params.必須 | string将来の日時を示す ISO 8601 形式の有効期限タイムスタンプ。リクエストが署名されている場合、または Signature Authentication が必要な場合は必須です。Bearer 認証を使用するリクエストでは省略できます。 |
params.必須 | stringリクエストの認証に使用する Transloadit API キー |
params. | string | integer各 Signature を一意にし、Signature の意図しない再利用を防ぐために、署名付きリクエストのパラメーターに含める一意のランダムな値。 |
認証方式別のリクエストパラメーター
署名付き params
Auth Key を params.auth.key として含めてください。リクエストに署名する場合は、将来の時刻を示す params.auth.expires タイムスタンプを含め、Signature を別の signature フィールドで送信してください。以下のフィールド定義では、params 内のパスを使用しています。
完全な JSON スキーマ
params: このオブジェクトでは、一覧に記載されているフィールドのみが受け付けられます。
上記のフィールド定義を使用します: params.auth, params.nonce
Bearer トークンを使用する場合
Bearer トークンを Authorization ヘッダーで送信してください。params.auth と、それとは別の signature フィールドは省略できます。他の必須パラメーターの要件は引き続き適用されます。以下のフィールド定義では、params 内のパスを使用します。
完全な JSON スキーマ
params: このオブジェクトでは、一覧に記載されているフィールドのみが受け付けられます。
上記のフィールド定義を使用します: params.nonce
| フィールド | 型と説明 |
|---|---|
params. | 請求リクエスト用の Transloadit API キーと Signature Authentication のメタデータを含みます。
|
params. | string将来の日時を示す ISO 8601 形式の有効期限タイムスタンプ。リクエストが署名されている場合、または Signature Authentication が必要な場合は必須です。Bearer 認証を使用するリクエストでは省略できます。 |
params. | stringリクエストの認証に使用する Transloadit API キー |
解約後の請求情報へのアクセス
解約済みの Workspaces では、新しい Bearer トークンを作成できません。これらの Workspaces の請求書を取得するには、上記のトークン設定の代わりに、既存の有効な Auth Key とその Auth Secret を使った署名付きリクエストを使用してください。そのキーは、このエンドポイントに記載されているスコープを引き続き許可している必要があります。
Node.js SDK は請求リクエストに直接署名し、/token は呼び出しません。信頼できるサーバー側の Node.js プロジェクトで、yarn add @transloadit/node を使用してインストールしてください。TRANSLOADIT_KEY、TRANSLOADIT_SECRET、BILL_YEAR_MONTH(例:2026-08)を環境変数として設定してください。シークレットはバックエンドに保持してください。
この SDK の例では、新しく作成された API キーのデフォルトである sha384 を使用しています。キーが別の Signature アルゴリズムを使用している場合は、Signature Authentication
の手順に従い、代わりにその設定済みのアルゴリズムを使用してください。
以下を bill.mjs として保存し、node bill.mjs を実行してください。
import { Transloadit } from '@transloadit/node'
const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, BILL_YEAR_MONTH } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !BILL_YEAR_MONTH) {
throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and BILL_YEAR_MONTH')
}
const transloadit = new Transloadit({
authKey: TRANSLOADIT_KEY,
authSecret: TRANSLOADIT_SECRET,
})
const bill = await transloadit.getBill(BILL_YEAR_MONTH)
if (bill.ok !== 'BILL_FOUND') throw new Error('No bill was returned')
console.log(JSON.stringify(bill, null, 2))
レスポンス
レスポンスボディの例を以下に示します:
{
"additional_gb": 0,
"additional_gb_fee": 0,
"address_1": "Jimbostreet 19",
"address_2": "",
"bill_limit": 0,
"city": "Berlin",
"company": "Jimbo Jones GmbH",
"country": "Germany",
"created": "2014-07-01T06:58:32.000Z",
"credit": 0,
"email": "testuser@example.org",
"invoice_id": "0d04b65924da41d4b68c80f776d196d5",
"is_prorated": false,
"month": "2014-06",
"ok": "BILL_FOUND",
"plan": {
"gb_included": 35,
"gb_limit": null,
"has_lifetime_limit": false,
"id": "3599821193a1f77baafb98e5f8fb17a6",
"price_per_gb": 2.85,
"price_per_month": 99
},
"reverse_charge_vat": false,
"reward_discount": 1.98,
"reward_discount_percent": 2,
"robots": {
"/assemblies": {
"factor": 0,
"freeGb": 0,
"gb": 0,
"gbFactorApplied": 0,
"rawGb": 0
},
"/s3/store": {
"factor": 10,
"freeGb": 0.57,
"gb": 0.6,
"gbFactorApplied": 1.17,
"rawGb": 11.75
},
"/video/encode": {
"factor": 1,
"freeGb": 0,
"gb": 21.05,
"gbFactorApplied": 21.05,
"rawGb": 21.05
},
"/video/thumbs": {
"factor": 10,
"freeGb": 0,
"gb": 0.34,
"gbFactorApplied": 0.34,
"rawGb": 3.42
}
},
"signup_discount": 0,
"signup_discount_percent": 0,
"state": null,
"sub_total": 99,
"to": "Test User",
"total": 115.45,
"used_gb": 21.99,
"vat": 18.43,
"vat_id": "",
"vat_rate": 0.19,
"zip": "10117"
}2xx 成功
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
次のいずれかのスキーマが適用される場合があります:
バリアント 1
レスポンスには、このオブジェクトについて記載されているフィールドのみが含まれます。
| フィールド | 型と説明 |
|---|---|
additional_gb | number (最小値: 0) |
additional_gb_fee | number |
address_1 | null | string |
address_2 | null | string |
annual_commitment_id | null | string |
bill_limit | number |
city | null | string |
company | null | string |
country | null | string |
country_id | null | string |
coupon_discount | number | string | null
|
coupon_discount_percent | number | string | null
|
created必須 | string | null (最小長: 1) |
credit必須 | number | string | null
|
currency | null | string |
email | null | string |
final_sub_total | number |
invoice_id必須 | null |
invoice_type | "annual_prepayment" | "monthly_usage" |
is_prorated必須 | boolean |
month必須 | string検証パターン(正規表現)^[0-9]{4}-(?:0[1-9]|1[0-2])$ |
ok必須 | string (常に: "BILL_FOUND") |
plan必須 |
|
plan.必須 | number | string
|
plan.必須 | number | string | null
|
plan.必須 | boolean | 0 | 1 | "0" | "1" | null次のいずれかのスキーマが適用される場合があります: boolean | 0 | 1 | "0" | "1"boolean | 0 | 1 | "0" | "1"null |
plan.必須 | null | string |
plan.必須 | number | string
|
plan.必須 | number | string
|
po_number | null | string |
prepaid_base_fee | number (最小値: 0) |
reverse_charge_vat | boolean |
reward_discount | number | string | null
|
reward_discount_percent | number | string | null
|
robots必須 | object |
service_ends_on | null | string |
service_starts_on | null | string |
signup_discount | number | string | null
|
signup_discount_percent | number | string | null
|
state | null | string |
sub_total必須 | number |
tiers | 任意の値 |
to | null | string |
to_contact_email_address | null | string |
total必須 | number |
used_gb | number (最小値: 0) |
vat | number |
vat_id | null | string |
vat_rate | number |
zip | null | string |
バリアント 2
レスポンスには、このオブジェクトについて記載されているフィールドのみが含まれます。
| フィールド | 型と説明 |
|---|---|
additional_gb | number (最小値: 0) |
additional_gb_fee | number |
address_1 | null | string |
address_2 | null | string |
annual_commitment_id | null | string |
bill_limit | number |
city | null | string |
company | null | string |
country | null | string |
country_id | null | string |
coupon_discount | number | string | null
|
coupon_discount_percent | number | string | null
|
created必須 | string | null (最小長: 1) |
credit必須 | number | string | null
|
currency | null | string |
custom_expenses | 任意の値 |
email | null | string |
final_sub_total | number |
invoice_id必須 | string | number |
invoice_type | "annual_prepayment" | "monthly_usage" |
is_prorated必須 | boolean |
month必須 | string検証パターン(正規表現)^[0-9]{4}-(?:0[1-9]|1[0-2])$ |
ok必須 | string (常に: "BILL_FOUND") |
plan必須 |
|
plan.必須 | number | string
|
plan.必須 | number | string | null
|
plan.必須 | boolean | 0 | 1 | "0" | "1" | null次のいずれかのスキーマが適用される場合があります: boolean | 0 | 1 | "0" | "1"boolean | 0 | 1 | "0" | "1"null |
plan.必須 | null | string |
plan.必須 | number | string
|
plan.必須 | number | string
|
po_number | null | string |
prepaid_base_fee | number (最小値: 0) |
reverse_charge_vat | boolean |
reward_discount | number | string | null
|
reward_discount_percent | number | string | null
|
robots必須 | string | number | boolean | null | Array<任意の値> | object次のいずれかのスキーマが適用される場合があります: stringnumberbooleannullArray<任意の値>Array<任意の値>配列要素のスキーマ任意の値objectobject追加プロパティのスキーマ任意の値 |
service_ends_on | null | string |
service_starts_on | null | string |
signup_discount | number | string | null
|
signup_discount_percent | number | string | null
|
state | null | string |
sub_total必須 | number |
tiers | 任意の値 |
to | null | string |
to_contact_email_address | null | string |
total必須 | number |
used_gb | number (最小値: 0) |
vat | number |
vat_id | null | string |
vat_rate | number |
zip | null | string |
エラーレスポンス
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
レスポンスには追加のフィールドが含まれる場合があります。
| フィールド | 型と説明 |
|---|---|
assembly_id | string |
error | string (最小長: 1) |
http_code | number | string
|
message | string人が読んで理解できる形式のエラー説明です。文言は変わる場合があるため、特定の失敗を処理する際は |
reason | null | string | number | boolean | Array<任意の値> | object次のいずれかのスキーマが適用される場合があります: nullstringnumberbooleanArray<任意の値>Array<任意の値>配列要素のスキーマ任意の値objectobject追加プロパティのスキーマ任意の値 |
HTTP 400
JSON レスポンスの本文。 application/json text/plain; charset=utf-8
レスポンスボディのスキーマ
完全な JSON スキーマ
名前付きエラーと一般的なエラー形式
error: "SIGNATURE_REUSE_DETECTED"
セキュリティ上の理由により、リクエストが拒否されました。これが誤りだと思われる場合は、サポートにお問い合わせください。
レスポンスには追加のフィールドが含まれる場合があります。
一般的なエラー形式
当月と、超過利用のない年払いの対象月では、invoice_id は null です。
年間分を前払いしても、サービス期間は暦月単位のままで、料金に含まれる GB 枠も毎月リセットされます。対象月では、割引、クレジット、最低請求額の処理、VAT の適用前に、prepaid_base_fee で定価の月額料金を相殺します。annual_commitment_id は、購入した契約条件を識別します。超過利用のない対象月は支払額がゼロとなり、請求書は作成されません。月ごとの超過利用の請求書には、監査のため、購入時の月額料金とその前払い調整額が保持されます。
年間分の請求書には invoice_type: "annual_prepayment" と、UTC の開始日 service_starts_on および終了日 service_ends_on(終了日当日はサービス期間に含みません)が含まれます。月次請求書では invoice_type: "monthly_usage" を使用します。