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

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

    主な機能：
    - 取引先の一覧の取得(検索・ページング対応)
    - 取引先の新規作成
    - 取引先詳細の取得・更新・削除
    - 法人番号による企業情報検索・取引先作成

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

    変更履歴：
    - 1.0.1: custom_fields フィールドを追加

  version: 1.0.1

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: 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_name:
                  type: string
                  description: 会社名
                  example: 'ソーシャルワイヤー'

      responses:
        '200':
          description: 取引先部分更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPartialUpdateResponse'
        '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: '企業情報が見つかりませんでした。'

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: 備考
        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: '取締役ＣＯＯ'

    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: '重要取引先'
        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'

    CustomerPartialUpdateResponse:
      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: '重要取引先'
        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
          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: '重要取引先'
        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: '重要取引先'
        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: '重要取引先'
        custom_fields:
          type: object
          nullable: true
          description: カスタムフィールド（事前に設定したキー・型の形式でデータを格納可能）
          additionalProperties: true
          example:
            department: '営業部'
            priority: 'high'

    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（外部システム連携用）