{
  "openapi": "3.1.0",
  "info": {
    "title": "ПронерАвто — каталог услуг",
    "version": "1.0.0",
    "description": "Catalogue reading and an aggregate-only missing-service feedback endpoint. Preview includes draft services. null price/time means unknown. Booking links open the same CSRF-protected contact form used by people; no appointment slot or parts order is implied. Customer data is not exposed."
  },
  "externalDocs": {
    "description": "Инструкция для клиентских ИИ-агентов. Подбор автомобиля, форма обращения и границы данных.",
    "url": "/for-agents.md"
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "paths": {
    "/api/услуги/": {
      "get": {
        "operationId": "listServices",
        "summary": "List service categories and their operations",
        "responses": {
          "200": {
            "description": "Catalogue with preview flag and currency BYN",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "version",
                    "preview",
                    "currency",
                    "categories",
                    "booking_url"
                  ],
                  "properties": {
                    "version": {
                      "type": "string"
                    },
                    "preview": {
                      "type": "boolean"
                    },
                    "currency": {
                      "const": "BYN"
                    },
                    "booking_url": {
                      "type": "string"
                    },
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "title",
                          "services"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "summary": {
                            "type": "string"
                          },
                          "services": {
                            "type": "array",
                            "items": {
                              "$ref": "#/components/schemas/Service"
                            }
                          },
                          "body_text": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Public category description."
                          },
                          "meta_title": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "maxLength": 160
                          },
                          "meta_description": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "maxLength": 320
                          }
                        }
                      }
                    },
                    "business": {
                      "type": "object",
                      "description": "Verified public company identity, contact details and published working hours, represented as schema.org AutoRepair; no customer data."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/услуги/{slug}/": {
      "get": {
        "operationId": "getService",
        "summary": "Read one operation, work scope and price factors",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string"
                    },
                    "preview": {
                      "type": "boolean"
                    },
                    "service": {
                      "$ref": "#/components/schemas/Service"
                    },
                    "booking_url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Service is missing or unavailable to public catalogue"
          }
        }
      }
    },
    "/api/поиск-услуг/": {
      "post": {
        "operationId": "matchServiceIntent",
        "summary": "Match an automotive service request against the catalog",
        "description": "Accepts a short service name or task, not a customer conversation. Existing catalog entries are suggestions only: they do not confirm current workshop availability. Explicitly planned tire, balancing and alignment work is identified as planned. Unsupported, privacy-filtered automotive queries increment a short normalized phrase aggregate without VIN, contact, visitor, session or request identifiers.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/ServiceIntent"},
              "example": {"query": "замена масла в МКПП"}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Supported catalog matches, explicitly planned operation, or clarification suggestion",
            "headers": {
              "Cache-Control": {"schema": {"type": "string", "const": "no-store"}},
              "X-Robots-Tag": {"schema": {"type": "string", "const": "noindex, nofollow"}}
            },
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/ServiceIntentResult"}
              }
            }
          },
          "400": {
            "description": "Malformed or privacy-filtered request. The query was not recorded."
          },
          "415": {
            "description": "Only application/json is accepted."
          },
          "422": {
            "description": "Empty, overlong or unsupported request shape."
          },
          "429": {
            "description": "Rate limit exceeded. No query aggregate is written."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Service": {
        "type": "object",
        "required": [
          "slug",
          "category_slug",
          "title",
          "summary",
          "state",
          "path",
          "price_byn",
          "duration_minutes",
          "content"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "category_slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "draft",
              "published"
            ]
          },
          "path": {
            "type": "string"
          },
          "price_byn": {
            "type": [
              "number",
              "null"
            ],
            "description": "Starting labour price in BYN; null means unknown, zero is an explicitly entered zero price. Parts are separate. Not a supplier stock confirmation."
          },
          "duration_minutes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "content": {
            "type": "object",
            "properties": {
              "includes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "price_factors": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "faq": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "question": {
                      "type": "string"
                    },
                    "answer": {
                      "type": "string"
                    }
                  }
                }
              },
              "body": {
                "type": "string",
                "description": "Public service description as plain text; editorial source URLs and review notes are excluded."
              }
            }
          },
          "price_minor": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 999999999,
            "description": "The same starting labour price in integer BYN kopeks; use this field for money arithmetic."
          },
          "meta_title": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 160
          },
          "meta_description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 320
          }
        }
      },
      "ServiceIntent": {
        "type": "object",
        "additionalProperties": false,
        "required": ["query"],
        "properties": {
          "query": {
            "type": "string",
            "minLength": 2,
            "maxLength": 160,
            "description": "Short automotive service name or task only. Never send a VIN, customer name, phone, email, conversation or vehicle history."
          }
        }
      },
      "ServiceIntentResult": {
        "type": "object",
        "additionalProperties": false,
        "required": ["version", "status", "matches", "planned", "notice"],
        "properties": {
          "version": {"type": "string", "const": "1.0"},
          "status": {
            "type": "string",
            "enum": ["matched", "planned", "needs_clarification"]
          },
          "matches": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/Service"}
          },
          "planned": {
            "type": "array",
            "items": {"type": "string"}
          },
          "notice": {"type": "string"}
        }
      }
    }
  }
}