{
  "openapi": "3.0.3",
  "info": {
    "title": "JKN Data Engine & RAG Feeder API",
    "description": "Mockup BPJS Kesehatan backend data hub for RAG and Telecollecting Bots in Dimagi Open Chat Studio (OCS).",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://data-jkn.technosmart.id",
      "description": "Production Server"
    },
    {
      "url": "http://localhost:8080",
      "description": "Local Development Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Secret key for JKN RAG Feeder API (default: jkn-rag-secret-poc-2026)"
      }
    },
    "schemas": {
      "Peserta": {
        "type": "object",
        "properties": {
          "no_kartu": { "type": "string", "example": "000192830004" },
          "nik": { "type": "string", "example": "3171010404920004" },
          "nama": { "type": "string", "example": "Joko Susilo" },
          "no_hp": { "type": "string", "example": "081199440004" },
          "status_peserta": { "type": "string", "example": "NON-AKTIF (TUNGGAKAN)" },
          "jenis_peserta": { "type": "string", "example": "PBPU (Mandiri)" },
          "kelas_rawat": { "type": "integer", "example": 2 },
          "jumlah_tanggungan_kk": { "type": "integer", "example": 2 },
          "faskes_tingkat_1": { "type": "string", "example": "0123U001" },
          "nama_faskes_1": { "type": "string", "example": "Puskesmas Gambir" }
        }
      },
      "BillingSummary": {
        "type": "object",
        "properties": {
          "iuran_per_jiwa": { "type": "number", "example": 100000 },
          "jumlah_anggota_kk": { "type": "integer", "example": 2 },
          "total_iuran_bulanan_kk": { "type": "number", "example": 200000 },
          "total_tunggakan": { "type": "number", "example": 800000 },
          "total_denda": { "type": "number", "example": 0 },
          "grand_total": { "type": "number", "example": 800000 },
          "jumlah_bulan_menunggak": { "type": "integer", "example": 4 },
          "status_kolektibilitas": { "type": "string", "example": "MENUNGGAK_KRITIS" },
          "virtual_account": { "type": "string", "example": "8888800192830004" },
          "eligible_rehab": { "type": "boolean", "example": true },
          "info_program_rehab": { "type": "string" },
          "aturan_denda_layanan": { "type": "string" },
          "peringatan_layanan": { "type": "string" }
        }
      },
      "Tagihan": {
        "type": "object",
        "properties": {
          "id_tagihan": { "type": "string", "example": "INV-004-2026-08" },
          "no_kartu": { "type": "string", "example": "000192830004" },
          "bulan_tagihan": { "type": "string", "example": "2026-08" },
          "iuran_per_bulan": { "type": "number", "example": 200000 },
          "denda": { "type": "number", "example": 0 },
          "total_tagihan": { "type": "number", "example": 200000 },
          "status_bayar": { "type": "string", "example": "MENUNGGAK" },
          "tanggal_jatuh_tempo": { "type": "string", "example": "2026-08-10" },
          "tanggal_bayar": { "type": "string", "example": "" },
          "virtual_account": { "type": "string", "example": "8888800192830004" }
        }
      },
      "PesertaSummary": {
        "type": "object",
        "properties": {
          "peserta": { "$ref": "#/components/schemas/Peserta" },
          "billing": { "$ref": "#/components/schemas/BillingSummary" },
          "tagihan": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Tagihan" }
          }
        }
      },
      "Anomaly": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "ANM-FF-000192830004-0" },
          "kategori": { "type": "string", "example": "FREQUENT_FLYER" },
          "severity": { "type": "string", "example": "HIGH" },
          "no_kartu": { "type": "string", "example": "000192830004" },
          "nama_peserta": { "type": "string", "example": "Joko Susilo" },
          "keterangan": { "type": "string" },
          "indikasi": { "type": "string" }
        }
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/api/v1/rag/peserta/{identifier}": {
      "get": {
        "operationId": "getPesertaContext",
        "summary": "Ambil konteks RAG data peserta BPJS Kesehatan untuk chatbot",
        "description": "Mengembalikan data identitas, status kepesertaan, rincian tunggakan iuran kolektif 1 KK, nomor VA, kelayakan Program REHAB, dan aturan denda layanan. Input identifier menerima Nomor Kartu JKN (12/13 digit), NIK (16 digit), atau Nomor HP/WhatsApp (08xx / +628xx).",
        "parameters": [
          {
            "name": "identifier",
            "in": "path",
            "required": true,
            "description": "Nomor Kartu JKN, NIK, atau Nomor HP/WhatsApp peserta (contoh: 081199440004 atau 000192830004)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "description": "Cakupan konteks RAG: 'billing' (khusus penagihan iuran tanpa noise medis/fraud) atau 'full' (lengkap beserta riwayat kunjungan & klaim)",
            "schema": {
              "type": "string",
              "enum": ["billing", "full"],
              "default": "full"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Format output: kosongkan untuk teks Markdown (prompt prompt feeder), atau 'json' untuk JSON terstruktur",
            "schema": {
              "type": "string",
              "enum": ["markdown", "json"],
              "default": "markdown"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Konteks RAG peserta berhasil diambil",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PesertaSummary"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: API Key salah atau tidak dikirim"
          },
          "404": {
            "description": "Peserta tidak ditemukan di database JKN"
          }
        }
      }
    },
    "/api/v1/rag/menunggak": {
      "get": {
        "operationId": "listPesertaMenunggak",
        "summary": "Daftar seluruh peserta yang memiliki tunggakan iuran aktif",
        "description": "Mengembalikan daftar peserta aktif/non-aktif yang memiliki tunggakan iuran (jumlah_bulan_menunggak > 0) untuk keperluan outbound blast atau antrean telecollecting.",
        "responses": {
          "200": {
            "description": "Daftar peserta menunggak",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total_menunggak": { "type": "integer" },
                    "peserta": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Peserta"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: API Key salah atau tidak dikirim"
          }
        }
      }
    },
    "/api/v1/fraud/anomalies": {
      "get": {
        "operationId": "listFraudAnomalies",
        "summary": "Daftar anomali medis dan indikasi fraud faskes",
        "description": "Mengembalikan seluruh temuan audit klaim (Phantom Billing, Frequent Flyer, Upcoding INA-CBGs, Split Billing).",
        "responses": {
          "200": {
            "description": "Daftar anomali klaim",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total_anomalies": { "type": "integer" },
                    "anomalies": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Anomaly"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: API Key salah atau tidak dikirim"
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "operationId": "healthCheck",
        "summary": "Health check server",
        "security": [],
        "responses": {
          "200": {
            "description": "Server healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "healthy" },
                    "engine": { "type": "string", "example": "jkn-data-rag-feeder" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
