日本語の名前だけでカスタムフィールドを作ると、2本目から400で止まる

GoHighLevelのカスタムフィールドを、Claude CodeからAPIで一気に作る場面があります。顧客の属性や案件の項目を、日本語の名前のまま何十本も用意したいときです。

私たちは、デモ用の検証アカウントで29本のフィールドを作ったときに、この作業で最初に止まりました。この記事では、止まった症状と原因、そして外し方をお伝えします。

症状は、1本目だけ通って2本目から400になること

最初の1本は、何事もなく作れます。画面にも日本語の名前で出ます。ところが2本目を同じ要領で作ると、400が返ります。内容は「同じキーのフィールドがすでにある」という衝突です。

名前は別のものを付けています。なのに衝突するので、最初は原因の見当がつきません。3本目以降も、すべて同じ400で止まります。

原因は、キーを自動で作る処理が日本語を落とすこと

GoHighLevelは、フィールドのキーを、渡した名前から自動で作ります。この処理は、ASCII以外の文字を落とします。

名前が英数字を含んでいれば、残った文字がキーになります。名前が日本語だけだと、残る文字がゼロです。その結果、キーが空のスラッグになり、どのフィールドも同じ空のキーになります。

1本目は、空のキーがまだ使われていないので通ります。2本目からは、空のキーがすでに使われているので、衝突します。名前の違いは、キーに反映されていません。

直し方は、fieldKeyを明示すること

作成のリクエストに、fieldKeyを自分で渡します。名前は日本語のままで構いません。表示名と、内部のキーは別のものだからです。

リクエストの形は、次のとおりです。

• name：画面に出る名前。日本語でよい
• fieldKey：内部のキー。英小文字と数字と下線だけで書く
• dataType：項目の型。テキスト、数値、日付など
• model：コンタクト用かオポチュニティ用か

接頭辞は付けない

作られたキーには、コンタクト用なら先頭に contact. が、オポチュニティ用なら opportunity. が、自動で付きます。fieldKeyに最初から付けておくと、接頭辞が二重になります。fieldKeyには、接頭辞より後ろの部分だけを渡します。

表示名は日本語のままでよい

試した例では、名前を「利用開始日」、fieldKeyを start_date としました。画面には「利用開始日」と出て、値を入れるときのキーは contact.start_date になりました。

日本語の名前を英語に直す必要はありません。画面を使う人には日本語が見え、APIを使うClaude Codeには英語のキーが見えます。どちらも困りません。

実測では、29本を衝突ゼロで作れた

私たちは、デモ用の検証アカウントで、fieldKeyを明示してコンタクト用17本とオポチュニティ用12本を、続けて作りました。結果は次のとおりです。

• 衝突は0件
• 作成後に一覧を読み出して、29本の実在を確認
• 画面の名前は、すべて日本語のまま

fieldKeyに共通の接頭辞を付けておくと、あとで便利でした。検証用のフィールドだけを一覧から選び出すとき、キーの先頭で絞り込めるからです。私たちは、検証用に専用の接頭辞を決め、消すときもその接頭辞で探しています。

カスタム値にも、同じ罠がある

カスタム値（Custom Values）も、同じ作りで止まります。名前が日本語だけだと、キーが空のスラッグになり、2本目から「同じキーがすでにある」という400になります。

直し方は、フィールドとは少し違います。カスタム値には、fieldKeyを渡す欄がありません。代わりに、名前の中にASCIIの語を入れます。たとえば「発行元の名称 issuer_name」のように、日本語の名前の後ろに英語の語を添えます。すると、その英語の語がキーになります。

もう一つ、知っておきたいことがあります。すでに作ってしまったカスタム値の名前を、あとから直しても、キーは作り直されません。名前の変更では、壊れたキーは直らないのです。直すには、削除して、英語の語を添えた名前で作り直します。

Claude Codeに作らせるときの指示

Claude Codeに作成を頼むときは、最初の指示に次の3点を入れておくと、止まりません。

• 名前は日本語、fieldKeyは英小文字の下線つなぎで、1本ごとに別の値を決める
• fieldKeyに contact. や opportunity. を付けない
• 作成後に一覧を読み出して、作った本数と一致するか確かめる

3点目は、見落とされやすい点です。作成のリクエストが成功したように見えても、キーが空で作られていることがあるからです。一覧を読み出してキーの欄が空のものがないか見れば、一度で確かめられます。

次に読む

カスタムフィールドを作ったら、次はそこに値を入れる側を整えます。オポチュニティを同じ相手に何件も積み上げる設定は、オポチュニティの重複を解禁する記事にまとめました。