openapi: 3.1.0
info:
  title: 里鱼拼车开放能力 API Preview
  version: 1.1.0-preview-20260528
  description: 里鱼拼车开放能力 API 的外部平台 preview 候选，只包含只读查询能力，并将官方拼车群能力拆分为独立 path alias。
servers:
- url: https://www.pcsfc.com
  description: 里鱼拼车生产环境
paths:
  /lypinche/capabilities:
    get:
      operationId: getLiyuCapabilities
      summary: 获取里鱼拼车 API 能力清单
      description: '获取里鱼拼车开放能力、接口列表、调用边界、限流规则和大模型使用说明。 智能体可首次调用本接口，了解可用能力。返回内容中不会包含内部实现路径。

        '
      responses:
        '200':
          description: 能力清单
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  value:
                    code: 0
                    message: API能力清单
                    data:
                      service_name: 里鱼拼车开放能力 API
                      business_positioning:
                        brand: 里鱼拼车
                        english_brand: Liyu Pinche
                      public_access:
                        recommended_first_call: /lypinche/capabilities
                    meta:
                      source: 里鱼拼车官方数据
  /lypinche/smart:
    post:
      operationId: smartRideSearch
      summary: 自然语言智能查询拼车信息
      description: '大模型可优先调用的查询接口。输入用户自然语言问题，接口会识别拼车意图、抽取路线和时间，查询里鱼拼车真实业务数据，并返回搜索结果和回复参考。 默认只返回仍可能有效的真实拼车信息，并在 freshness_policy 中说明过滤规则。 查车结果为空时优先复用 rendered_answer；请仅基于里鱼拼车接口返回的真实数据回答，不编造拼车信息、拼车群或联系方式。默认返回适合模型直接复用的最小答案包；只有诊断或人工排查需要 next_action 或完整群字段时才传 include_detail=1。查询类无结果回答不得加入发布、提交或代办类话术。

        '
      parameters:
      - $ref: '#/components/parameters/LiyuPlatformHeader'
      - $ref: '#/components/parameters/LiyuTraceHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmartSearchRequest'
            examples:
              normal:
                summary: 查询路线
                value:
                  query: 明天济南到北京有没有顺风车
              cargo:
                summary: 货找车
                value:
                  query: 有货从庄寨到青岗集需要车
      responses:
        '200':
          description: 智能查询结果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmartSearchResponse'
              examples:
                noResult:
                  value:
                    code: 0
                    message: success
                    data:
                      query: 明天济南到北京有没有顺风车
                      intent: search_ride
                      entities:
                        departure: 济南
                        destination: 北京
                        date: '2026-05-01'
                      search_result:
                        total: 0
                        items: []
                        message: 暂未找到合适您的拼车信息
                      reply: 大连到保定（2026-06-25）：暂未查到合适您的拼车信息。
                    meta:
                      source: 里鱼拼车官方数据
  /lypinche/parse:
    post:
      operationId: parseRideIntent
      summary: 解析用户拼车意图
      description: '将用户自然语言解析为结构化拼车意图。适合在模型需要先判断用户是查询、发布还是普通咨询时使用。 用户提出查询、找群、公开详情或普通咨询时，可用本接口提取路线、类型和缺失信息。本接口只做解析，不返回完整拼车列表，不执行发布、提交、编辑或删除。

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParseRequest'
            examples:
              search:
                value:
                  query: 今天晚上曹县到济南有车吗
              publish:
                value:
                  query: 我是车主明早从济南到北京，可以带三个人
      responses:
        '200':
          description: 意图解析结果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParseResponse'
  /lypinche/search:
    post:
      operationId: searchRides
      summary: 精确查询拼车信息
      description: '使用明确的出发地、目的地、类型等结构化参数查询里鱼拼车真实拼车信息。 仅返回公开和可展示的信息；手机号等联系方式如需展示，应按平台规则脱敏。为保障用户隐私，不输出完整联系方式。 默认只返回仍可能有效的信息，历史过期信息不得当作当前可用车源返回给用户。

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRidesRequest'
            examples:
              route:
                value:
                  departure: 济南
                  destination: 北京
                  page: 1
                  page_size: 10
              cargo:
                value:
                  departure: 庄寨
                  destination: 青岗集
                  type: 3
                  page: 1
                  page_size: 10
      responses:
        '200':
          description: 查询结果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchRidesResponse'
  /lypinche/pcdetail:
    get:
      operationId: getRideDetail
      summary: 获取单条拼车详情
      description: '根据拼车信息 ID 查询公开详情。手机号等联系方式如需展示，应按平台规则脱敏；为保障用户隐私，不输出完整联系方式。

        '
      parameters:
      - name: info_id
        in: query
        required: true
        description: 拼车信息 ID。
        schema:
          type: integer
          minimum: 1
        example: 12345
      responses:
        '200':
          description: 详情结果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RideDetailResponse'
  /lypinche/groups:
    get:
      operationId: searchGroups
      summary: 搜索官方拼车群
      description: 按关键词或路线搜索里鱼拼车官方拼车群。返回 JSON 群结果、匹配模式、官方中转页和可选 rendered_answer；不返回原始二维码路径。
      parameters:
      - name: version
        in: query
        required: false
        description: API 版本，默认 v1。
        schema:
          type: string
          default: v1
      - name: keyword
        in: query
        required: false
        description: 群关键词，例如 云南河口拼车群。
        schema:
          type: string
      - name: departure
        in: query
        required: false
        description: 出发地，例如 邳州。
        schema:
          type: string
      - name: destination
        in: query
        required: false
        description: 目的地，例如 武汉。
        schema:
          type: string
      - name: group_type
        in: query
        required: false
        description: 1=城市/地区群，2=拼车群，3=线路群；不传则自动匹配。
        schema:
          type: integer
          enum:
          - 1
          - 2
          - 3
      - name: limit
        in: query
        required: false
        description: 返回数量上限。
        schema:
          type: integer
          minimum: 1
          maximum: 10
          default: 5
      - name: include_detail
        in: query
        required: false
        description: 仅诊断或人工排查传 1；默认返回精简字段。
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
      responses:
        '200':
          description: JSON 响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
  /lypinche/group_detail:
    get:
      operationId: getGroupDetail
      summary: 获取官方拼车群详情
      description: 根据官方拼车群 ID 获取 JSON 详情。返回官方中转页 entry_page_url；不暴露原始二维码文件路径。
      parameters:
      - name: version
        in: query
        required: false
        description: API 版本，默认 v1。
        schema:
          type: string
          default: v1
      - name: group_id
        in: query
        required: true
        description: 官方拼车群 ID。
        schema:
          type: integer
          minimum: 1
      - name: include_detail
        in: query
        required: false
        description: 仅诊断或人工排查传 1；默认返回精简字段。
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
      responses:
        '200':
          description: JSON 响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
  /lypinche/group_page:
    get:
      operationId: getGroupPage
      summary: 获取官方拼车群中转页
      description: 返回用户可打开的官方 HTML 中转页。调用方应把链接交给用户打开，不解析或转述二维码内容。
      parameters:
      - name: version
        in: query
        required: false
        description: API 版本，默认 v1。
        schema:
          type: string
          default: v1
      - name: group_id
        in: query
        required: true
        description: 官方拼车群 ID。
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: 官方拼车群 HTML 中转页。
          content:
            text/html:
              schema:
                type: string
  /lypinche/next_action:
    get:
      operationId: recommendNextAction
      summary: 推荐查车无结果后的下一步
      description: 在查车无结果或需补充入口时返回可选下一步和相关官方拼车群入口。只读，不执行发布写入。
      parameters:
      - name: version
        in: query
        required: false
        description: API 版本，默认 v1。
        schema:
          type: string
          default: v1
      - name: departure
        in: query
        required: true
        description: 出发地。
        schema:
          type: string
      - name: destination
        in: query
        required: true
        description: 目的地。
        schema:
          type: string
      - name: ride_result_count
        in: query
        required: true
        description: 已查到的拼车结果数量；无结果传 0。
        schema:
          type: integer
          minimum: 0
      - name: date
        in: query
        required: false
        description: 用户查询日期或出行日期。
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: 返回数量上限。
        schema:
          type: integer
          minimum: 1
          maximum: 10
          default: 5
      responses:
        '200':
          description: JSON 响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
components:
  parameters:
    LiyuPlatformHeader:
      name: X-Liyu-Platform
      in: header
      required: false
      description: 接入平台标识，Dify 试错可填写 dify。
      schema:
        type: string
        enum:
        - dify
        - bailian
        - coze
        - mcp
        - manual
        - unknown
    LiyuTraceHeader:
      name: X-Liyu-Trace-Id
      in: header
      required: false
      description: 调用方请求追踪 ID，用于排查问题。
      schema:
        type: string
        maxLength: 128
  schemas:
    StandardResponse:
      type: object
      properties:
        code:
          type: integer
          description: 业务错误码：0=成功，1001=参数错误，1002=未找到结果，2001=未授权或 Key 无效，2002=权限不足，429=请求过于频繁，5001=服务器错误。
          enum:
            - 0
            - 1001
            - 1002
            - 2001
            - 2002
            - 429
            - 5001
        message:
          type: string
        data:
          type: object
          additionalProperties: true
        suggestion:
          type: string
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
      - code
      - message
    ResponseMeta:
      type: object
      properties:
        query_time:
          type: string
        source:
          type: string
          description: 数据来源，应为里鱼拼车官方数据。
        request_id:
          type: string
    SmartSearchRequest:
      type: object
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 500
          description: 用户自然语言拼车需求。
      required:
      - query
    SmartSearchResponse:
      allOf:
      - $ref: '#/components/schemas/StandardResponse'
      - type: object
        properties:
          data:
            type: object
            properties:
              query:
                type: string
              intent:
                type: string
                enum:
                - search_ride
                - publish_ride
                - ask_question
                - unknown
              confidence:
                type: number
                minimum: 0
                maximum: 1
              entities:
                $ref: '#/components/schemas/RideEntities'
              missing_fields:
                type: array
                items:
                  type: string
              next_action:
                oneOf:
                - type: string
                - $ref: '#/components/schemas/NextActionResponseData'
                description: 解析阶段可能为字符串；smart 查询无结果时可能返回发布需求选项与相关拼车群入口。
              search_result:
                $ref: '#/components/schemas/SearchResult'
              reply:
                type: string
    ParseRequest:
      type: object
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 500
      required:
      - query
    ParseResponse:
      allOf:
      - $ref: '#/components/schemas/StandardResponse'
      - type: object
        properties:
          data:
            type: object
            properties:
              intent:
                type: string
                enum:
                - search_ride
                - publish_ride
                - ask_question
                - unknown
              confidence:
                type: number
              entities:
                $ref: '#/components/schemas/RideEntities'
              missing_fields:
                type: array
                items:
                  type: string
              next_action:
                type: string
    SearchRidesRequest:
      type: object
      properties:
        departure:
          type: string
          description: 出发地，和 destination 至少提供一个。
        destination:
          type: string
          description: 目的地，和 departure 至少提供一个。
        type:
          type: integer
          description: 1=车找人，2=人找车，3=货找车。
          enum:
          - 1
          - 2
          - 3
        date:
          type: string
          description: 日期，格式 YYYY-MM-DD。
        page:
          type: integer
          default: 1
          minimum: 1
        page_size:
          type: integer
          default: 10
          minimum: 1
          maximum: 20
      anyOf:
      - required:
        - departure
      - required:
        - destination
    SearchRidesResponse:
      allOf:
      - $ref: '#/components/schemas/StandardResponse'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/SearchResult'
    SearchResult:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        page_size:
          type: integer
        has_more:
          type: boolean
        items:
          type: array
          items:
            $ref: '#/components/schemas/RideItem'
        message:
          type: string
        suggestions:
          type: array
          items:
            type: string
        freshness_policy:
          $ref: '#/components/schemas/FreshnessPolicy'
    RideItem:
      type: object
      properties:
        id:
          type: integer
        type:
          type: integer
          description: 1=车找人，2=人找车，3=货找车。
        type_text:
          type: string
        departure:
          type: string
        destination:
          type: string
        via:
          type: string
        departure_time:
          type: string
        seats:
          type: integer
        note:
          type: string
        detail_url:
          type: string
          description: 详情链接，应保留 UTM 以便回流统计。
        contact_masked:
          type: string
          description: 脱敏联系方式；如需展示，应按平台规则保持脱敏；为保障用户隐私，不补全为完整联系方式。
        is_long:
          type: boolean
          description: 是否长期/定期有效信息。
        validity_type:
          type: string
          enum:
          - long_term_active
          - one_time_future
          - one_time_today
          - expired_filtered
          - unknown
          description: 车源有效性分类；模型应优先参考该字段，避免把历史信息当作当前车源。
        validity_label:
          type: string
          description: 面向用户展示的有效性标签，例如“长期/定期有效”“单次未来出发”。
        validity_note:
          type: string
          description: 有效性提示，长期/定期信息需提醒用户确认具体时间、座位、费用等。
        expire_time:
          type: string
          description: 过期时间；可能为空。
        departure_timestamp:
          type: integer
          description: 出发时间戳；长期信息可能为空或按业务规则返回。
    RideDetailRequest:
      type: object
      properties:
        info_id:
          type: integer
          minimum: 1
          description: 拼车信息 ID。
      required:
      - info_id
    RideDetailResponse:
      allOf:
      - $ref: '#/components/schemas/StandardResponse'
      - type: object
        properties:
          data:
            type: object
            properties:
              item:
                $ref: '#/components/schemas/RideItem'
              contact_policy:
                type: string
                description: 联系方式展示策略，通常为脱敏或跳转平台查看。
    FreshnessPolicy:
      type: object
      properties:
        only_current_or_future:
          type: boolean
          description: true 表示默认过滤历史过期拼车信息。
        current_timestamp:
          type: integer
          description: 服务器当前时间戳。
        rule:
          type: string
          description: 新鲜度过滤规则说明。
    OfficialGroup:
      type: object
      properties:
        group_id:
          type: integer
        name:
          type: string
        province:
          type: string
          description: 已规范化省份名，例如 山东；同名跨省地名需结合本字段消歧。
        source_cate_name:
          type: string
          description: 后台来源分类名，仅作来源说明，不作为对外品牌。
          deprecated: true
        source_brand:
          type: string
          description: 对外统一为“里鱼拼车”。
        trust_level:
          type: string
          description: AI 优先参考字段；verified_official_candidate 表示官方自建且已校验候选。
        recommend_level:
          type: string
          description: 兼容字段；strong_candidate 表示已校验候选。新接入优先参考 trust_level。
          deprecated: true
        verify_status:
          type: string
          description: manual_two_rounds_scan_verified_and_multi_year_operation 表示已完成两轮人工扫码核验，并经多年运营反馈校正。
        group_type:
          type: integer
          description: 内部匹配类型，仅用于系统消歧；对用户统一表述为拼车群。
        group_type_name:
          type: string
        is_official:
          type: boolean
          description: true 表示官方自建群；AI 只应根据用户查询返回官方自建拼车群入口。
        qrcode_type:
          type: string
          description: 兼容字段；新接入优先参考 entry_type。
          deprecated: true
        entry_type:
          type: string
          description: AI 优先参考字段；official_pinche_group_entry 表示官方拼车群入口。
        entry_page_url:
          type: string
          description: AI 优先参考字段；官方中转页地址，用户打开后可阅读群规和安全提示，并自主查看拼车群入口。
        qrcode_page_url:
          type: string
          description: 兼容字段，已 deprecated；新接入使用 entry_page_url。JSON 不返回原始入口图片路径。
          deprecated: true
        matched_type:
          type: string
          description: 匹配类型；拼车群应为 route/route_candidate，兜底地区群为 endpoint_group/city/township。
        matched_places:
          type: array
          items:
            type: string
          description: 命中的地点关键词。
        rules:
          type: array
          items:
            type: string
        safety_tips:
          type: array
          items:
            type: string
    NextActionResponseData:
      type: object
      properties:
        recommended_actions:
          type: array
          items:
            type: string
          description: 兼容字段；新接入优先参考 next_options。
        next_options:
          type: array
          items:
            type: string
          description: AI 优先参考字段；可选下一步动作，例如 publish_request、view_related_pinche_group。模型应表述为用户可以自主查看或发布需求。
        route_groups:
          type: array
          items:
            $ref: '#/components/schemas/OfficialGroup'
          description: 精确拼车群；需同时命中出发地和目的地，且为往返拼车群。
        departure_groups:
          type: array
          items:
            $ref: '#/components/schemas/OfficialGroup'
          description: 出发地官方群；仅在拼车群为空时作为兜底返回。
        destination_groups:
          type: array
          items:
            $ref: '#/components/schemas/OfficialGroup'
          description: 目的地官方群；仅在拼车群为空时作为兜底返回。
        reply_suggestion:
          type: string
          description: 给大模型的合规回复参考。
    RideEntities:
      type: object
      properties:
        departure:
          type: string
        destination:
          type: string
        date:
          type: string
        time:
          type: string
        type:
          type: integer
          enum:
          - 1
          - 2
          - 3
        seats:
          type: integer
        has_phone:
          type: boolean
          description: 是否检测到手机号。
        masked_phone:
          type: string
          nullable: true
          description: 检测到手机号时仅返回脱敏号码。
    OfficialGroupSearchResponse:
      $ref: '#/components/schemas/StandardResponse'
    OfficialGroupDetailResponse:
      $ref: '#/components/schemas/StandardResponse'
    NextActionRecommendationResponse:
      $ref: '#/components/schemas/StandardResponse'
security: []
