{"openapi":"3.0.3","info":{"title":"K&C Realty Agent Gateway","version":"1.0.0","description":"Machine-readable Costa del Sol new-build property references, honest comparison data and a deterministic mortgage planning calculator. Unknown project facts remain null and require confirmation.","contact":{"name":"KRAFT & CHRISTENSEN REALTY","email":"hello@kcrealty.es"}},"servers":[{"url":"https://www.kcrealty.es/agents","description":"K&C production agent gateway"}],"paths":{"/properties.json":{"get":{"operationId":"searchProperties","summary":"Search current K&C property references","parameters":[{"name":"municipality","in":"query","schema":{"type":"string","enum":["Marbella","Estepona","Mijas Costa"]}},{"name":"property_type","in":"query","schema":{"type":"string","enum":["VILLA","PENTHOUSE","APARTMENT"]}},{"name":"min_price","in":"query","description":"Matches published starting prices only; listings whose price is not published are never matched by price filters.","schema":{"type":"number","minimum":0}},{"name":"max_price","in":"query","description":"Matches published starting prices only; listings whose price is not published are never matched by price filters.","schema":{"type":"number","minimum":0}},{"name":"min_bedrooms","in":"query","schema":{"type":"integer","minimum":0}},{"name":"max_handover_year","in":"query","description":"Listings without a published completion date are excluded when this filter is used.","schema":{"type":"integer","minimum":2026}},{"name":"advance_payment_protection_verified_only","in":"query","description":"Listings without independently verified project-specific protection are excluded.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Property result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertySearchResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"}}}},"/compare.json":{"get":{"operationId":"compareProperties","summary":"Compare up to six property references without filling unknown fields","parameters":[{"name":"property_ids","in":"query","description":"Comma-separated property_id values. If omitted, all live photographed references are compared.","schema":{"type":"string","example":"kc-est-example-1,kc-mar-example-2"}}],"responses":{"200":{"description":"Side-by-side comparison"},"400":{"$ref":"#/components/responses/ValidationError"},"404":{"description":"One or more property IDs were not found"}}}},"/faq.json":{"get":{"operationId":"getBuyerFaq","summary":"Get factual buyer and agent questions","responses":{"200":{"description":"Structured FAQ envelope"}}}},"/calculate-mortgage":{"post":{"operationId":"calculateMortgage","summary":"Calculate mortgage payments and a complete monthly amortization schedule","description":"Returns a mathematical planning estimate, not a lender decision. Construction interest is calculated only when a caller states that part of the mortgage is actually drawn during construction.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MortgageRequest"}}}},"responses":{"200":{"description":"Mortgage planning result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MortgageResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"413":{"description":"Request body exceeds 64 KiB"}}}},"/request-secure-upload":{"post":{"operationId":"requestSecureUpload","summary":"Request authenticated document instructions after a mortgage pre-check","description":"Accepts contact details and a pre-check reference only. It never accepts or stores documents.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email","phone","mortgage_precheck_reference"],"properties":{"name":{"type":"string","maxLength":120},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":60},"mortgage_precheck_reference":{"type":"string","maxLength":120}}}}}},"responses":{"202":{"description":"Human or mortgage-partner review requested; no documents received"},"400":{"$ref":"#/components/responses/ValidationError"},"503":{"description":"Secure workflow connection is unavailable"}}}},"/submit-documents":{"post":{"operationId":"submitDocumentsDisabled","summary":"Public sensitive-document uploads are disabled","description":"This endpoint intentionally rejects files. KYC, credit reports and proof of funds require an authenticated, partner-approved secure workflow.","responses":{"501":{"description":"PUBLIC_DOCUMENT_UPLOAD_DISABLED"}}}}},"components":{"responses":{"ValidationError":{"description":"Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"nullable":true}}},"request_id":{"type":"string","format":"uuid"}}},"Property":{"type":"object","required":["property_id","project_name","municipality","property_type","starting_price","currency","availability_status","payment_plan","advance_payment_protection","source_url"],"properties":{"property_id":{"type":"string"},"project_name":{"type":"string"},"developer":{"type":"string","nullable":true},"municipality":{"type":"string"},"country":{"type":"string","enum":["Spain"]},"property_type":{"type":"string"},"bedrooms":{"type":"integer"},"bathrooms":{"type":"integer"},"built_area_m2":{"type":"number","nullable":true,"description":"Whole m², rounded down. Read with built_area_basis."},"built_area_basis":{"type":"string","enum":["own","incl_communal"],"nullable":true,"description":"own = the unit's own built area; incl_communal = includes a share of communal areas (only when the own figure is not recorded)."},"built_area_label":{"type":"string","enum":["Built Size","Built Size (incl. communal areas)"],"nullable":true},"starting_price":{"type":"number","nullable":true,"description":"null when the price is not published (price on request); price_status is then NOT_PUBLISHED."},"currency":{"type":"string","enum":["EUR"]},"price_status":{"type":"string","enum":["INDICATIVE_CONFIRMATION_REQUIRED","NOT_PUBLISHED"]},"construction_status":{"type":"string","enum":["NOT_PUBLISHED"]},"completion_date":{"type":"string","format":"date","nullable":true},"availability_status":{"type":"string","enum":["CONFIRMATION_REQUIRED"]},"payment_plan":{"type":"object"},"advance_payment_protection":{"type":"object"},"source_url":{"type":"string","format":"uri"},"image_url":{"type":"string","format":"uri"},"data_quality":{"type":"object"}}},"PropertySearchResponse":{"type":"object","required":["schema_version","generated_at","request_id","count","currency","warnings","data"],"properties":{"schema_version":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"request_id":{"type":"string","format":"uuid"},"count":{"type":"integer"},"currency":{"type":"string","enum":["EUR"]},"filters_applied":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}},"data":{"type":"array","items":{"$ref":"#/components/schemas/Property"}}}},"MortgageRequest":{"type":"object","required":["property_price","down_payment_percent","interest_rate_percent","loan_term_years"],"properties":{"property_price":{"type":"number","minimum":50000,"maximum":100000000},"down_payment_percent":{"type":"number","minimum":10,"maximum":90},"interest_rate_percent":{"type":"number","minimum":0,"maximum":25},"loan_term_years":{"type":"integer","minimum":5,"maximum":30},"construction_phase_options":{"type":"object","properties":{"interest_only_during_construction":{"type":"boolean","default":false},"construction_period_months":{"type":"integer","minimum":0,"maximum":60,"default":0},"construction_draw_percent":{"type":"number","minimum":0,"maximum":100,"description":"Required when interest_only_during_construction is true."}}},"purchase_costs":{"type":"object","properties":{"purchase_cost_percent":{"type":"number","minimum":0,"maximum":25},"fixed_fees":{"type":"number","minimum":0,"maximum":1000000}}},"payment_plan":{"type":"object","properties":{"reservation_amount":{"type":"number","minimum":0},"milestones":{"type":"array","maxItems":24,"items":{"type":"object","required":["label","month","percentage_due"],"properties":{"label":{"type":"string"},"month":{"type":"integer","minimum":0,"maximum":120},"percentage_due":{"type":"number","minimum":0,"maximum":100}}}},"on_completion_percent":{"type":"number","minimum":0,"maximum":100}}}}},"MortgageResponse":{"type":"object","required":["request_id","calculation_version","currency","financing","construction_phase","purchase_payment_plan","costs","standard_amortization_schedule","decision_status","lender_decision_required"],"properties":{"request_id":{"type":"string","format":"uuid"},"calculation_version":{"type":"string"},"currency":{"type":"string","enum":["EUR"]},"financing":{"type":"object"},"construction_phase":{"type":"object"},"purchase_payment_plan":{"type":"object"},"costs":{"type":"object"},"standard_amortization_schedule":{"type":"array","items":{"type":"object","properties":{"payment_number":{"type":"integer"},"payment":{"type":"number"},"principal_repayment":{"type":"number"},"interest_repayment":{"type":"number"},"remaining_balance":{"type":"number"}}}},"decision_status":{"type":"string","enum":["PLANNING_ESTIMATE_ONLY"]},"lender_decision_required":{"type":"boolean","enum":[true]}}}}}}