{
  "openapi": "3.1.0",
  "info": {
    "title": "Pipocando Festas e Eventos API",
    "version": "1.0.0",
    "description": "Public programmatic REST API for Pipocando Festas e Eventos. Enables AI agents, LLM tool callers, and developers to explore party entertainment packages, check date availability in Rio de Janeiro, query ready combos, calculate quotes, and search party guides.\n\n### Rate Limiting (RFC RateLimit Headers)\nAll endpoints enforce a default window rate limit:\n- `RateLimit-Limit`: 120 requests\n- `RateLimit-Remaining`: Remaining quota in current 60s window\n- `RateLimit-Reset`: Seconds remaining until window reset\n- `RateLimit-Policy`: '120;w=60'\n- In case of 429 Too Many Requests, a `Retry-After: 60` header is returned.\n\n### Versioning and Deprecation Policy\nThis API is versioned via URL path (`/api/v1/`). Major releases remain stable for a minimum of 24 months. Deprecations are announced with standard `Sunset` and `Deprecation` headers and documented at https://pipocando.org/docs/versioning.",
    "contact": {
      "name": "Pipocando Support Team",
      "email": "contato@pipocando.org",
      "url": "https://pipocando.org"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://pipocando.org/privacy"
    }
  },
  "servers": [
    {
      "url": "https://pipocando.org",
      "description": "Official Production Server"
    }
  ],
  "paths": {
    "/api/v1/services": {
      "get": {
        "operationId": "listServices",
        "summary": "List available entertainment and recreation services",
        "description": "Returns the complete catalog of services offered by Pipocando Festas in Rio de Janeiro, including traditional infant recreation, teen sports dynamics, inflatable rentals, and creative workshops.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Filter services by category: 'recreacao', 'teen', 'brinquedos', 'oficinas', or 'all'",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["recreacao", "teen", "brinquedos", "oficinas", "all"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of available services successfully retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServicesListResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/combos": {
      "get": {
        "operationId": "listCombos",
        "summary": "List ready party combos and promotional packages",
        "description": "Retrieves pre-configured, cost-effective party combos: Traditional Recreation, Recreation + Inflatable Toy, Recreation + Photography, and Premium Full Recreation.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Filter combos by category: 'recreacao', 'teen', or 'brinquedos'",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["recreacao", "teen", "brinquedos"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Combos list successfully returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CombosListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/availability": {
      "get": {
        "operationId": "checkAvailability",
        "summary": "Check recreation team and toy availability for an event date",
        "description": "Verifies whether Pipocando's recreation crews and toys are available on the specified date in Rio de Janeiro.",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "description": "Event date in YYYY-MM-DD format (must be current or future date)",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "neighborhood",
            "in": "query",
            "description": "Neighborhood in Rio de Janeiro (e.g., 'Barra da Tijuca', 'Recreio', 'Copacabana', 'Tijuca')",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Availability report returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AvailabilityResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/faq": {
      "get": {
        "operationId": "getFaq",
        "summary": "Retrieve frequently asked questions and business policies",
        "description": "Returns verified answers to common questions about payment methods, rain contingencies, staff ratios, and picnic coordination.",
        "parameters": [
          {
            "name": "topic",
            "in": "query",
            "description": "Topic or keyword filter for FAQs: 'rain', 'picnic', 'payment', 'teen', 'safety', or 'all'",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["rain", "picnic", "payment", "teen", "safety", "all"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "FAQ list returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaqResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/quotes": {
      "post": {
        "operationId": "calculateQuote",
        "summary": "Calculate an event budget estimate and generate a WhatsApp booking link",
        "description": "Accepts party details and returns pricing guidance along with a direct WhatsApp booking link (+55 21 98826-9004).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote estimate calculated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing required party details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "status", "message", "resolution_hint"],
            "properties": {
              "code": {
                "type": "string",
                "example": "NOT_FOUND"
              },
              "status": {
                "type": "integer",
                "example": 404
              },
              "message": {
                "type": "string",
                "example": "The requested resource was not found."
              },
              "resolution_hint": {
                "type": "string",
                "example": "Review available endpoints at https://pipocando.org/openapi.json"
              }
            }
          }
        }
      },
      "ServicesListResponse": {
        "type": "object",
        "required": ["company", "city", "services"],
        "properties": {
          "company": {
            "type": "string",
            "example": "Pipocando Festas e Eventos"
          },
          "city": {
            "type": "string",
            "example": "Rio de Janeiro - RJ"
          },
          "services": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "name", "category", "durationHours", "targetAgeRange", "description"],
              "properties": {
                "id": { "type": "string", "example": "recreacao-tradicional" },
                "name": { "type": "string", "example": "Recreação Tradicional Infantil" },
                "category": { "type": "string", "example": "Recreação" },
                "durationHours": { "type": "integer", "example": 4 },
                "targetAgeRange": { "type": "string", "example": "0 a 7 anos" },
                "description": { "type": "string", "example": "4 horas com 2 recreadores, paraquedas gigante, cabo de guerra, corrida do saco, picnic e parabéns animado." }
              }
            }
          }
        }
      },
      "CombosListResponse": {
        "type": "object",
        "required": ["combos"],
        "properties": {
          "combos": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "name", "category", "duration", "inclusions"],
              "properties": {
                "id": { "type": "string", "example": "combo-recreacao-tradicional" },
                "name": { "type": "string", "example": "Pacote Recreação Tradicional • Promocional" },
                "category": { "type": "string", "example": "Recreação" },
                "duration": { "type": "string", "example": "4 Horas" },
                "inclusions": {
                  "type": "array",
                  "items": { "type": "string" },
                  "example": ["2 Recreadores Especializados", "Paraquedas Gigante", "Cabo de Guerra", "Picnic com Toalha Xadrez", "Parabéns Animado"]
                }
              }
            }
          }
        }
      },
      "AvailabilityResponse": {
        "type": "object",
        "required": ["serviceActive", "city", "status", "bookingNotice"],
        "properties": {
          "serviceActive": { "type": "boolean", "example": true },
          "city": { "type": "string", "example": "Rio de Janeiro" },
          "status": { "type": "string", "example": "available" },
          "bookingNotice": { "type": "string", "example": "Reservas devem ser confirmadas via WhatsApp oficial +55 21 98826-9004." }
        }
      },
      "FaqResponse": {
        "type": "object",
        "required": ["faqs"],
        "properties": {
          "faqs": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["question", "answer"],
              "properties": {
                "question": { "type": "string" },
                "answer": { "type": "string" }
              }
            }
          }
        }
      },
      "QuoteRequest": {
        "type": "object",
        "required": ["customerName", "eventDate", "neighborhood"],
        "properties": {
          "customerName": { "type": "string", "example": "Ana Maria" },
          "phone": { "type": "string", "example": "(21) 98888-7777" },
          "eventDate": { "type": "string", "format": "date", "example": "2026-10-15" },
          "neighborhood": { "type": "string", "example": "Barra da Tijuca" },
          "kidsCount": { "type": "integer", "example": 20 },
          "comboId": { "type": "string", "example": "combo-recreacao-tradicional" }
        }
      },
      "QuoteResponse": {
        "type": "object",
        "required": ["status", "summary", "whatsAppBookingUrl"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "summary": { "type": "string", "example": "Orçamento simulado para Recreação Infantil na Barra da Tijuca." },
          "whatsAppBookingUrl": { "type": "string", "example": "https://wa.me/5521988269004?text=..." }
        }
      }
    }
  }
}