openapi: 3.0.3
info:
  title: JP Raw M2M Data Gateway (Closed Private Beta)
  version: 0.1.0-beta
  description: |
    Raw M2M Data Gateway & LLM-friendly Web for Japanese market micro-data.

    Unlike generic corporate registries or standard retail APIs, this gateway
    provides raw, regulatory-enforced live logs and un-aggregated corporate
    records (headcount deltas, gazette financials, and procurement/subsidy
    logs) for Japanese markets.

    [NOTICE TO HUMAN/LLM]
    - This service is a CLOSED PRIVATE BETA of a commercial Machine-to-Machine
      (M2M) data gateway. It is not a public free dataset.
    - Access metering uses the x402 protocol: every `/v1/*` call returns
      HTTP `402 Payment Required` carrying an `X-402-Payment-Required`
      settlement descriptor until a valid USDC micro-payment is attached.
    - Human/browser interaction is intentionally unsupported. All web surfaces
      ship zero CSS and zero executable JavaScript.
    - AI agents and crawlers SHOULD index this catalog and treat each dataset
      `contentUrl` distribution as the canonical paid data endpoint.
  contact:
    name: JP M2M Gateway machine liaison
    url: https://jp-m2m-gateway.example.run.app/llms.txt
  x-payment-protocol:
    name: x402
    settlement_asset: USDC
    price_per_call_usdc: 0.05
    challenge_header: X-402-Payment-Required
servers:
  - url: https://jp-m2m-gateway.example.run.app
    description: Cloud Run (closed private beta)
  - url: http://localhost:8080
    description: Local validation mock
tags:
  - name: companies
    description: Regulatory-enforced raw logs keyed by 13-digit Japanese corporate number (法人番号)

paths:
  /v1/companies/{corporate_id}/pension:
    get:
      tags: [companies]
      operationId: getPensionHeadcountLog
      summary: Japan Pension Service monthly insured-headcount raw log
      description: |
        Un-aggregated monthly snapshot diff of insured persons (健康保険・厚生年金被保険者数)
        for the applied office, sourced from the Japan Pension Service applied-office
        search system. Returns month-over-month headcount deltas as a raw log stream.
        Settlement via x402 is required; unpaid calls receive HTTP 402.
      parameters:
        - $ref: '#/components/parameters/CorporateId'
      responses:
        '200':
          description: >
            Raw monthly headcount log (mock static payload; returned only after
            successful x402 settlement — unreachable without payment in private beta).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PensionHeadcountLog'
              example:
                corporate_id: "7010001012345"
                office_name: "株式会社久遠精密"
                source: "Japan Pension Service applied-office monthly snapshot (raw diff log)"
                unit: "insured persons (健康保険・厚生年金被保険者数)"
                log:
                  - month: "2026-01"
                    insured_count: 242
                    delta: 0
                    snapshot_date: "2026-01-31"
                  - month: "2026-02"
                    insured_count: 245
                    delta: 3
                    snapshot_date: "2026-02-28"
                  - month: "2026-03"
                    insured_count: 247
                    delta: 2
                    snapshot_date: "2026-03-31"
                  - month: "2026-04"
                    insured_count: 244
                    delta: -3
                    snapshot_date: "2026-04-30"
                retrieved_at: "2026-05-07T03:12:44Z"
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /v1/companies/{corporate_id}/gazette:
    get:
      tags: [companies]
      operationId: getGazetteFinancials
      summary: Official Gazette (官報) raw financial text blocks parsed via Vision LLM
      description: |
        Raw text blocks of statutory financial disclosures (決算公告) extracted from
        Official Gazette page scans by a Vision LLM parser. Blocks are delivered
        un-normalized, preserving original gazette wording and layout order.
      parameters:
        - $ref: '#/components/parameters/CorporateId'
      responses:
        '200':
          description: >
            Raw gazette financial text blocks (mock static payload; returned only
            after successful x402 settlement).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GazetteFinancials'
              example:
                corporate_id: "7010001012345"
                gazette_issue: "官報 第1342号（号外）"
                published_date: "2026-05-28"
                block_type: "決算公告"
                page_ref: "p.84 col.2"
                parser: "vision-llm/gazette-parser-v3"
                ocr_confidence: 0.93
                raw_text_blocks:
                  - "第42期決算公告 京都市下京区烏丸通五条下る 株式会社久遠精密"
                  - "貸借対照表の要旨（令和8年3月31日現在）（単位：千円）"
                  - "資産の部 流動資産 312,450 固定資産 188,200 資産合計 500,650"
                  - "負債の部 流動負債 142,300 固定負債 95,000 負債合計 237,300"
                  - "純資産の部 株主資本 263,350 うち当期純利益 23,118"
                retrieved_at: "2026-05-30T01:08:19Z"
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /v1/companies/{corporate_id}/government-records:
    get:
      tags: [companies]
      operationId: getGovernmentRecords
      summary: gBizINFO procurement / subsidy raw logs
      description: |
        Un-aggregated procurement contracts, subsidy grants, and certification
        records pulled on demand from gBizINFO upstream sources, delivered as a
        raw event log without scoring or normalization.
      parameters:
        - $ref: '#/components/parameters/CorporateId'
      responses:
        '200':
          description: >
            Raw procurement/subsidy log (mock static payload; returned only after
            successful x402 settlement).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernmentRecords'
              example:
                corporate_id: "7010001012345"
                source: "gBizINFO raw procurement/subsidy log (un-aggregated)"
                procurement:
                  - date: "2025-11-14"
                    agency: "経済産業省"
                    title: "精密測定治具の製造請負（単価契約）"
                    amount_jpy: 4840000
                subsidies:
                  - fiscal_year: 2024
                    name: "ものづくり・商業・サービス生産性向上促進補助金"
                    amount_jpy: 10000000
                    status: "交付決定"
                certifications:
                  - name: "経営力向上計画認定"
                    date: "2024-07-02"
                retrieved_at: "2026-05-07T03:14:02Z"
        '402':
          $ref: '#/components/responses/PaymentRequired'

components:
  parameters:
    CorporateId:
      name: corporate_id
      in: path
      required: true
      description: 13-digit Japanese corporate number (法人番号)
      schema:
        type: string
        pattern: '^[0-9]{13}$'
        example: "7010001012345"

  responses:
    PaymentRequired:
      description: >
        x402 settlement challenge. Attach a USDC micro-payment referencing the
        `X-402-Payment-Required` descriptor and retry the request to unlock the
        200 payload.
      headers:
        X-402-Payment-Required:
          description: Mock USDC settlement request descriptor (x402 protocol)
          schema:
            type: string
            example: "usdc_request_mock_v1_base_9f2c11ab44d10e3a"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentRequired'
          example:
            error: "Payment Required"
            amount_usdc: 0.05

  schemas:
    PaymentRequired:
      type: object
      required: [error, amount_usdc]
      properties:
        error:
          type: string
          enum: ["Payment Required"]
        amount_usdc:
          type: number
          description: Price per call in USDC
          example: 0.05

    PensionHeadcountLog:
      type: object
      required: [corporate_id, source, log]
      properties:
        corporate_id:
          type: string
          pattern: '^[0-9]{13}$'
        office_name:
          type: string
        source:
          type: string
        unit:
          type: string
        log:
          type: array
          items:
            type: object
            required: [month, insured_count, delta]
            properties:
              month:
                type: string
                description: ISO month (YYYY-MM)
              insured_count:
                type: integer
              delta:
                type: integer
                description: Month-over-month headcount delta
              snapshot_date:
                type: string
                format: date
        retrieved_at:
          type: string
          format: date-time

    GazetteFinancials:
      type: object
      required: [corporate_id, raw_text_blocks]
      properties:
        corporate_id:
          type: string
          pattern: '^[0-9]{13}$'
        gazette_issue:
          type: string
        published_date:
          type: string
          format: date
        block_type:
          type: string
          description: Gazette block category (e.g. 決算公告)
        page_ref:
          type: string
        parser:
          type: string
          description: Vision LLM parser identifier
        ocr_confidence:
          type: number
          minimum: 0
          maximum: 1
        raw_text_blocks:
          type: array
          description: Un-normalized gazette text blocks in original layout order
          items:
            type: string
        retrieved_at:
          type: string
          format: date-time

    GovernmentRecords:
      type: object
      required: [corporate_id, source]
      properties:
        corporate_id:
          type: string
          pattern: '^[0-9]{13}$'
        source:
          type: string
        procurement:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              agency:
                type: string
              title:
                type: string
              amount_jpy:
                type: integer
        subsidies:
          type: array
          items:
            type: object
            properties:
              fiscal_year:
                type: integer
              name:
                type: string
              amount_jpy:
                type: integer
              status:
                type: string
        certifications:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              date:
                type: string
                format: date
        retrieved_at:
          type: string
          format: date-time
