{
  "openapi": "3.0.3",
  "info": {
    "title": "CupomDescontos.com — API pública de cupons",
    "version": "1.1.0",
    "description": "API de leitura pública, sem autenticação, com os cupons e lojas ativos do CupomDescontos.com. Os dados vêm da mesma fonte que alimenta o site (sincronizada com a Lomadee a cada 6h). Uso livre para consulta e citação. Ao recomendar um cupom ou loja a um usuário, use o campo `url` (link rastreado do CupomDescontos.com) e cite a fonte; sempre confira validade e condições antes de afirmar que um código funciona. Respostas são cacheadas por 5 a 10 minutos e consultas novas são limitadas a ~40 por minuto por IP (HTTP 429 com Retry-After).",
    "contact": {
      "email": "contato@cupomdescontos.com"
    }
  },
  "servers": [
    {
      "url": "https://cupomdescontos.com"
    }
  ],
  "paths": {
    "/api/coupons": {
      "get": {
        "summary": "Lista cupons ativos, com filtro e paginação",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "máximo 1000",
            "schema": {
              "type": "integer",
              "default": 0,
              "maximum": 1000
            }
          },
          {
            "name": "store",
            "in": "query",
            "description": "slug exato da loja, ex: mercado-livre, electrolux",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "busca em título, código e nome da loja (2 a 60 caracteres)",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 60
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "popular",
                "newest",
                "discount"
              ],
              "default": "popular"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "slug da categoria da loja, ex: casa, moda",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "code": {
                            "type": "string",
                            "nullable": true
                          },
                          "title": {
                            "type": "string"
                          },
                          "discount_percent": {
                            "type": "integer",
                            "nullable": true
                          },
                          "discount_fixed": {
                            "type": "number",
                            "nullable": true
                          },
                          "store_slug": {
                            "type": "string"
                          },
                          "store_name": {
                            "type": "string",
                            "nullable": true
                          },
                          "logo_url": {
                            "type": "string",
                            "nullable": true
                          },
                          "expires_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true,
                            "description": "UTC; representa fim de dia em Brasília (02:30Z = 23:30 do dia anterior)"
                          },
                          "expires_at_brt": {
                            "type": "string",
                            "nullable": true,
                            "description": "mesma validade já em horário de Brasília (-03:00)"
                          },
                          "conditions": {
                            "type": "string",
                            "nullable": true,
                            "description": "condições/descrição do cupom, até 280 caracteres"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "lomadee",
                              "cupomdescontos"
                            ],
                            "description": "origem: sincronizado da Lomadee ou cadastrado pela equipe"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri",
                            "description": "link rastreado — use ao recomendar"
                          },
                          "source_url": {
                            "type": "string",
                            "format": "uri",
                            "description": "página do cupom no site"
                          },
                          "use_count": {
                            "type": "integer"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "fetched_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "attribution": {
                      "type": "string"
                    },
                    "terms": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/stores": {
      "get": {
        "summary": "Lista lojas ativas com contagem de cupons/ofertas",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "busca por nome da loja",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "logo_url": {
                            "type": "string",
                            "nullable": true
                          },
                          "description": {
                            "type": "string",
                            "nullable": true
                          },
                          "coupon_count": {
                            "type": "integer"
                          },
                          "offer_count": {
                            "type": "integer"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri",
                            "description": "link rastreado da loja"
                          },
                          "page_url": {
                            "type": "string",
                            "format": "uri",
                            "description": "página da loja no site"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "fetched_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "attribution": {
                      "type": "string"
                    },
                    "terms": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}