{
    "agentsJson": "0.1.0",
    "info": {
        "title": "PanWybierak.pl — przepływy dla agentów",
        "version": "1.0.0",
        "description": "Przepływy nad publicznym API PanWybierak.pl: sprawdzenie, którzy operatorzy obsługują konkretny adres w Polsce, i porównanie ich ofert internetu, telewizji, telefonu oraz pakietów. Adresy identyfikujemy kodami TERYT (`sym` dla miejscowości, `symul` dla ulicy), dlatego przepływy adresowe zaczynają się od wyszukania miejscowości. Dostępność liczy się per punkt adresowy: sama miejscowość daje oferty obecne gdziekolwiek w niej, dopiero ulica i numer budynku odpowiadają na pytanie „co dostanę u siebie”. Ceny są w złotówkach brutto i zmieniają się często — przy cytowaniu podawaj datę. Wszystko jest tylko do odczytu i bez uwierzytelnienia; zamówienia nie da się złożyć przez API i nie należy tego robić za użytkownika."
    },
    "sources": [
        {
            "id": "panwybierak_public_api",
            "path": "https://panwybierak.pl/api/public/v1/openapi.json"
        }
    ],
    "flows": [
        {
            "id": "find_offers_at_address_flow",
            "title": "Oferty pod konkretnym adresem",
            "description": "Pełna ścieżka adresowa: zamienia nazwę miejscowości i ulicy na kody TERYT, a potem zwraca oferty operatorów dostępne pod tym adresem. Wybieraj ten przepływ, gdy użytkownik podał ulicę — a najlepiej też numer budynku, bo operator potrafi obsługiwać jedną stronę ulicy, a drugiej nie. Gdy znasz tylko miejscowość, użyj find_offers_in_city_flow. Nazwy miejscowości się powtarzają: przy kilku trafieniach rozstrzygnij po polu nameWithCounty, zanim pójdziesz dalej.",
            "actions": [
                {
                    "id": "search_city",
                    "sourceId": "panwybierak_public_api",
                    "operationId": "searchCities"
                },
                {
                    "id": "search_street",
                    "sourceId": "panwybierak_public_api",
                    "operationId": "searchStreets"
                },
                {
                    "id": "find_offers",
                    "sourceId": "panwybierak_public_api",
                    "operationId": "findOffers"
                }
            ],
            "links": [
                {
                    "origin": { "actionId": null, "fieldPath": "parameters.city" },
                    "target": { "actionId": "search_city", "fieldPath": "parameters.q" }
                },
                {
                    "origin": { "actionId": "search_city", "fieldPath": "response.0.sym" },
                    "target": { "actionId": "search_street", "fieldPath": "parameters.citySym" }
                },
                {
                    "origin": { "actionId": null, "fieldPath": "parameters.street" },
                    "target": { "actionId": "search_street", "fieldPath": "parameters.q" }
                },
                {
                    "origin": { "actionId": "search_city", "fieldPath": "response.0.sym" },
                    "target": { "actionId": "find_offers", "fieldPath": "parameters.citySym" }
                },
                {
                    "origin": { "actionId": "search_street", "fieldPath": "response.0.symul" },
                    "target": { "actionId": "find_offers", "fieldPath": "parameters.streetSymul" }
                },
                {
                    "origin": { "actionId": null, "fieldPath": "parameters.number" },
                    "target": { "actionId": "find_offers", "fieldPath": "parameters.number" }
                },
                {
                    "origin": { "actionId": null, "fieldPath": "parameters.serviceId" },
                    "target": { "actionId": "find_offers", "fieldPath": "parameters.serviceId" }
                },
                {
                    "origin": { "actionId": null, "fieldPath": "parameters.limit" },
                    "target": { "actionId": "find_offers", "fieldPath": "parameters.limit" }
                },
                {
                    "origin": { "actionId": "find_offers", "fieldPath": "response.offers" },
                    "target": { "actionId": null, "fieldPath": "responses.offers" }
                },
                {
                    "origin": { "actionId": "find_offers", "fieldPath": "response.location" },
                    "target": { "actionId": null, "fieldPath": "responses.location" }
                }
            ],
            "fields": {
                "parameters": [
                    { "name": "city", "description": "Nazwa miejscowości albo jej fragment, np. „Warszawa”.", "required": true, "type": "string" },
                    { "name": "street", "description": "Nazwa ulicy albo jej fragment, bez typu („Marszałkowska”, nie „ul. Marszałkowska”).", "required": true, "type": "string" },
                    { "name": "number", "description": "Numer budynku, np. „12A”. Bez niego wynik obejmuje całą ulicę.", "required": false, "type": "string" },
                    { "name": "serviceId", "description": "Ogranicza wynik do kategorii usług — identyfikator z list_services_flow.", "required": false, "type": "integer" },
                    { "name": "limit", "description": "Maksymalna liczba ofert w odpowiedzi (domyślnie 20, najwyżej 50).", "required": false, "type": "integer" }
                ],
                "responses": {
                    "success": {
                        "description": "Rozpoznany adres (location) oraz oferty operatorów dostępne pod nim: cena miesięczna, opłata aktywacyjna, okres umowy, parametry, adres strony oferty i formularza zamówienia."
                    }
                }
            }
        },
        {
            "id": "find_offers_in_city_flow",
            "title": "Oferty w miejscowości",
            "description": "Skrócona ścieżka dla pytań bez ulicy: zamienia nazwę miejscowości na kod TERYT i zwraca oferty obecne gdziekolwiek w tej miejscowości. Wynik jest orientacyjny — mówi, czego w ogóle można się tam spodziewać, a nie co jest dostępne pod danym budynkiem. Gdy użytkownik zna ulicę, sięgnij po find_offers_at_address_flow.",
            "actions": [
                {
                    "id": "search_city",
                    "sourceId": "panwybierak_public_api",
                    "operationId": "searchCities"
                },
                {
                    "id": "find_offers",
                    "sourceId": "panwybierak_public_api",
                    "operationId": "findOffers"
                }
            ],
            "links": [
                {
                    "origin": { "actionId": null, "fieldPath": "parameters.city" },
                    "target": { "actionId": "search_city", "fieldPath": "parameters.q" }
                },
                {
                    "origin": { "actionId": "search_city", "fieldPath": "response.0.sym" },
                    "target": { "actionId": "find_offers", "fieldPath": "parameters.citySym" }
                },
                {
                    "origin": { "actionId": null, "fieldPath": "parameters.serviceId" },
                    "target": { "actionId": "find_offers", "fieldPath": "parameters.serviceId" }
                },
                {
                    "origin": { "actionId": null, "fieldPath": "parameters.limit" },
                    "target": { "actionId": "find_offers", "fieldPath": "parameters.limit" }
                },
                {
                    "origin": { "actionId": "find_offers", "fieldPath": "response.offers" },
                    "target": { "actionId": null, "fieldPath": "responses.offers" }
                }
            ],
            "fields": {
                "parameters": [
                    { "name": "city", "description": "Nazwa miejscowości albo jej fragment.", "required": true, "type": "string" },
                    { "name": "serviceId", "description": "Ogranicza wynik do kategorii usług — identyfikator z list_services_flow.", "required": false, "type": "integer" },
                    { "name": "limit", "description": "Maksymalna liczba ofert w odpowiedzi (domyślnie 20, najwyżej 50).", "required": false, "type": "integer" }
                ],
                "responses": {
                    "success": {
                        "description": "Oferty obecne w tej miejscowości. Dostępność pod konkretnym budynkiem trzeba potwierdzić przepływem adresowym."
                    }
                }
            }
        },
        {
            "id": "get_offer_details_flow",
            "title": "Szczegóły oferty",
            "description": "Pełne dane pojedynczej oferty po jej identyfikatorze: cena miesięczna i sprzed promocji, opłata aktywacyjna, okres umowy, parametry, adres strony oferty oraz formularza zamówienia. Identyfikator bierze się z przepływów ofertowych. Formularz zamówienia wypełnia człowiek — oddaj użytkownikowi orderUrl zamiast go wysyłać.",
            "actions": [
                {
                    "id": "get_offer",
                    "sourceId": "panwybierak_public_api",
                    "operationId": "getOffer"
                }
            ],
            "links": [
                {
                    "origin": { "actionId": null, "fieldPath": "parameters.offerId" },
                    "target": { "actionId": "get_offer", "fieldPath": "parameters.id" }
                },
                {
                    "origin": { "actionId": "get_offer", "fieldPath": "response" },
                    "target": { "actionId": null, "fieldPath": "responses.offer" }
                }
            ],
            "fields": {
                "parameters": [
                    { "name": "offerId", "description": "Identyfikator oferty z find_offers_at_address_flow lub find_offers_in_city_flow.", "required": true, "type": "integer" }
                ],
                "responses": {
                    "success": { "description": "Pełne dane oferty wraz z adresem strony i formularza zamówienia." }
                }
            }
        },
        {
            "id": "list_services_flow",
            "title": "Kategorie usług",
            "description": "Drzewo kategorii usług (internet, telewizja, telefon, pakiety łączone) wraz z identyfikatorami do zawężania przepływów ofertowych parametrem serviceId.",
            "actions": [
                {
                    "id": "list_services",
                    "sourceId": "panwybierak_public_api",
                    "operationId": "getServices"
                }
            ],
            "links": [
                {
                    "origin": { "actionId": "list_services", "fieldPath": "response" },
                    "target": { "actionId": null, "fieldPath": "responses.services" }
                }
            ],
            "fields": {
                "parameters": [],
                "responses": {
                    "success": { "description": "Kategorie usług z identyfikatorami i adresami stron." }
                }
            }
        },
        {
            "id": "list_vendors_flow",
            "title": "Operatorzy",
            "description": "Lista operatorów obecnych w porównywarce wraz z adresami ich profili. Sama obecność operatora na liście nie znaczy, że obsługuje dany adres — to sprawdzają przepływy ofertowe.",
            "actions": [
                {
                    "id": "list_vendors",
                    "sourceId": "panwybierak_public_api",
                    "operationId": "getVendors"
                }
            ],
            "links": [
                {
                    "origin": { "actionId": "list_vendors", "fieldPath": "response" },
                    "target": { "actionId": null, "fieldPath": "responses.vendors" }
                }
            ],
            "fields": {
                "parameters": [],
                "responses": {
                    "success": { "description": "Operatorzy z identyfikatorami i adresami profili." }
                }
            }
        },
        {
            "id": "search_articles_flow",
            "title": "Szukaj poradników",
            "description": "Szuka na blogu poradników i artykułów po frazie. Przydatne przy pytaniach ogólnych („czym różni się światłowód od LTE”, „na co uważać w umowie”), a nie o dostępność pod adresem.",
            "actions": [
                {
                    "id": "search_articles",
                    "sourceId": "panwybierak_public_api",
                    "operationId": "searchArticles"
                }
            ],
            "links": [
                {
                    "origin": { "actionId": null, "fieldPath": "parameters.query" },
                    "target": { "actionId": "search_articles", "fieldPath": "parameters.q" }
                },
                {
                    "origin": { "actionId": null, "fieldPath": "parameters.limit" },
                    "target": { "actionId": "search_articles", "fieldPath": "parameters.limit" }
                },
                {
                    "origin": { "actionId": "search_articles", "fieldPath": "response" },
                    "target": { "actionId": null, "fieldPath": "responses.articles" }
                }
            ],
            "fields": {
                "parameters": [
                    { "name": "query", "description": "Szukana fraza, co najmniej dwa znaki.", "required": true, "type": "string" },
                    { "name": "limit", "description": "Maksymalna liczba artykułów (domyślnie 10, najwyżej 50).", "required": false, "type": "integer" }
                ],
                "responses": {
                    "success": { "description": "Artykuły z tytułem, adresem, zajawką i datą publikacji." }
                }
            }
        }
    ]
}