{
  "openapi": "3.1.0",
  "info": {
    "title": "Golfeira API",
    "version": "1.0.0",
    "summary": "Anúncios ativos de equipamentos de golfe usados no Brasil e guia de preços de taco usado.",
    "description": "API pública, somente leitura, sem chave. Devolve os mesmos dados que as páginas de golfeira.com mostram: anúncios ativos de golfista para golfista (sem taxa) e o guia de preços calculado sobre anúncios reais observados em grupos brasileiros de golfe. Preços em reais (BRL). Todo erro é JSON com `error.code`, `error.message` e `error.hint`. Use quando um agente precisa do preço de mercado de um taco usado no Brasil, por categoria e marca, ou de anúncios à venda de uma categoria. Não cobre tacos novos em loja nem preços fora do Brasil. Guia em linguagem natural: https://golfeira.com/llms.txt Documentação e quickstart: https://golfeira.com/developers/. Política de versão: a versão vai na URL (/api/v1); campo novo pode aparecer a qualquer momento, campo existente não muda de tipo nem some dentro de uma versão; uma versão só é desligada seis meses depois de anunciada em /developers/, e nesse período as respostas levam os headers Deprecation e Sunset (RFC 8594). Sem chave nem cota fixa: respeite o Cache-Control das respostas; uso abusivo pode receber 429 com Retry-After.",
    "termsOfService": "https://golfeira.com/termos/",
    "contact": {
      "name": "Golfeira",
      "url": "https://golfeira.com/contato/",
      "email": "contato@golfeira.com"
    },
    "license": {
      "name": "Uso com citação e link (Content-Signal: ai-input=yes, ai-train=no)",
      "url": "https://golfeira.com/llms.txt"
    },
    "x-deprecation-policy": {
      "notice_period": "P6M",
      "announcement": "https://golfeira.com/developers/",
      "headers": [
        "Deprecation",
        "Sunset"
      ]
    }
  },
  "servers": [
    {
      "url": "https://golfeira.com/api/v1"
    }
  ],
  "tags": [
    {
      "name": "products",
      "description": "Anúncios ativos do marketplace"
    },
    {
      "name": "price-guide",
      "description": "Guia de preços de taco usado (quartis, mediana, amostra)"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getIndex",
        "summary": "Índice da API com os endpoints e as categorias válidas",
        "responses": {
          "200": {
            "description": "Índice",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "default": {
            "$ref": "#/components/responses/Default"
          }
        }
      }
    },
    "/products": {
      "get": {
        "operationId": "listProducts",
        "tags": [
          "products"
        ],
        "summary": "Lista anúncios ativos, do mais novo ao mais antigo",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Categoria do equipamento",
            "schema": {
              "$ref": "#/components/schemas/CategorySlug"
            }
          },
          {
            "name": "brand",
            "in": "query",
            "description": "Marca, como slug (taylormade, scotty-cameron) ou nome (TaylorMade)",
            "schema": {
              "$ref": "#/components/schemas/BrandSlug"
            }
          },
          {
            "name": "condition",
            "in": "query",
            "description": "Estado de conservação declarado pelo vendedor",
            "schema": {
              "$ref": "#/components/schemas/ConditionSlug"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Busca no título (2 a 60 caracteres, sem distinção de maiúsculas)",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 60
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 5000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Página de anúncios",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductList"
                },
                "example": {
                  "data": [
                    {
                      "id": "9a50cd6c-96b2-4c65-9e4a-b1e312cec974",
                      "url": "https://golfeira.com/produto/9a50cd6c-96b2-4c65-9e4a-b1e312cec974/",
                      "title": "Driver TaylorMade Stealth 2 10.5",
                      "type": "Driver",
                      "category": "drivers",
                      "brand": "TaylorMade",
                      "condition": "Usado",
                      "price": 2000,
                      "current_price": 2000,
                      "currency": "BRL",
                      "location": {
                        "city": "Campinas",
                        "state": "SP"
                      }
                    }
                  ],
                  "meta": {
                    "total": 124,
                    "limit": 20,
                    "offset": 0,
                    "next": "https://golfeira.com/api/v1/products?offset=20"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "502": {
            "$ref": "#/components/responses/Upstream"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "default": {
            "$ref": "#/components/responses/Default"
          }
        }
      }
    },
    "/products/{id}": {
      "get": {
        "operationId": "getProduct",
        "tags": [
          "products"
        ],
        "summary": "Um anúncio ativo pelo id (UUID)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Anúncio",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Product"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/Upstream"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "default": {
            "$ref": "#/components/responses/Default"
          }
        }
      }
    },
    "/price-guide": {
      "get": {
        "operationId": "getPriceGuide",
        "tags": [
          "price-guide"
        ],
        "summary": "Faixa de preço por categoria (p25, mediana, p75, amostra)",
        "responses": {
          "200": {
            "description": "Categorias do guia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "methodology": {
                      "type": "string",
                      "format": "uri"
                    },
                    "note": {
                      "type": "string"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CategoryStat"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "502": {
            "$ref": "#/components/responses/Upstream"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "default": {
            "$ref": "#/components/responses/Default"
          }
        }
      }
    },
    "/price-guide/{category}": {
      "get": {
        "operationId": "getPriceGuideCategory",
        "tags": [
          "price-guide"
        ],
        "summary": "Faixa da categoria e das marcas com amostra suficiente (20 ou mais anúncios)",
        "parameters": [
          {
            "name": "category",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/CategorySlug"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Categoria com marcas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "methodology": {
                      "type": "string",
                      "format": "uri"
                    },
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/CategoryStat"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "brands": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/BrandStat"
                              }
                            }
                          }
                        }
                      ]
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/Upstream"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "default": {
            "$ref": "#/components/responses/Default"
          }
        }
      }
    },
    "/price-guide/{category}/{brand}": {
      "get": {
        "operationId": "getPriceGuideBrand",
        "tags": [
          "price-guide"
        ],
        "summary": "Faixa de uma marca dentro da categoria",
        "parameters": [
          {
            "name": "category",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/CategorySlug"
            }
          },
          {
            "name": "brand",
            "in": "path",
            "required": true,
            "description": "Slug da marca (taylormade, callaway, ping, scotty-cameron...)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Marca",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "methodology": {
                      "type": "string",
                      "format": "uri"
                    },
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/BrandStat"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "category": {
                              "$ref": "#/components/schemas/CategorySlug"
                            }
                          }
                        }
                      ]
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "methodology": "https://golfeira.com/metodologia/",
                  "data": {
                    "category": "drivers",
                    "brand": "TaylorMade",
                    "slug": "taylormade",
                    "url": "https://golfeira.com/quanto-vale/drivers/taylormade/",
                    "sample": 97,
                    "p25": 600,
                    "median": 1200,
                    "p75": 2397,
                    "currency": "BRL",
                    "last_seen": "2026-09-03"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/Upstream"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "default": {
            "$ref": "#/components/responses/Default"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CategorySlug": {
        "type": "string",
        "enum": [
          "drivers",
          "ferros",
          "putters",
          "wedges",
          "madeiras",
          "hibridos",
          "bolsas",
          "kits"
        ]
      },
      "BrandSlug": {
        "type": "string",
        "enum": [
          "taylormade",
          "callaway",
          "titleist",
          "ping",
          "mizuno",
          "wilson",
          "cobra",
          "odyssey",
          "cleveland",
          "pxg",
          "srixon",
          "bridgestone",
          "scotty-cameron",
          "nike",
          "g-fore",
          "footjoy",
          "outras"
        ]
      },
      "ConditionSlug": {
        "type": "string",
        "enum": [
          "novo",
          "como-novo",
          "seminovo",
          "muito-bom",
          "bom",
          "usado",
          "economico"
        ]
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Página pública do anúncio (também responde em Markdown com Accept: text/markdown)"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "type": [
              "string",
              "null"
            ],
            "description": "Tipo de produto como cadastrado (Driver, Ferro, Kit de Ferros, Bolsa...)"
          },
          "category": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/CategorySlug"
              },
              {
                "type": "null"
              }
            ]
          },
          "brand": {
            "type": [
              "string",
              "null"
            ]
          },
          "model": {
            "type": [
              "string",
              "null"
            ]
          },
          "condition": {
            "type": [
              "string",
              "null"
            ]
          },
          "price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Preço cheio em BRL"
          },
          "current_price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Preço em vigor: promocional quando ativo, senão o cheio"
          },
          "promotional_price": {
            "type": [
              "number",
              "null"
            ]
          },
          "currency": {
            "type": "string",
            "const": "BRL"
          },
          "location": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "state": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "images": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "free_shipping": {
            "type": "boolean"
          },
          "accepts_trade": {
            "type": "boolean"
          },
          "specs": {
            "type": "object",
            "properties": {
              "loft": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "flex": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "handedness": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "url",
          "currency",
          "images"
        ]
      },
      "ProductList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "total": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "limit": {
                "type": "integer"
              },
              "offset": {
                "type": "integer"
              },
              "next": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri",
                "description": "URL da próxima página; null na última"
              }
            },
            "required": [
              "limit",
              "offset",
              "next"
            ]
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "Stat": {
        "type": "object",
        "properties": {
          "sample": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Anúncios observados na amostra"
          },
          "p25": {
            "type": [
              "number",
              "null"
            ]
          },
          "median": {
            "type": [
              "number",
              "null"
            ]
          },
          "p75": {
            "type": [
              "number",
              "null"
            ]
          },
          "currency": {
            "type": "string",
            "const": "BRL"
          },
          "last_seen": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Data de apuração (último anúncio visto)"
          }
        }
      },
      "CategoryStat": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Stat"
          },
          {
            "type": "object",
            "properties": {
              "category": {
                "$ref": "#/components/schemas/CategorySlug"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "listings_url": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri"
              }
            },
            "required": [
              "category",
              "url"
            ]
          }
        ]
      },
      "BrandStat": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Stat"
          },
          {
            "type": "object",
            "properties": {
              "brand": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "brand",
              "slug",
              "url"
            ]
          }
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "bad_request",
                  "not_found",
                  "method_not_allowed",
                  "upstream_error"
                ]
              },
              "message": {
                "type": "string"
              },
              "hint": {
                "type": "string",
                "description": "Como sair do erro: parâmetros válidos, rota certa ou quando tentar de novo"
              },
              "docs": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "code",
              "message",
              "hint",
              "docs"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Parâmetro inválido; `hint` lista os valores aceitos",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "bad_request",
                "message": "category \"driver\" nao existe",
                "hint": "Use um destes: drivers, ferros, putters, wedges, madeiras, hibridos, bolsas, kits.",
                "docs": "https://golfeira.com/openapi.json"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Recurso inexistente ou anúncio vendido",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Upstream": {
        "description": "Banco indisponível; tente de novo em alguns segundos (Retry-After)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Default": {
        "description": "Qualquer outro erro, no mesmo envelope",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "Só GET, HEAD e OPTIONS",
        "headers": {
          "Allow": {
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Documentação, quickstart e política de versão",
    "url": "https://golfeira.com/developers/"
  }
}