メインコンテンツへスキップ

レコード作成 API

Canbus. チーム
  • 更新

レコード作成 API を使用すると、アプリに新しいレコードを追加できます。

  • エンドポイント URL - https://<tenant-id>.canbus.com/api/records
  • メソッド - POST

 

リクエストヘッダーの形式

以下のリクエストヘッダーが必要です。

  • Content-Type: application/json

 

リクエストボディの形式

レコード作成 API のリクエストボディ形式は次のとおりです。

{
    "tenant_id": <tenant-id>,
    "app_id": <app-id>,
    "api_key": <api-key>,
    "api_secret": <api-secret>,
    "add": [
        {
            "System_Create_User": <user-login-id>,
            <form-item-id>: <form-item-value>,
            ...
        },
        ...
    ]
}

淡色部分には、Canbus. API の認証情報を挿入します。認証情報の送信方法については、認証を参照してください。

add はオブジェクト配列です。作成するレコードを表す 1 個以上のオブジェクトを要素として指定します。各要素には、必須の System_Create_User と、任意のプロパティを指定します。

System_Create_User は、レコードの作成者として記録するユーザーのログイン ID を表す文字列です。その他のプロパティは、フォーム項目の ID を表すプロパティ名と、作成するレコード上の項目値をフォーム項目の型に応じて指定します。

実際の add 配列のサンプルをいくつか例示します。

"add": [
    {
        "System_Create_User": "admin"
    }
]

これは、レコード作成 API のもっとも単純な形式を表しています。レコードの作成者として admin を指定し、他のフォーム項目には何も値を入力せずに空のレコードを 1 件作成します。

空のレコードを同時に 2 件作成するには、次のようにします。

"add": [
    {
        "System_Create_User": "admin"
    }, {
        "System_Create_User": "canbus"
    }
]

1 件目のレコードはユーザー admin が、2 件目のレコードはユーザー canbus が作成者になります。どちらのレコードも、フォーム上のすべての項目が未入力になります。

レコード作成時にフォーム上の文字列項目 Text と数値項目 Number の 2 項目に値を入力するには、次のようにします。

"add": [
    {
        "System_Create_User": "admin",
        "Text": "これは文字列項目 Text に入力される値です",
        "Number": 1000
    }
]

プロパティ名と値は、レコード作成時に値を入力したい項目の分だけ、自由に指定できます。指定しなかった項目は未入力扱いになります。

文字列、数値、日付と時刻など、フォーム項目の型ごとに、値を指定する際の形式が異なります。次のセクションを確認してください。

 

項目値の形式

レコード作成 API で指定可能な各フォーム項目の値は、項目の型に応じて以下の形式になります。

  • 数値 - 任意の数値
  • 文字列 - 任意の文字列
  • リッチテキスト - 任意の文字列。HTML の <b>, <u>, <i> タグを使用して装飾することが可能
  • 日付 - "YYYY/MM/DD" 形式の文字列
  • 時刻 - "HH:MM" 形式の文字列。"00:00" から "23:59" まで 1 分単位で指定可能
  • 日付と時刻 - "YYYY/MM/DD HH:MM" 形式の文字列。24:00 以降の入力が可能な設定になっている項目の場合、時刻部分は "48:00" まで指定可能
  • 添付ファイル - ファイル名と Base64 エンコードされたコンテンツの配列
  • ラジオボタン - 選択する値を 1 から始まる順序で表す数値、または選択肢のラベルを表す文字列
  • チェックボックス - 選択する値を 1 から始まる順序で表す数値の配列、または選択肢のラベルを表す文字列の配列
  • プルダウン - 選択する値を 1 から始まる順序で表す数値、または選択肢のラベルを表す文字列
  • ユーザー選択 - 選択されたユーザーのログイン ID
  • 表組み - 表組み内の各行を JSON 文字列として表した JSON 配列
  • アプリ連携 - キー項目の値
  • 組織選択 - 選択する組織名を、最上位の組織から "/" 区切りで連結した文字列
  • 作成者 - レコードの作成者とするユーザーのログイン ID

ラベル、計算式、レコード参照、グリッド参照、罫線、ボタン、参照と、作成者を除くすべての自動入力項目の ID をレコード作成 API で指定することはできません。

 

添付ファイルを送信する方法

レコード作成 API で添付ファイル項目の値を送信するには、送信するファイル名と Base64 エンコードされたファイルコンテンツを含む JSON 配列を作成します。

<attachment-form-item-id> : [
    {
        "name": <filename>,
        "data": <file-content-base64-encoded>
    },
    ...
],
...

値全体は、0 個以上の JSON オブジェクトの配列です。配列の各要素がそれぞれ添付するファイル 1 つに対応します。

配列内のオブジェクトは、ファイル名を表す name と、ファイルのコンテンツを表す data を持ちます。data の値は、Base64 エンコードされたファイルコンテンツです。

例えば、添付ファイル項目 Attachments に 2 個のファイルを添付する場合、以下のようになります。

"Attachments": [
    {
        "name": "乙稟議_2024-04-19.docx",
        "data": "UEsDBBQABgAIAAAAIQDfpNJsWgEAACAFAAATAA ... APQsAAAAAA=="
    }, {
        "name": "20240405-1354_見積書.pdf",
        "data": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjMgMCBvYmoKP ... kxCiUlRU9GCg=="
    }
],

Canbus. API の制限事項により、1 回に送信可能なリクエストサイズには上限があります。これはウェブ画面から Canbus. に添付可能な 1 ファイルの最大サイズよりも小さいため、ウェブ画面から添付可能なファイルが API では送信できない場合があります。現在の Canbus. API では、大きなファイルを複数のリクエストに分割して送信する方法はサポートされていません。

 

表組みを送信する方法

レコード作成 API で表組み項目の値を送信するには、入れ子になった形式でフォーム項目の ID と値を指定する JSON 配列を作成します。

<table-form-item-id>: [
    {
        <form-item-id>: <form-item-value>,
        ...
    },
    ...
],
...

値全体は、0 個以上の JSON オブジェクトの配列です。配列の各要素がそれぞれ表組みの各行に対応します。

例えば、文字列項目 Text, 数値項目 Number, 日付項目 Date を含む表組み項目 Table に 2 行追加する場合、以下のようになります。

"Table": [
    {
        "Text": "1 行目の文字列",
        "Number": 1234567890,
        "Date": "2024/04/19"
    }, {
        "Text": "2 行目の文字列",
        "Number": 1200
    }
],

上記の例では、表組みの 2 行目には Date 項目を指定していません。この場合、2 行目の Date の値は未入力になります。

 

レスポンスボディの形式

レコード作成 API のレスポンスボディ形式は次のとおりです。

{
    "authen": "OK",
    "results": [
        {
            "result": <result-code>,
            "id": <record-object-id>,
        },
        ...
    ]
}

results は作成結果を表すオブジェクト配列です。リクエストボディの add 配列の要素数と results の要素数は同じになり、互いの各要素が 1 対 1 で対応します。

レコード作成 API では、作成しようとしたレコードごとに以下の result コードが返されます。

  • 0 - 作成に成功
  • 32 - System_Create_User またはユーザー選択項目に指定されたログイン ID のユーザーが存在しない、または有効ではない
  • 99 - 組織選択項目に指定された組織が存在しない
  • 7001 - 数値項目に指定された値が最小値の制限を満たしていない
  • 7002 - 数値項目に指定された値が最大値の制限を満たしていない
  • 7003 - 数値で値を指定する必要がある項目に文字列の値を指定した
  • 7004 - 数値で値を指定する必要がある項目に対して指定範囲外の値を指定した
  • 7012 - 重複禁止項目に重複する値を指定した
  • 7013 - 入力必須項目に値が指定されていない
  • 7014 - 文字列項目に指定された値が入力可能文字の制限を満たしていない
  • 7018 - 数値項目に指定された値がシステム上の上限値 (999,999,999,999,999) を超えた
  • 7020 - 日付と時刻項目に指定された値が正しい形式でない
  • 7021 - 日付項目に指定された値が正しい形式でない
  • 7022 - 時刻項目に指定された値が正しい形式でない
  • 7042 - その他のエラー。例えば、チェックボックスや表組み項目に指定された値が正しい配列形式になっていない

result コードが 0 以外の値になっている場合、レコードは作成されていません。

複数のレコードを一度に作成しようとした場合、作成に成功したレコードと、何らかのエラーによって作成に失敗したレコードが混在することがあります。results の要素ごとに、result コードを確認してください。

各要素の id は、作成されたレコードの永続的な ID です。この ID を使用して、レコード編集 API やレコード削除 API を呼び出すことができます。レコードが作成されなかった場合、id の値は空の文字列になります。

 

関連情報

関連記事