> ## Documentation Index > Fetch the complete documentation index at: https://docs.stockwork.ai/llms.txt > Use this file to discover all available pages before exploring further. # 会社のプロパティ定義を一覧取得 ## OpenAPI ````yaml /openapi/v1.yaml get /v1/companies/properties/ openapi: 3.0.3 info: title: Stockwork Public API version: 1.0.0 description: > Stockwork の取引(Deal)・会社(Account)・コンタクト(Contact)・商談ログ(Meeting Log)・ コンタクト活動(Contact Activity)を外部システムから操作する公開 API。 ## 認証 `Authorization: Bearer sk_` 形式の API キーを送る。 キーは Stockwork 管理画面で発行し、発行時のみ平文が 1 回だけ返却される(以降は再表示不可)。 ## 識別子 Stockwork が発行する `id`(record_id、18 文字)が**全レコードの唯一の identity**。 クライアントはこの `id` を保存し、以降の取得・更新に使用する。 レコード間の参照もすべて record_id で行う。`properties.account_id`(Contact → Account)、 `properties.deal_id`(Meeting Log → Deal)、`properties.contact_id`(Contact Activity → Contact)、`properties.owner_id`(Deal → User)。担当ユーザーの氏名・メールアドレスは `GET /v1/users/` で解決する。 メールアドレスから担当者の record_id を引きたい場合は `GET /v1/users/?email=...` を使う。 ただしこれは**発見用のフィルタであって識別子ではない**。メールアドレスは変更され得るため、 解決した record_id を保存して以降の参照に使うこと(HubSpot / Salesforce と同じ作法)。 ## エラー 全てのエラーは次の封筒で返る。`error.code` は機械可読な enum、`error.message` は人間向けの 説明文(日本語)。バリデーション失敗時のみ `error.fields` にフィールド単位の詳細が入る。 ```json { "error": { "code": "validation_error", "message": "リクエストの検証に失敗しました。", "fields": [ {"name": "properties.name", "code": "required", "message": "この項目は必須です。"} ] } } ``` ## ロール API キー発行時に付与する **role** で操作範囲を制限する。Stockwork 既存の組織ロールと 同じ概念を流用(リソース単位の細かいスコープ分割は提供しない): - `read` — 読み取りのみ - `analyst` — 読み取り + 分析(本 API では read 相当) - `write` — 読み取り + 書き込み - `admin` — 全権限 ### エンドポイントと必要 role の対応 | メソッド + パス | 必要 role | |---|---| | `GET /v1/deals/` / `/v1/deals/{record_id}/` / `/v1/deals/properties/` | `read` | | `POST /v1/deals/search/` | `read` | | `POST /v1/deals/` / `PATCH /v1/deals/{record_id}/` | `write` | | `GET /v1/companies/` / `/v1/companies/{record_id}/` / `/v1/companies/properties/` | `read` | | `POST /v1/companies/search/` | `read` | | `POST /v1/companies/` / `PATCH /v1/companies/{record_id}/` | `write` | | `GET /v1/contacts/` / `/v1/contacts/{record_id}/` / `/v1/contacts/properties/` | `read` | | `POST /v1/contacts/search/` | `read` | | `POST /v1/contacts/` / `PATCH /v1/contacts/{record_id}/` | `write` | | `GET /v1/meeting-logs/` / `/v1/meeting-logs/{record_id}/` / `/v1/meeting-logs/properties/` | `read` | | `POST /v1/meeting-logs/search/` | `read` | | `POST /v1/meeting-logs/` / `PATCH /v1/meeting-logs/{record_id}/` | `write` | | `GET /v1/contact-activities/` / `/v1/contact-activities/{record_id}/` / `/v1/contact-activities/properties/` | `read` | | `POST /v1/contact-activities/search/` | `read` | | `POST /v1/contact-activities/` / `PATCH /v1/contact-activities/{record_id}/` | `write` | | `GET /v1/users/` / `/v1/users/{record_id}/` | `read` | 上位 role は下位 role を内包する(`write` キーは `read` 操作も可)。 ## 検索(プロパティ値による絞り込み) GUI 一覧画面と同等の表現力でレコードを検索できる `POST /v1//search/` を提供する。クエリ文字列ではなく POST body にフィルタを含めるため、WAF / 中間機器の URL 長制限の影響を受けない。 - **2 階層構造**: グループ間 OR / グループ内 AND(GUI と同じ。最大 10 グループ) - **対象フィールド**: コアフィールド(`name` / `amount` / `stage` 等)+ カスタム プロパティ(`PropertyDefinition.api_name` で指定) - **operator**: text / number / date / select / boolean のそれぞれに必要な集合を提供 (詳細は `FilterOperator` schema) - **select 値の解決**: ラベルではなく**内部値の完全一致**のみ(fuzzy match なし) - **`is_null` / `is_empty` の意味論**: 該当プロパティの値レコードが存在しない場合も 含める(GUI と同じ) - **ページネーション**: 検索はページ番号型(`page` / `page_size`)。任意の複合ソート (`sort_by` / `sort_order`)を許すため、カーソル型とは両立しない。 `page * page_size` は **10,000 を超えられない**(超過時は `400`)。 全件走査には `GET /v1//?updated_after=...` のカーソルページネーションを使う。 ## `updated_at` と差分取得 `updated_at` は**レコードの値が最後に変わった日時**で、行への書き込み日時ではない。 コアフィールド・カスタムプロパティ・アクティビティ件数などの集計値のいずれかが実際に 変わったときに進む。商談ログやメールを記録した場合も、それが集計値を動かすため進む。 同じ値での再保存（SFA 同期が同一値を書き戻した場合を含む）、他レコードとの紐付け変更、 日次バッチが再計算する予測値（受注確率・ヘルススコア）では進まない。 `updated_after` を差分同期のウォーターマークに使う場合、活動の記録でも親レコードが 再取得対象になる点に注意する。 ## レート制限 - API キー単位: `1000 / 分` - 組織合算: `5000 / 分` 全レスポンス(成功・失敗を問わず)に次のヘッダを付与する。クライアントは残量を見て 事前に減速できる。 - `X-RateLimit-Limit` — 現在の窓の上限回数(API キー単位) - `X-RateLimit-Remaining` — 現在の窓の残り回数 - `X-RateLimit-Reset` — 窓がリセットされる Unix 時刻(秒) 超過時は `429 Too Many Requests` + `Retry-After` ヘッダ。 contact: name: Stockwork Public API Support servers: - url: https://api.strixai.jp description: Production - url: https://api-dev.strixai.jp description: Development(検証環境) security: - BearerApiKey: [] tags: - name: Deals description: 取引リソース - name: Companies description: 会社(Account)リソース - name: Contacts description: コンタクトリソース - name: Meeting Logs description: 商談ログ(Deal 配下の活動)リソース - name: Contact Activities description: コンタクト活動(Contact 配下の活動)リソース - name: Users description: Stockwork ユーザー(担当者)リソース。read-only paths: /v1/companies/properties/: get: tags: - Companies summary: 会社のプロパティ定義を一覧取得 responses: '200': description: 取得成功 content: application/json: schema: $ref: '#/components/schemas/PropertyDefinitionListResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' security: - BearerApiKey: [] components: schemas: PropertyDefinitionListResponse: type: object properties: results: type: array items: $ref: '#/components/schemas/PropertyDefinition' required: - results PropertyDefinition: type: object description: プロパティ定義 properties: api_name: type: string description: | プロパティの API キー名(`properties` マップのキー)。 - **コアフィールド**: `name` / `amount` / `stage` / `owner_id` 等の固定名。 - **カスタムプロパティ**: 組織の管理者が作成時に指定したスラッグ (`^[a-z][a-z0-9_]{2,63}$`)。未指定の場合は 8 文字のランダム英数字が採番され、 その値は**環境ごとに異なる**。連携用のプロパティにはスラッグを指定すること。 example: external_deal_id display_name: type: string description: UI 表示名 property_type: type: string enum: - text - number - boolean - date - datetime - select is_core: type: boolean description: コアフィールド(モデル本体の直接カラム)か、EAV カスタムプロパティか is_required_on_create: type: boolean description: | 作成時に必須か(true なら POST 時に `properties.` が必須)。 **`is_core: true` のプロパティだけが true になり得る。** カスタムプロパティに必須指定の仕組みはなく、常に false。 options: type: array items: $ref: '#/components/schemas/PropertyOption' description: SELECT 型のときのみ存在 required: - api_name - display_name - property_type - is_core - is_required_on_create Error: type: object description: | 全エラーレスポンスの共通封筒。 properties: error: type: object properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: 人間向けの説明文(日本語) fields: type: array description: | `code` が `validation_error` のときのみ存在。フィールド単位の詳細。 items: $ref: '#/components/schemas/FieldError' required: - code - message required: - error example: error: code: validation_error message: リクエストの検証に失敗しました。 fields: - name: properties.name code: required message: この項目は必須です。 PropertyOption: type: object description: SELECT 型プロパティの選択肢 properties: value: type: string label: type: string required: - value - label ErrorCode: type: string description: | 機械可読なエラー種別。HTTP ステータスと 1 対 1 ではない(`400` は `validation_error` と `invalid_request` の両方を取り得る)ため、 クライアントは**このコードで分岐する**こと。 今後の追加に備え、未知のコードは汎用エラーとして扱うこと。 enum: - invalid_request - validation_error - unauthorized - forbidden - not_found - rate_limited - internal_error FieldError: type: object description: バリデーション失敗時のフィールド単位の詳細 properties: name: type: string description: 対象フィールドのパス。`properties` 配下は `properties.` で表す example: properties.name code: type: string description: > フィールド単位のエラー種別。 `required` / `invalid_type` / `invalid_value` / `not_found` / `unknown_property` / `too_long` / `out_of_range` のいずれか。 example: required message: type: string description: 人間向けの説明文(日本語) example: この項目は必須です。 required: - name - code - message responses: Unauthorized: description: 認証失敗(キー欠落・不正・失効・IP 拒否) content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: スコープ不足 content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: レート制限超過(`Retry-After` ヘッダあり) headers: Retry-After: schema: type: integer description: 次のリクエストまでの待機秒数 content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerApiKey: type: http scheme: bearer bearerFormat: sk_* description: | Stockwork が発行する API キー(`sk_` プレフィックス、base62 ランダム ≥ 40 文字)。 キーには 1 つの role(`read` / `analyst` / `write` / `admin`)が紐付き、 各エンドポイントの必要 role 以上であることが要求される(対応表は info.description 参照)。 ````