{
  "openapi": "3.1.0",
  "info": {
    "title": "NaceniTo.cz – AI Agent & Inquiry Creation API",
    "version": "1.0.0",
    "description": "Oficiální OpenAPI 3.1 specifikace pro přímé vytváření a nacenění poptávek řemeslníků, stavebních firem a brigádníků v České republice přes portál NaceniTo.cz (provozovatel hkcloud.cz). Umožňuje AI asistentům (ChatGPT Custom GPTs, Google Gemini Extensions, Claude, Perplexity) vytvořit poptávku přímo v databázi nebo vygenerovat předvyplněný potvrzovací odkaz.",
    "contact": {
      "name": "NaceniTo.cz (hkcloud.cz)",
      "url": "https://nacenito.cz"
    }
  },
  "servers": [
    {
      "url": "https://nacenito.cz",
      "description": "Hlavní produkční doména NaceniTo.cz"
    },
    {
      "url": "https://europe-west1-hk-software-c5e52.cloudfunctions.net",
      "description": "Přímý Cloud Functions server (europe-west1)"
    }
  ],
  "paths": {
    "/api/v1/inquiries": {
      "get": {
        "operationId": "getInquiryCatalogAndInstructions",
        "summary": "Získat seznam 67 kategorií řemesel a instrukce pro vytvoření poptávky",
        "description": "Vrátí přehled všech podporovaných kódů oborů (categories) a návod pro vytvoření poptávky na NaceniTo.cz.",
        "responses": {
          "200": {
            "description": "Katalog oborů a instrukce"
          }
        }
      },
      "post": {
        "operationId": "createCraftsmanInquiry",
        "summary": "Vytvořit novou poptávku řemeslníka nebo stavební firmy na NaceniTo.cz",
        "description": "Vytvoří poptávku na NaceniTo.cz jménem uživatele. Pokud jsou předány kontaktní údaje (clientPhone nebo clientEmail), poptávka se okamžitě uloží a zveřejní v databázi NaceniTo.cz. Pokud kontakt chybí, vrátí předvyplněný odkaz (actionUrl), kde uživatel jedním kliknutím doplní telefon a poptávku odešle.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "Stručný název zakázky, např. 'Rekonstrukce koupelny 6 m2 a rozvody vody v Brně'"
                  },
                  "description": {
                    "type": "string",
                    "description": "Podrobný popis poptávaných prací, rozsahu a požadavků klienta"
                  },
                  "prompt": {
                    "type": "string",
                    "description": "Přirozený popis od uživatele, pokud ještě nejsou rozděleny title a description"
                  },
                  "categories": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Pole kódů kategorií (např. ['bathroom', 'plumbing', 'electrical'])"
                  },
                  "subTasks": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Konkrétní požadované úkony"
                  },
                  "scaleSummary": {
                    "type": "string",
                    "description": "Stručný odhad rozsahu (např. 'Byt 3+1, cca 75 m2')"
                  },
                  "city": {
                    "type": "string",
                    "description": "Město nebo obec realizace v ČR (např. 'Praha', 'Brno', 'Ostrava')"
                  },
                  "zip": {
                    "type": "string",
                    "description": "PSČ místa realizace (např. '60200')"
                  },
                  "street": {
                    "type": "string",
                    "description": "Ulice a orientační číslo (volitelné)"
                  },
                  "urgency": {
                    "type": "string",
                    "enum": ["urgent", "within_month", "flexible"],
                    "description": "Naléhavost realizace"
                  },
                  "expectedDate": {
                    "type": "string",
                    "description": "Požadovaný termín realizace slovně (např. 'Do 1 měsíce')"
                  },
                  "estimatedBudget": {
                    "type": "string",
                    "description": "Orientační rozpočet (např. '150 000 Kč' nebo 'Dle dohody / nabídek')"
                  },
                  "clientName": {
                    "type": "string",
                    "description": "Jméno a příjmení zákazníka"
                  },
                  "clientPhone": {
                    "type": "string",
                    "description": "Telefonní číslo zákazníka (pokud je vyplněno, poptávka se přímo zveřejní v databázi)"
                  },
                  "clientEmail": {
                    "type": "string",
                    "description": "E-mailová adresa zákazníka"
                  },
                  "agentName": {
                    "type": "string",
                    "description": "Název AI asistenta (např. 'ChatGPT', 'Gemini', 'Claude')"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Poptávka byla přímo uložena a zveřejněna v databázi NaceniTo.cz"
          },
          "200": {
            "description": "Vrácen předvyplněný odkaz (actionUrl) pro potvrzení kontaktu uživatelem"
          }
        }
      }
    }
  }
}