メインコンテンツまでスキップ

テンプレートのパラメータ取得

GET /file/design/parameter/{designId} エンドポイントは、指定されたテンプレート IDのパラメータ構造を取得します。PDFやサムネイル生成時に必要なパラメータのスキーマを確認できます。

エンドポイント情報​

  • URL: https://api.re-port-flow.com/v1/file/design/parameter/{designId}
  • メソッド: GET
  • 認証: appkey ヘッダーが必要

使用例​

cURL​

# 最新バージョンのパラメータを取得
curl -X GET https://api.re-port-flow.com/v1/file/design/parameter/0eUDdgAjNXrrItA2 \
  -H "appkey: your-application-key"

# 特定バージョンのパラメータを取得
curl -X GET "https://api.re-port-flow.com/v1/file/design/parameter/0eUDdgAjNXrrItA2?version=1" \
  -H "appkey: your-application-key"

JavaScript​

async function getDesignParameters(designId, version = null) {
  const baseUrl = 'https://api.re-port-flow.com/v1';
  const url = version
    ? `${baseUrl}/file/design/parameter/${designId}?version=${version}`
    : `${baseUrl}/file/design/parameter/${designId}`;

  const response = await axios.get(url, {
    headers: {
      'appkey': process.env.APP_KEY
    }
  });

  return response.data;
}

// 使用例
const schema = await getDesignParameters('0eUDdgAjNXrrItA2');
console.log('パラメータスキーマ:', schema);

Python​

def get_design_parameters(design_id, version=None):
    base_url = "https://api.re-port-flow.com/v1"
    url = f"{base_url}/file/design/parameter/{design_id}"

    if version:
        url += f"?version={version}"

    headers = {
        'appkey': os.getenv('APP_KEY')
    }

    response = requests.get(url, headers=headers)
    response.raise_for_status()

    return response.json()

# 使用例
schema = get_design_parameters('0eUDdgAjNXrrItA2')
print('パラメータスキーマ:', schema)

パラメータ​

パラメータ型必須説明
designIdstring✓テンプレート ID（16文字の英数字。例: 0eUDdgAjNXrrItA2。パスパラメータ）
versioninteger-バージョン番号（クエリパラメータ、省略時は最新）

レスポンス​

成功時 (200 OK)​

[
  { "name": "customerName", "type": "text", "label": "顧客名" },
  { "name": "invoiceNumber", "type": "text", "label": "請求書番号" },
  { "name": "amount", "type": "number", "label": "金額" },
  {
    "name": "items",
    "type": "array",
    "label": "明細",
    "spec": [
      { "name": "name", "type": "text", "label": "品目" },
      { "name": "price", "type": "number", "label": "単価" },
      { "name": "quantity", "type": "number", "label": "数量" }
    ]
  },
  { "name": "issueDate", "type": "date", "label": "発行日" }
]

レスポンスは、入力画面を構築できるパラメータ定義の配列です。name はPDF生成時の params のキー、label は表示名です。description は設定されている場合のみ含まれ、array と collection は子フィールドを spec に持ちます。

name は返された値をそのまま使う

name はテンプレート作成者が付けた名前で、日本語などの非 ASCII 文字（例: "顧客名"）のこともあります。params のキーには name を変換せずそのまま使ってください（label をキーにしても一致しません）。API から使う前提のテンプレートを作るときは、ASCII のキー（例: customerName）を付け、日本語の表示名は label 側に入れることを推奨します。

キーの扱いは次のとおりです。

  • キーは、テンプレート作成者が指定した値のままです。Re:port Flow がキーを自動で付け直したり、日本語を英字に置き換えたり（翻字）することはありません。
  • 照合は name との完全一致です。別名（エイリアス）で受け付ける仕組みはありません。
  • params に無いキーは、真偽値は既定値、それ以外は空として描画されます。定義に無い余分なキーは無視されます（エラーにはなりません）。

type の値:

型説明例
text文字列（テンプレート側の string / url）"山田太郎"
number数値1000
date日付（ISO 8601）"2024-02-12"
boolean真偽値true
collectionspec で定義されたネストオブジェクト{ "name": "値" }
arrayspec で行構造が定義された配列[{ "item": 1 }]

エラー時​

404 Not Found​

{
  "statusCode": 404,
  "code": "DESIGN_NOT_FOUND",
  "message": "The specified design does not exist.",
  "error": "Not Found",
  "details": [],
  "docsUrl": "https://doc.re-port-flow.com/en/docs/guides/error-codes#design_not_found"
}

Accept-Language: ja を付けると message は 指定したデザインが存在しません、docsUrl は日本語版ページになります。

原因: 返るコードは version クエリの有無で変わります。

versionテンプレート ID が存在しないバージョンが存在しない
指定なしDESIGN_NOT_FOUND（The specified design does not exist.）（最新バージョンを使うため該当なし）
指定ありDESIGN_VERSION_NOT_FOUND（The specified design and version do not exist.）DESIGN_VERSION_NOT_FOUND

別のワークスペースのテンプレート ID も「存在しない」と同じ扱いです。テンプレート ID の形式チェックは行わないため、ID の誤りは 400 ではなく常に 404 になります。詳細は エラーコード一覧 を参照してください。

ユースケース​

動的フォーム生成​

テンプレートのパラメータから入力フォームを動的に生成する例。

function createFieldElement(field, path = field.name) {
  if (['text', 'number', 'date', 'boolean'].includes(field.type)) {
    const input = document.createElement('input');
    input.type = field.type === 'boolean' ? 'checkbox' : field.type;
    input.name = path;
    input.setAttribute('aria-label', field.label);

    if (field.type === 'text' || field.type === 'number') {
      input.placeholder = field.label;
    }

    return input;
  }

  if (field.type === 'array' || field.type === 'collection') {
    const fieldset = document.createElement('fieldset');
    const legend = document.createElement('legend');
    legend.textContent = field.label;
    fieldset.append(legend);

    // 配列は最初の行を生成。必要に応じて同じ方法で行を追加する。
    const childPath = field.type === 'array' ? `${path}[0]` : path;
    for (const child of field.spec ?? []) {
      fieldset.append(
        createFieldElement(child, `${childPath}.${child.name}`),
      );
    }

    return fieldset;
  }

  return document.createDocumentFragment();
}

// ブラウザ側。自社サーバーの中継から取得する
async function createDynamicForm(designId) {
  const res = await fetch(`/api/design-parameters/${encodeURIComponent(designId)}`);
  if (!res.ok) throw new Error(`パラメータの取得に失敗しました: ${res.status}`);
  const schema = await res.json();

  // API由来の値をHTML文字列へ埋め込まず、DOM APIで安全にフィールドを生成
  const form = document.createElement('form');

  for (const field of schema) {
    form.append(createFieldElement(field));
  }

  return form;
}

// 自社サーバー側（appkey はここにだけ置く）。ログイン必須にし、受け付ける designId を許可リストで絞る
const FORM_DESIGN_IDS = new Set(['0eUDdgAjNXrrItA2']);

app.get('/api/design-parameters/:designId', requireLogin, async (req, res) => {
  if (!FORM_DESIGN_IDS.has(req.params.designId)) return res.status(404).end();
  res.json(await getDesignParameters(req.params.designId)); // 上の getDesignParameters
});

name や label はDOMプロパティとして設定するため、HTMLマークアップとして解釈されません。

バリデーション​

function validateObject(params, schema, path, errors) {
  for (const field of schema) {
    if (!Object.prototype.hasOwnProperty.call(params, field.name)) {
      // このAPIは必須属性を返さないため、未指定フィールドは検証対象外
      continue;
    }

    const value = params[field.name];
    const fieldPath = path ? `${path}.${field.name}` : field.name;

    if (field.type === 'text' && typeof value !== 'string') {
      errors.push(`${fieldPath} は文字列である必要があります`);
    } else if (field.type === 'number' && typeof value !== 'number') {
      errors.push(`${fieldPath} は数値である必要があります`);
    } else if (field.type === 'boolean' && typeof value !== 'boolean') {
      errors.push(`${fieldPath} は真偽値である必要があります`);
    } else if (field.type === 'date') {
      if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
        errors.push(`${fieldPath} はISO 8601形式の日付である必要があります`);
      }
    } else if (field.type === 'collection') {
      if (value === null || typeof value !== 'object' || Array.isArray(value)) {
        errors.push(`${fieldPath} はオブジェクトである必要があります`);
      } else {
        validateObject(value, field.spec ?? [], fieldPath, errors);
      }
    } else if (field.type === 'array') {
      if (!Array.isArray(value)) {
        errors.push(`${fieldPath} は配列である必要があります`);
      } else {
        value.forEach((item, index) => {
          const itemPath = `${fieldPath}[${index}]`;
          if (item === null || typeof item !== 'object' || Array.isArray(item)) {
            errors.push(`${itemPath} はオブジェクトである必要があります`);
          } else {
            validateObject(item, field.spec ?? [], itemPath, errors);
          }
        });
      }
    }
  }
}

function validateParams(params, schema) {
  const errors = [];

  if (params === null || typeof params !== 'object' || Array.isArray(params)) {
    return ['params はオブジェクトである必要があります'];
  }

  validateObject(params, schema, '', errors);
  return errors;
}

// 使用例
const schema = await getDesignParameters('0eUDdgAjNXrrItA2');
const params = {
  customerName: '山田太郎',
  invoiceNumber: 'INV-001',
  amount: 10000
};

const errors = validateParams(params, schema);
if (errors.length > 0) {
  console.error('バリデーションエラー:', errors);
}

ベストプラクティス​

1. パラメータスキーマのキャッシュ​

テンプレートのバージョンが変わらない限り、パラメータスキーマは変わりません。キャッシュして再利用することを推奨します。

const schemaCache = new Map();

async function getDesignParametersCached(designId, version) {
  const cacheKey = `${designId}:${version}`;

  if (schemaCache.has(cacheKey)) {
    return schemaCache.get(cacheKey);
  }

  const schema = await getDesignParameters(designId, version);
  schemaCache.set(cacheKey, schema);

  return schema;
}

2. PDF生成前の検証​

パラメータスキーマを事前に取得してバリデーションを行うことで、エラーを早期に検出できます。

async function generatePDFSafely(params) {
  // 1. パラメータスキーマを取得
  const schema = await getDesignParameters(params.designId, params.version);

  // 2. バリデーション
  const errors = validateParams(params.data, schema);
  if (errors.length > 0) {
    throw new Error(`パラメータエラー: ${errors.join(', ')}`);
  }

  // 3. PDF生成
  return await generatePDF(params);
}

よくある質問​

テンプレートのパラメータスキーマはいつ変わりますか​

テンプレートのバージョンが変わらない限りスキーマは変わりません。同じ designId と version の組み合わせであれば、取得したスキーマをキャッシュして再利用できます。

特定バージョンのパラメータを取得するにはどうすればよいですか​

クエリパラメータに version を指定します。省略した場合は最新バージョンのパラメータが返されます。

次のステップ​