Design Parameters

The GET /file/design/parameter/{designId} endpoint retrieves the parameter structure for a specified design ID. You can check the schema for parameters needed for PDF or thumbnail generation.

Endpoint Information

URL: https://api.re-port-flow.com/v1/file/design/parameter/{designId}
Method: GET
Authentication: appkey header required

Usage Examples

cURL

# Get latest version parameters
curl -X GET https://api.re-port-flow.com/v1/file/design/parameter/550e8400-e29b-41d4-a716-446655440000 \
  -H "appkey: your-application-key"

# Get specific version parameters
curl -X GET "https://api.re-port-flow.com/v1/file/design/parameter/550e8400-e29b-41d4-a716-446655440000?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;
}

// Usage example
const schema = await getDesignParameters('550e8400-...');
console.log('Parameter schema:', 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()

# Usage example
schema = get_design_parameters('550e8400-...')
print('Parameter schema:', schema)

Parameters

Parameter	Type	Required	Description
`designId`	string (UUID)	✓	Design ID (path parameter)
`version`	integer	-	Version number (query parameter, defaults to latest)

Response

Success (200 OK)

[
  { "name": "customerName", "type": "text", "label": "Customer name" },
  { "name": "invoiceNumber", "type": "text", "label": "Invoice number" },
  { "name": "amount", "type": "number", "label": "Amount" },
  {
    "name": "items",
    "type": "array",
    "label": "Items",
    "spec": [
      { "name": "name", "type": "text", "label": "Item" },
      { "name": "price", "type": "number", "label": "Price" },
      { "name": "quantity", "type": "number", "label": "Quantity" }
    ]
  },
  { "name": "issueDate", "type": "date", "label": "Issue date" }
]

The response is an array of parameter definitions that can be used to build an input form. name is the key to send in PDF generation params, and label is the display name. description is included only when configured. array and collection fields contain child definitions in spec.

type values:

Type	Description	Example
`text`	String (the design's `string` and `url` types)	`"John Doe"`
`number`	Number	`1000`
`date`	Date (ISO 8601)	`"2024-02-12"`
`boolean`	Boolean	`true`
`collection`	Nested object defined by `spec`	`{ "name": "value" }`
`array`	Array whose row structure is defined by `spec`	`[{ "item": 1 }]`

Errors

404 Not Found

{
  "statusCode": 404,
  "message": "指定したデザインが存在しません",
  "error": "Not Found"
}

(The server returns the message in Japanese; it translates to "The specified design does not exist". When a specific version is missing, the message is 指定したバージョン（X）が存在しません ("The specified version X does not exist").)

Cause: Specified design ID or version does not exist

Use Cases

Dynamic Form Generation

Generate input forms dynamically from design parameters.

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);

    // Create the first array row. Add more rows with the same approach as needed.
    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) {
  // Get parameter schema
  const schema = await getDesignParameters(designId);

  // Build fields with DOM APIs instead of interpolating API values into HTML
  const form = document.createElement('form');

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

  return form;
}

Because name and label are assigned as DOM properties, the browser does not interpret them as HTML markup.

Validation

function validateObject(params, schema, path, errors) {
  for (const field of schema) {
    if (!Object.prototype.hasOwnProperty.call(params, field.name)) {
      // This endpoint does not return required metadata, so omitted fields are skipped.
      continue;
    }

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

    if (field.type === 'text' && typeof value !== 'string') {
      errors.push(`${fieldPath} must be a string`);
    } else if (field.type === 'number' && typeof value !== 'number') {
      errors.push(`${fieldPath} must be a number`);
    } else if (field.type === 'boolean' && typeof value !== 'boolean') {
      errors.push(`${fieldPath} must be a boolean`);
    } else if (field.type === 'date') {
      if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
        errors.push(`${fieldPath} must be in ISO 8601 date format`);
      }
    } else if (field.type === 'collection') {
      if (value === null || typeof value !== 'object' || Array.isArray(value)) {
        errors.push(`${fieldPath} must be an object`);
      } else {
        validateObject(value, field.spec ?? [], fieldPath, errors);
      }
    } else if (field.type === 'array') {
      if (!Array.isArray(value)) {
        errors.push(`${fieldPath} must be an array`);
      } else {
        value.forEach((item, index) => {
          const itemPath = `${fieldPath}[${index}]`;
          if (item === null || typeof item !== 'object' || Array.isArray(item)) {
            errors.push(`${itemPath} must be an object`);
          } else {
            validateObject(item, field.spec ?? [], itemPath, errors);
          }
        });
      }
    }
  }
}

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

  if (params === null || typeof params !== 'object' || Array.isArray(params)) {
    return ['params must be an object'];
  }

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

// Usage example
const schema = await getDesignParameters('550e8400-...');
const params = {
  customerName: 'John Doe',
  invoiceNumber: 'INV-001',
  amount: 10000
};

const errors = validateParams(params, schema);
if (errors.length > 0) {
  console.error('Validation errors:', errors);
}

Best Practices

1. Cache Parameter Schema

Parameter schemas don't change unless the design version changes. Cache and reuse them.

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. Validate Before PDF Generation

Get parameter schema in advance and validate to detect errors early.

async function generatePDFSafely(params) {
  // 1. Get parameter schema
  const schema = await getDesignParameters(params.designId, params.version);

  // 2. Validate
  const errors = validateParams(params.data, schema);
  if (errors.length > 0) {
    throw new Error(`Parameter errors: ${errors.join(', ')}`);
  }

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

FAQ

When does a design's parameter schema change?

The schema does not change unless the design's version changes. For the same designId and version pair you can cache the schema you fetched and reuse it.

How do I fetch the parameters for a specific version?

Pass version as a query parameter. If you omit it, the parameters for the latest version are returned.

Next Steps

Sync Single PDF Generation - Generate PDF using parameters
Error Handling - Handle validation errors

Endpoint Information​

Usage Examples​

cURL​

JavaScript​

Python​

Parameters​

Response​

Success (200 OK)​

Errors​

404 Not Found​

Use Cases​

Dynamic Form Generation​

Validation​

Best Practices​

1. Cache Parameter Schema​

2. Validate Before PDF Generation​

FAQ​

When does a design's parameter schema change?​

How do I fetch the parameters for a specific version?​

Next Steps​