Modifications

テンプレートは、名前付きのレイヤーで構成されたデザインです。modification は、1 回の描画に限って、そのレイヤーのいずれかを変更します。そのため、1 つのテンプレートから、商品、顧客、投稿ごとに異なるファイルを作れます。テンプレート自体は変わらず、modification のないレイヤーは、エディターで設定した値のままです。

modification は、ファイルを生成するすべてのリクエストで送ります。

{
  "apiKey": "YOUR_API_KEY",
  "templateId": "tpl_xxx",
  "modifications": [
    { "name": "headline", "text": "Summer sale" },
    { "name": "photo", "src": "https://example.com/shoes.png" },
    { "name": "badge", "visible": false }
  ]
}

レイヤーに名前を付ける

name は、テンプレートのレイヤー名と一致する必要があります。完全一致が条件のため、Headline と headline は別の名前です。

レイヤーの名前を変更するには、エディターのレイヤーパネルでレイヤーをダブルクリックします。API でテンプレートのレイヤー名を一覧するには、includeLayers=true を付けてテンプレート一覧を呼び出します。

値が変わらないときは、次の 2 つのルールが役立ちます。

• その名前のレイヤーがない場合、Bannerify は modification を無視し、エラーを返しません。まずスペルを確認してください。
• 複数のレイヤーが同じ名前を持つ場合、すべてのレイヤーに同じ modification が適用されます。

フィールド

フィールド	型	変更する内容
name	string	変更するレイヤー。必須
text	string	テキストレイヤーまたはリンクレイヤーのテキスト、アラートの本文、署名の署名者名
color	string	テキストレイヤーまたはリンクレイヤーの文字色（例: #ff5733）
src	string	画像レイヤーの画像 URL
href	string	リンクレイヤーの URL。PDF でクリックすると開きます
visible	boolean	すべてのレイヤーの表示と非表示
qrcode	string	QR コードレイヤーの内容
barcode	string	バーコードレイヤーの値
star	number	星レイヤーの評価。0 の値は無視されます
rows	array	表、グラフ、キー・バリューのレイヤーのデータ
columns	array	表レイヤーの列
title	string	アラートの見出し、または署名の役職
date	string	署名の日付

レイヤーに合わないフィールドは、Bannerify に無視されます。たとえば、テキストレイヤーに src を指定しても何も起こらず、color はテキストレイヤーだけを変更します。未知のフィールドも無視されます。

レイヤーごとに読み取られるフィールド

レイヤー	フィールド
テキスト	text, color, visible
リンク	text, color, href, visible
画像	src, visible
QR コード	qrcode, visible
バーコード	barcode, visible
星	star, visible
表	rows, columns, visible
グラフ	rows, visible
キー・バリュー	rows, visible
署名	text, title, date, visible
アラート	title, text, visible
アイコン、フレーム、線	visible

modification では、キャンバス、レイヤーの位置とサイズ、塗りの色は変更できません。これらはエディターで変更してください。

テキスト

新しいテキストは、レイヤーのテキスト全体を置き換えます。改行すると、新しい段落が始まります。フォントやサイズなど、レイヤー自体のスタイルは保たれますが、1 語だけの太字のようなテキスト内の書式は失われます。

画像

src は、PNG、JPEG、WebP、SVG ファイルの公開 URL にしてください。Bannerify は、描画中にファイルをダウンロードします。ダウンロードは最大 5 秒待ち、2 回再試行します。ダウンロードに失敗した場合や、ファイルが別の形式の場合、リクエストは FETCH_IMAGE_ERROR で失敗します。

表

表には、columns と rows を渡します。各行は、列名をキーにしたオブジェクトです。セルには、文字列、数値、真偽値、null のいずれかを入れられます。

{
  "name": "line-items",
  "columns": ["Item", "Qty", "Total"],
  "rows": [
    { "Item": "Automate plan", "Qty": 1, "Total": "$29.00" },
    { "Item": "Extra seat", "Qty": 2, "Total": "$10.00" }
  ]
}

列は、名前、または次のフィールドを持つオブジェクトです。

フィールド	型	説明
key	string	行がこの列に使うキー
header	string	ヘッダーセルのテキスト
align	left、center、right	セルの配置
width	string または number	列の幅

columns なしで rows を送ると、表はテンプレートの列を保ち、各行にはその列のキーが必要です。

グラフ

グラフには、rows を渡します。1 つの系列にはデータ点を、複数の系列には系列ごとのデータを渡します。

{
  "name": "revenue",
  "rows": [
    { "label": "Jan", "value": 22 },
    { "label": "Feb", "value": 31, "color": "#0d9373" }
  ]
}

{
  "name": "revenue",
  "rows": [
    { "name": "2025", "data": [{ "label": "Jan", "value": 22 }, { "label": "Feb", "value": 31 }] },
    { "name": "2026", "data": [{ "label": "Jan", "value": 27 }, { "label": "Feb", "value": 35 }] }
  ]
}

データ点には、label、数値の value、省略可能な color があります。系列には、name、data のデータ点、省略可能な color があります。

キー・バリュー

キー・バリューのレイヤーには、1 行につき 1 つの要素を持つ rows を渡します。value は文字列または数値で、Bannerify はテキストとして表示します。

{
  "name": "order-details",
  "rows": [
    { "key": "Order", "value": "1042" },
    { "key": "Total", "value": 29 }
  ]
}

受け付ける形式

modifications フィールドは 4 つの形を受け付け、どれも同じファイルを生成します。

形	用途
modification の配列	SDK が送る形式。このページではこの形式を使います
レイヤーごとに 1 つのキーを持つオブジェクト	ノーコードツールと、手軽なリクエスト
どちらかの形の JSON 文字列	署名付き URLのようなクエリ文字列
null または空文字列	modification なし

オブジェクトの形では、キーがレイヤーを指定します。値が文字列または数値の場合は text が設定され、値がオブジェクトの場合は、そのフィールドがそのまま使われます。

{
  "modifications": {
    "headline": "Summer sale",
    "photo": { "src": "https://example.com/shoes.png" },
    "badge": { "visible": false }
  }
}

真偽値には、オブジェクトが必要です。"badge": false はレイヤーのテキストを false に設定し、"badge": { "visible": false } はレイヤーを非表示にします。

リクエストを確認する

無効な modification は、BAD_REQUEST を返します。メッセージには、modifications[0].text のように、フィールドのパスが示されます。

すべてのフィールドと型は、Modification スキーマにまとめています。