{
  "openapi": "3.1.0",
  "info": {
    "title": "7 Rekomendasi Produk — API Rekomendasi Produk",
    "version": "1.0.0",
    "summary": "Katalog kurasi 7 produk terbaik per topik, dibaca mesin dan agen AI tanpa HTML.",
    "description": "7 Rekomendasi Produk adalah pusat kurasi dan ulasan yang merangkum 7 produk terbaik per topik, lengkap dengan kode pencarian video, kisaran harga Rupiah, kelebihan-kekurangan, dan tautan harga ke Shopee, Tokopedia, serta TikTok Shop.\n\nSemua respons adalah JSON murni tanpa markup. Harga berupa snapshot dan selalu disertai tanggal verifikasinya. Bahasa konten: Indonesia.",
    "contact": {
      "name": "7 Rekomendasi Produk",
      "url": "https://tujuhrekomendasi.com",
      "email": "redaksi@tujuhrekomendasi.com"
    },
    "license": {
      "name": "CC BY 4.0",
      "identifier": "CC-BY-4.0"
    },
    "x-language": "id",
    "x-currency": "IDR",
    "x-llms-txt": "https://tujuhrekomendasi.com/llms.txt",
    "x-llms-full": "https://tujuhrekomendasi.com/llms-full.txt"
  },
  "servers": [
    {
      "url": "https://tujuhrekomendasi.com",
      "description": "Produksi"
    }
  ],
  "externalDocs": {
    "description": "Basis pengetahuan lengkap dalam Markdown",
    "url": "https://tujuhrekomendasi.com/llms-full.txt"
  },
  "tags": [
    {
      "name": "rekomendasi",
      "description": "Cari produk kurasi berdasarkan kata kunci, kategori, atau nomor kode"
    },
    {
      "name": "artikel",
      "description": "Daftar kurasi 7 produk per topik"
    },
    {
      "name": "kategori",
      "description": "Katalog kategori"
    }
  ],
  "paths": {
    "/api/v1/rekomendasi": {
      "get": {
        "tags": [
          "rekomendasi"
        ],
        "operationId": "cariRekomendasi",
        "summary": "Cari produk kurasi",
        "description": "Kembalikan produk yang cocok. Minimal satu parameter wajib diisi (q, kategori, atau kode) supaya server tidak mengembalikan seluruh katalog secara tidak sengaja.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Nama produk, merek, use case, atau topik.",
            "schema": {
              "type": "string",
              "examples": [
                "rice cooker"
              ]
            }
          },
          {
            "name": "kategori",
            "in": "query",
            "required": false,
            "description": "Slug kategori.",
            "schema": {
              "type": "string",
              "examples": [
                "rumah-tangga"
              ]
            }
          },
          {
            "name": "kode",
            "in": "query",
            "required": false,
            "description": "Nomor kode produk yang disebut di video. \"042\", \"42\", dan \"KODE: 042\" dianggap sama.",
            "schema": {
              "type": "string",
              "examples": [
                "042"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Jumlah produk maksimum (1–50).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Daftar produk yang cocok.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "query": {
                      "type": "object"
                    },
                    "jumlah": {
                      "type": "integer"
                    },
                    "produk": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Produk"
                      }
                    },
                    "artikel": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Artikel"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "jumlah",
                    "produk"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Tidak ada parameter pencarian yang diisi.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/kode/{kode}": {
      "get": {
        "tags": [
          "rekomendasi"
        ],
        "operationId": "produkLewatKode",
        "summary": "Ambil satu produk dari nomor kode video",
        "parameters": [
          {
            "name": "kode",
            "in": "path",
            "required": true,
            "description": "Nomor kode, dinormalkan otomatis (042 = 42).",
            "schema": {
              "type": "string",
              "examples": [
                "042"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Produk yang diminta.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "produk": {
                      "$ref": "#/components/schemas/Produk"
                    }
                  },
                  "required": [
                    "ok",
                    "produk"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Nomor kode tidak dikenal.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/artikel/{slug}": {
      "get": {
        "tags": [
          "artikel"
        ],
        "operationId": "artikelLengkap",
        "summary": "Satu artikel kurasi dengan ketujuh produk dan FAQ",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Artikel lengkap.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "artikel": {
                      "type": "object",
                      "properties": {
                        "slug": {
                          "type": "string"
                        },
                        "judul": {
                          "type": "string"
                        },
                        "ringkasan": {
                          "type": "string"
                        },
                        "intro": {
                          "type": "string"
                        },
                        "metodologi": {
                          "type": "string"
                        },
                        "diperbarui": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "produk": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Produk"
                          }
                        },
                        "faq": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "pertanyaan": {
                                "type": "string"
                              },
                              "jawaban": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "artikel"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Slug tidak ditemukan atau artikel masih draf.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/kategori": {
      "get": {
        "tags": [
          "kategori"
        ],
        "operationId": "daftarKategori",
        "summary": "Daftar kategori beserta jumlah artikel terbitnya",
        "responses": {
          "200": {
            "description": "Kategori.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "kategori": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "nama": {
                            "type": "string"
                          },
                          "tagline": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "jumlah_artikel": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "kategori"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Produk": {
        "type": "object",
        "description": "Satu produk kurasi. Semua angka harga dalam Rupiah tanpa titik ribuan.",
        "properties": {
          "kode": {
            "type": "string",
            "description": "Nomor tiga digit yang disebut di video.",
            "examples": [
              "042"
            ]
          },
          "peringkat": {
            "type": "integer",
            "minimum": 1,
            "maximum": 7
          },
          "label": {
            "type": "string",
            "examples": [
              "Pilihan Terbaik Keseluruhan"
            ]
          },
          "nama": {
            "type": "string"
          },
          "merek": {
            "type": "string"
          },
          "kategori": {
            "type": "string"
          },
          "cocok_untuk": {
            "type": "string"
          },
          "harga_rendah": {
            "type": "integer",
            "examples": [
              2900000
            ]
          },
          "harga_tinggi": {
            "type": "integer",
            "examples": [
              3750000
            ]
          },
          "harga_label": {
            "type": "string",
            "examples": [
              "Rp2.900.000 – Rp3.750.000"
            ]
          },
          "harga_diverifikasi_pada": {
            "type": "string",
            "format": "date"
          },
          "rating": {
            "type": "number",
            "minimum": 0,
            "maximum": 5,
            "examples": [
              4.8
            ]
          },
          "ulasan": {
            "type": "string"
          },
          "kelebihan": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "kekurangan": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "spesifikasi": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "nilai": {
                  "type": "string"
                }
              },
              "required": [
                "label",
                "nilai"
              ]
            }
          },
          "tautan": {
            "type": "object",
            "properties": {
              "shopee": {
                "type": "string",
                "format": "uri"
              },
              "tokopedia": {
                "type": "string",
                "format": "uri"
              },
              "tiktokShop": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "halaman": {
            "type": "string",
            "description": "Path artikel kurasi dengan jangkar produk."
          }
        },
        "required": [
          "kode",
          "peringkat",
          "nama",
          "harga_rendah",
          "harga_tinggi",
          "rating"
        ]
      },
      "Artikel": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "judul": {
            "type": "string"
          },
          "ringkasan": {
            "type": "string"
          },
          "kategori_slug": {
            "type": "string"
          },
          "kategori_nama": {
            "type": "string"
          },
          "episode_kode": {
            "type": "string"
          },
          "diperbarui": {
            "type": "string",
            "format": "date-time"
          },
          "jumlah_produk": {
            "type": "integer"
          },
          "url": {
            "type": "string"
          },
          "seo_deskripsi": {
            "type": "string"
          }
        },
        "required": [
          "slug",
          "judul",
          "kategori_slug",
          "jumlah_produk"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "examples": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "saran": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "ok",
          "error"
        ]
      }
    }
  }
}