openapi: 3.0.3
info:
  title: RISK EYES V2 取引先管理API
  description: |
    RISK EYES V2 取引先管理API 仕様書

    取引先の一覧取得、作成、詳細操作(取得・更新・削除)、法人番号検索による作成が可能です。

    主な機能：
    - 取引先の一覧の取得(検索・ページング対応)
    - 取引先の新規作成
    - 取引先詳細の取得・更新・削除
    - 法人番号による企業情報検索・取引先作成
    - 承認ステータスの取得・更新
    - カスタムフィールドスキーマの取得

    注意事項：
    - /api/v2/token で取得したトークンを Authorization ヘッダーに設定してください。
    - 並行でリクエストを送信せず、1件ずつリクエストを送信してください。

    変更履歴：
    - 1.0.2: approve エンドポイント、custom-fields/schema エンドポイントの追加、取引先一覧取得に法人番号パラメータを追加
    - 1.0.1: custom_fields フィールドを追加
    - 1.0.0: 初版公開

  version: 1.0.2

servers:
  - url: https://www.riskeyes.jp

security:
  - bearerAuth: []

paths:
  /api/v2/customer:
    get:
      tags:
        - Customer
      summary: 取引先一覧取得
      description: |
        取引先一覧を取得します。
        検索キーワードによるフィルタリングとページング機能を提供します。
      operationId: getCustomerList
      parameters:
        - name: search_keyword
          in: query
          description: 会社名、代表者名、または住所のどれかでの部分一致検索
          required: false
          schema:
            type: string
            example: 'ソーシャルワイヤー'
        - name: customer_unique_id
          in: query
          description: 貴社取引先IDの完全一致検索
          required: false
          schema:
            type: string
            example: 'CUST001'
        - name: corporate_number
          in: query
          description: 法人番号の完全一致検索
          required: false
          schema:
            type: integer
            example: 3011101058626
        - name: page
          in: query
          description: ページ番号
          required: false
          schema:
            type: integer
            example: 1
            default: 1
        - name: page_size
          in: query
          description: ページサイズ
          required: false
          schema:
            type: integer
            example: 10
            default: 30
      responses:
        '200':
          description: 取引先一覧取得成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v2/customer/create:
    post:
      tags:
        - Customer
      summary: 取引先新規作成
      description: |
        新しい取引先を作成します。
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreateRequest'
      responses:
        '201':
          description: 取引先作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v2/customer/detail/{id}:
    get:
      tags:
        - Customer
      summary: 取引先詳細取得
      description: |
        指定されたIDの取引先詳細情報を取得します。
        調査対象も含めて返却します。
      operationId: getCustomerDetail
      parameters:
        - name: id
          in: path
          description: 取引先ID
          schema:
            type: integer
            example: 1
          required: true
      responses:
        '200':
          description: 取引先詳細取得成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - Customer
      summary: 取引先情報部分更新
      description: |
        指定されたIDの取引先情報を部分的に更新します。
        指定されたフィールドのみが更新され、未指定のフィールドは変更されません。
        ※調査対象を更新する場合は、取引先に紐づいた全ての調査対象を上書きするため、ご注意ください。
      operationId: partialUpdateCustomer
      parameters:
        - name: id
          in: path
          description: 取引先ID
          required: true
          schema:
            type: integer
            example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                corporate_number:
                  type: integer
                  nullable: true
                  description: 法人番号（13桁）
                  example: 3011101058626
                company_name:
                  type: string
                  description: 会社名
                  example: 'ソーシャルワイヤー'
                customer_unique_id:
                  type: string
                  nullable: true
                  description: 貴社取引先ID
                  example: 'CUST001'
                representative_name:
                  type: string
                  nullable: true
                  description: 代表者名
                  example: '矢田峰之'
                address:
                  type: string
                  nullable: true
                  description: 住所
                  example: '東京都港区...'
                remarks:
                  type: string
                  nullable: true
                  description: 備考
                  example: '重要取引先'
                risk_alert_enabled:
                  type: boolean
                  description: リスクアラート有効フラグ
                  example: true
                custom_fields:
                  type: object
                  nullable: true
                  description: カスタムフィールド（事前に設定したキー・型の形式でデータを格納可能）
                  additionalProperties: true
                  example:
                    department: '営業部'
                    priority: 'high'
                research_subjects:
                  type: array
                  description: 調査対象リスト
                  items:
                    $ref: '#/components/schemas/ResearchSubject'
      responses:
        '200':
          description: 取引先部分更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - Customer
      summary: 取引先情報更新
      description: |
        指定されたIDの取引先情報を全て更新(上書き)します。
        調査対象も同時に上書きされます。
      operationId: updateCustomer
      parameters:
        - name: id
          in: path
          description: 取引先ID
          required: true
          schema:
            type: integer
            example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerUpdateRequest'
      responses:
        '200':
          description: 取引先更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Customer
      summary: 取引先削除
      description: |
        指定されたIDの取引先を削除します。
        関連する調査対象も削除されます。
      operationId: deleteCustomer
      parameters:
        - name: id
          in: path
          description: 取引先ID
          required: true
          schema:
            type: integer
            example: 1
      responses:
        '204':
          description: 取引先削除成功
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v2/customer/create/search:
    post:
      tags:
        - Customer
      summary: 法人番号検索による取引先作成
      description: |
        法人番号を使用してRISK EYES企業情報を検索し、その結果を基に取引先を作成します。
        企業データベースから取得した情報で取引先を自動作成します。
      operationId: searchAndCreateCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerSearchCreateRequest'
      responses:
        '201':
          description: 企業情報検索・取引先作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: 企業情報が見つからない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: false
                error: '企業情報が見つかりませんでした。'

  /api/v2/customer/approve/{id}:
    get:
      tags:
        - Customer
      summary: 承認状態取得
      description: |
        指定されたIDの取引先の承認状態を取得します。
        承認レコードが存在しない場合は、confirm_status・approval_status ともに PENDING を返します。
      operationId: getCustomerApproval
      parameters:
        - name: id
          in: path
          description: 取引先ID
          required: true
          schema:
            type: integer
            example: 1
      responses:
        '200':
          description: 承認状態取得成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerApproveResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - Customer
      summary: 承認ステータス更新
      description: |
        指定されたIDの取引先の承認ステータスを更新します。
        confirm_status、approval_status、remarks のいずれか1つ以上を指定してください。
        本エンドポイントには確認者権限または承認者権限が必要です。
      operationId: updateCustomerApproval
      parameters:
        - name: id
          in: path
          description: 取引先ID
          required: true
          schema:
            type: integer
            example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerApproveRequest'
      responses:
        '200':
          description: 承認ステータス更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerApproveResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 権限エラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v2/customer/custom-fields/schema:
    get:
      tags:
        - Customer
      summary: カスタムフィールドスキーマ取得
      description: |
        カスタムフィールドのJSON Schemaを取得します。
        事前に設定されたカスタムフィールドの定義（キー名、型、選択肢など）をJSON Schema形式で返します。
      operationId: getCustomFieldSchema
      responses:
        '200':
          description: カスタムフィールドスキーマ取得成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldSchemaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: /api/v2/token で取得したトークンを設定してください。

  schemas:
    CustomerSummary:
      type: object
      description: 取引先一覧用の詳細情報
      properties:
        id:
          type: integer
          description: id
          example: 1
        corporate_number:
          type: integer
          nullable: true
          description: 法人番号
          example: 3011101058626
        company_name:
          type: string
          description: 会社名
          example: 'ソーシャルワイヤー株式会社'
        customer_unique_id:
          type: string
          nullable: true
          description: 貴社取引先ID
        representative_name:
          type: string
          nullable: true
          description: 代表者名
          example: '矢田峰之'
        address:
          type: string
          nullable: true
          description: 住所
          example: '東京都港区新橋１丁目１－１３アーバンネット内幸町ビル３階'
        remarks:
          type: string
          nullable: true
          description: 備考
        risk_alert_enabled:
          type: boolean
          description: リスクアラート有効フラグ
          example: true
        custom_fields:
          type: object
          nullable: true
          description: カスタムフィールド（事前に設定したキー・型の形式でデータを格納可能）
          additionalProperties: true
          example:
            department: '営業部'
            priority: 'high'
        research_subjects:
          type: array
          description: 調査対象配列
          items:
            $ref: '#/components/schemas/ResearchSubject'
        created_at:
          type: string
          description: 作成日時
          example: '2025-07-18T13:48:37'
        updated_at:
          type: string
          description: 更新日時
          example: '2025-07-22T10:52:28'

    ResearchSubject:
      type: object
      description: 調査対象(会社名、代表者名以外の調査対象を入力してください)
      properties:
        word:
          type: string
          description: 調査対象ワード
          example: '藤原直美'
        memo:
          type: string
          nullable: true
          description: メモ
          example: '取締役ＣＯＯ'
        word_type:
          type: integer
          description: |
            ワード種別
            0: 調査対象
          example: 0
        word_en:
          type: string
          nullable: true
          description: 英字名
          example: 'Naomi Fujiwara'
        word_dj:
          type: string
          nullable: true
          description: DJ現地語名
          example: null

    CustomerDetail:
      type: object
      description: 取引先詳細情報
      properties:
        id:
          type: integer
          description: 取引先ID
          example: 1
        corporate_number:
          type: integer
          description: 法人番号
          example: 3011101058626
        company_name:
          type: string
          description: 会社名
          example: 'ソーシャルワイヤー株式会社'
        customer_unique_id:
          type: string
          description: 貴社取引先ID
          example: 'CUST001'
        representative_name:
          type: string
          description: 代表者名
          example: '矢田峰之'
        address:
          type: string
          description: 住所
          example: '東京都港区...'
        remarks:
          type: string
          description: 備考
          example: '重要取引先'
        risk_alert_enabled:
          type: boolean
          description: リスクアラート有効フラグ
          example: true
        custom_fields:
          type: object
          nullable: true
          description: カスタムフィールド（事前に設定したキー・型の形式でデータを格納可能）
          additionalProperties: true
          example:
            department: '営業部'
            priority: 'high'
            contract_date: '2024-01-15'
        research_subjects:
          type: array
          description: 調査対象配列
          items:
            $ref: '#/components/schemas/ResearchSubject'
        created_at:
          type: string
          format: date-time
          description: 作成日時
          example: '2024-01-01T10:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: 更新日時
          example: '2024-01-01T10:00:00Z'

    CustomerListResponse:
      type: object
      description: 取引先一覧レスポンス（ページング対応）
      properties:
        count:
          type: integer
          description: 総件数
          example: 1
        next:
          type: string
          nullable: true
          description: 次のページのURL
        previous:
          type: string
          nullable: true
          description: 前のページのURL
        results:
          type: array
          description: 取引先データ配列
          items:
            $ref: '#/components/schemas/CustomerSummary'

    CustomerCreateRequest:
      type: object
      description: |
        取引先作成リクエスト
      properties:
        corporate_number:
          type: integer
          nullable: true
          description: |
            法人番号（13桁の半角数字）
          pattern: "^\\d{13}$"
          example: 3011101058626
        company_name:
          type: string
          nullable: false
          description: |
            会社名
            法人番号が指定されていない場合に使用されます。
          example: 'ソーシャルワイヤー株式会社'
        customer_unique_id:
          type: string
          nullable: true
          description: 貴社取引先ID
          example: 'CUST001'
        representative_name:
          type: string
          nullable: true
          description: 代表者名
          example: '矢田峰之'
        address:
          type: string
          nullable: true
          description: 住所
          example: '東京都港区...'
        remarks:
          type: string
          nullable: true
          description: 備考
          example: '重要取引先'
        risk_alert_enabled:
          type: boolean
          description: リスクアラート有効フラグ
          example: false
        custom_fields:
          type: object
          nullable: true
          description: カスタムフィールド（事前に設定したキー・型の形式でデータを格納可能）
          additionalProperties: true
          example:
            department: '営業部'
            priority: 'high'
        research_subjects:
          type: array
          description: 調査対象リスト
          items:
            $ref: '#/components/schemas/ResearchSubject'

    CustomerUpdateRequest:
      type: object
      description: 取引先更新リクエスト
      required:
        - corporate_number
        - company_name
        - customer_unique_id
        - representative_name
        - address
        - remarks
        - research_subjects
      properties:
        corporate_number:
          type: integer
          nullable: true
          description: 法人番号（13桁）
          pattern: '^[0-9]{13}$'
          example: 3011101058626
        company_name:
          type: string
          nullable: false
          description: 会社名
          example: 'ソーシャルワイヤー株式会社'
        customer_unique_id:
          type: string
          nullable: true
          description: 貴社取引先ID
          example: 'CUST001'
        representative_name:
          type: string
          nullable: true
          description: 代表者名
          example: '矢田峰之'
        address:
          type: string
          nullable: true
          description: 住所
          example: '東京都港区...'
        remarks:
          type: string
          nullable: true
          description: 備考
          example: '重要取引先'
        risk_alert_enabled:
          type: boolean
          description: リスクアラート有効フラグ（未指定の場合は既存の値を維持）
          example: true
        custom_fields:
          type: object
          nullable: true
          description: カスタムフィールド（事前に設定したキー・型の形式でデータを格納可能）
          additionalProperties: true
          example:
            department: '営業部'
            priority: 'high'
        research_subjects:
          type: array
          nullable: false
          description: 調査対象リスト
          items:
            $ref: '#/components/schemas/ResearchSubject'

    CustomerSearchCreateRequest:
      type: object
      description: 法人番号検索・取引先作成リクエスト
      required:
        - corporate_number
      properties:
        corporate_number:
          type: integer
          description: 法人番号（13桁）
          pattern: '^[0-9]{13}$'
          example: 3011101058626
        customer_unique_id:
          type: string
          description: 貴社取引先ID
          example: 'CUST001'
        remarks:
          type: string
          description: 備考
          example: '重要取引先'
        risk_alert_enabled:
          type: boolean
          description: リスクアラート有効フラグ
          example: false

    CustomerApproveResponse:
      type: object
      description: 承認状態レスポンス
      properties:
        confirm_status:
          type: string
          description: |
            確認ステータス
            - PENDING: 未確認
            - CONFIRMED: 確認済
            - NEEDS_CONFIRMATION: 要確認
          enum:
            - PENDING
            - CONFIRMED
            - NEEDS_CONFIRMATION
          example: 'PENDING'
        approval_status:
          type: string
          description: |
            承認ステータス
            - PENDING: 未確認
            - APPROVED: 承認
            - REJECTED: 否認
          enum:
            - PENDING
            - APPROVED
            - REJECTED
          example: 'PENDING'
        remarks:
          type: string
          description: 備考
          example: ''

    CustomerApproveRequest:
      type: object
      description: |
        承認ステータス更新リクエスト
        confirm_status、approval_status、remarks のいずれか1つ以上を指定してください。
      properties:
        confirm_status:
          type: string
          nullable: true
          description: |
            確認ステータス
            - PENDING: 未確認
            - CONFIRMED: 確認済
            - NEEDS_CONFIRMATION: 要確認
          enum:
            - PENDING
            - CONFIRMED
            - NEEDS_CONFIRMATION
          example: 'CONFIRMED'
        approval_status:
          type: string
          nullable: true
          description: |
            承認ステータス
            - PENDING: 未確認
            - APPROVED: 承認
            - REJECTED: 否認
          enum:
            - PENDING
            - APPROVED
            - REJECTED
          example: 'APPROVED'
        remarks:
          type: string
          description: 備考
          example: '承認済み'

    CustomFieldSchemaResponse:
      type: object
      description: |
        カスタムフィールドのJSON Schema。
        事前に設定されたカスタムフィールドの定義を返します。
      properties:
        type:
          type: string
          description: スキーマタイプ
          example: 'object'
        properties:
          type: object
          description: 各カスタムフィールドの定義
          additionalProperties:
            type: object
            properties:
              title:
                type: string
                description: フィールド名
              type:
                type: string
                description: データ型 (string, integer, number, boolean)
              format:
                type: string
                description: フォーマット (date, date-time など)
              maxLength:
                type: integer
                description: 最大文字数
              enum:
                type: array
                description: 選択肢リスト（ENUM型の場合）
                items:
                  type: string
          example:
            department:
              title: '部署'
              type: 'string'
              maxLength: 255
            priority:
              title: '優先度'
              type: 'string'
              enum: ['high', 'medium', 'low']
            contract_date:
              title: '契約日'
              type: 'string'
              format: 'date'
        required:
          type: array
          description: 必須フィールドのキー一覧
          items:
            type: string
          example: ['department', 'priority', 'contract_date']
        additionalProperties:
          type: boolean
          description: 追加プロパティの許可
          example: false

    ErrorResponse:
      type: object
      description: エラーレスポンス
      properties:
        status:
          type: boolean
          description: 処理ステータス
          example: false
        status_code:
          type: integer
          description: HTTPステータスコード
          example: 400
        error:
          type: string
          description: エラーメッセージ
          example: 'バリデーションエラー'
        errors:
          type: object
          description: 詳細エラー情報
          example:
            company_name: ['この項目は必須です。']

    ValidationErrorResponse:
      type: object
      description: バリデーションエラーレスポンス
      additionalProperties:
        type: array
        items:
          type: string
      example:
        company_name: ['この項目は必須です。']

  responses:
    BadRequest:
      description: バリデーションエラー
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
          examples:
            required_field_error:
              summary: 必須フィールドエラー
              value:
                company_name: ['この項目は必須です。']
            duplicate_corporate_number:
              summary: 法人番号重複エラー
              value:
                corporate_number: ['この法人番号は既に使用されています。']

    Unauthorized:
      description: 認証エラー
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: '認証に失敗しました。'

    NotFound:
      description: 取引先が見つからない
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: '取引先が見つかりませんでした。'

tags:
  - name: Customer
    description: 取引先管理API（外部システム連携用）