openapi: 3.0.3
info:
  title: Greffe Fonciq — GREF public read API v1
  version: 0.1.0
  description: >
    Lecture anonyme **redacted** d’une exécution GREF persistée (`rf_gref_readings`).
    Aucune chaîne OCR brute ni texte libre : sous-ensemble documenté ci-dessous.
    L’empreinte `sha256` est celle du PDF Registre (document).

servers:
  - url: https://fonciq.ca
    description: Production
  - url: http://127.0.0.1:3000
    description: Développement local (site)

paths:
  /api/v1/gref/document/{sha256}:
    get:
      summary: Dernier enregistrement GREF public (payload redacted)
      operationId: getGrefDocumentV1
      parameters:
        - name: sha256
          in: path
          required: true
          description: Empreinte SHA-256 du PDF (64 hex).
          schema:
            type: string
            pattern: '^[a-fA-F0-9]{64}$'
      responses:
        '200':
          description: Lecture trouvée
          content:
            application/json:
              schema:
                type: object
                required: [sha256, reading]
                properties:
                  sha256:
                    type: string
                  reading:
                    type: object
                    required:
                      [public_id, version, composite_tier, composite_score, attestation_status, payload]
                    properties:
                      public_id:
                        type: string
                        format: uuid
                      version:
                        type: integer
                      composite_tier:
                        type: string
                        enum: [red, yellow, green]
                      composite_score:
                        type: number
                      attestation_status:
                        type: string
                      payload:
                        type: object
                        description: >
                          Sous-ensemble sûr (composite, pipeline_version, polygones résumés, etc.).
                          Marqueur `_public_redaction=gref_v1_read`. Pas de `cleanup_full_text`.
              example:
                sha256: abababababababababababababababababababababababababababababababab
                reading:
                  public_id: 8d2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                  version: 1
                  composite_tier: green
                  composite_score: 0.82
                  attestation_status: draft
                  payload:
                    _public_redaction: gref_v1_read
                    pipeline_version: gref-1.0
        '404':
          description: Aucune ligne `rf_gref_readings` pour ce digest
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: not_found
                  sha256:
                    type: string
        '400':
          description: sha256 invalide
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: invalid_sha256

  /api/v1/gref/document/{sha256}/envelope:
    get:
      summary: Enveloppe signée / RFC3161 (non implémenté)
      operationId: getGrefEnvelope
      parameters:
        - name: sha256
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-fA-F0-9]{64}$'
      responses:
        '501':
          description: À venir — utiliser `draft_attestation` sur la ressource principale
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: not_implemented
                  message:
                    type: string
                  sha256:
                    type: string
        '400':
          description: sha256 invalide