{"openapi":"3.1.0","info":{"title":"Valia API","version":"1.0.0","description":"API de valuación inmobiliaria. Autenticación por header x-valiacion-key."},"servers":[{"url":"/","description":"Same origin as this document."}],"components":{"securitySchemes":{"ValiacionKey":{"type":"apiKey","in":"header","name":"x-valiacion-key"}}},"security":[{"ValiacionKey":[]}],"paths":{"/api/geocode/search":{"post":{"operationId":"buscar-lugares","summary":"Buscar lugares","description":"Primer paso del flujo: convierte una dirección escrita en candidatos geocodificados. Elige la dirección y las coordenadas de un resultado para armar Generar valuación.","security":[{"ValiacionKey":[]}],"parameters":[{"name":"content-type","in":"header","required":true,"description":"Por defecto application/json.","schema":{"type":"string","description":"Por defecto application/json."}}],"responses":{"200":{"description":"Candidatos encontrados. candidates con placeId, formattedAddress, center y googleMapsUri.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Entrada inválida."},"401":{"description":"Sin x-valiacion-key, o clave inválida."},"402":{"description":"Créditos insuficientes."},"429":{"description":"Límite horario de geocode (60)."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Dirección a buscar. direction es un alias aceptado."}},"required":["address"]}}}}}},"/api/valiacion":{"post":{"operationId":"crear-valuacion","summary":"Generar valuación","description":"Publica la valuación con los datos del inmueble y las coordenadas del lugar elegido. No envíes currency ni postedCurrency: el motor valúa en USD. Con clave de cliente, la respuesta indica si se conservó el crédito.","security":[{"ValiacionKey":[]}],"parameters":[{"name":"content-type","in":"header","required":true,"description":"Por defecto application/json.","schema":{"type":"string","description":"Por defecto application/json."}},{"name":"idempotency-key","in":"header","required":true,"description":"Obligatoria en cliente. Máximo 200 caracteres. Un conflicto da 409.","schema":{"type":"string","description":"Obligatoria en cliente. Máximo 200 caracteres. Un conflicto da 409."}}],"responses":{"200":{"description":"Valuación publicada. Con clave de cliente, billed es true cuando se conservó el crédito. dashboardUrl, snapshot, billed","content":{"application/json":{"schema":{"type":"object","properties":{"billed":{"type":"boolean"},"dashboardUrl":{"type":"string"},"snapshot":{"type":"object","additionalProperties":true}},"required":["billed","dashboardUrl","snapshot"]}}}},"400":{"description":"JSON inválido, issues, o falta idempotency-key"},"401":{"description":"Sin x-valiacion-key, o clave inválida"},"402":{"description":"Créditos insuficientes"},"409":{"description":"idempotency-key choca con otra petición"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Dirección resuelta. Elige un lugar geocodificado, no un texto libre."},"latitude":{"type":"number","description":"Latitud del pin. Viene de geocodificar, no se inventa a mano."},"longitude":{"type":"number","description":"Longitud del pin. Viene de geocodificar, no se inventa a mano."},"operation":{"type":"string","description":"Venta o Alquiler. Amoblado solo aplica a Alquiler.","enum":["Venta","Alquiler"]},"listingType":{"type":"string","description":"Tipo de inmueble. Cambia qué áreas y habitaciones son obligatorias: Departamentos, Casas, Terrenos, Oficinas, Locales Comerciales.","enum":["Departamentos","Casas","Terrenos","Oficinas","Locales Comerciales"]},"listingTypeDetail":{"type":"string","description":"Detalle del tipo. Obligatorio como string. Vacío salvo Departamentos."},"age":{"type":"integer","description":"Antigüedad en años. Entero de 0 a 250. 0 usa la edad matemática interna."},"radiusM":{"type":"number","description":"Radio de comparables en metros. Si omites, usa el default del motor. Permitidos: 300, 500.","enum":[300,500]},"furnished":{"type":"boolean","description":"Solo Alquiler. true, false o ausente. En Venta no lo envíes."},"totalArea":{"type":"number","description":"Área total en m². Siempre positivo."},"builtArea":{"type":"number","description":"Área construida en m². Obligatoria en Departamentos y Casas."},"landArea":{"type":"number","description":"Área de terreno en m². Obligatoria en Terrenos y Casas."},"bedrooms":{"type":"integer","description":"Habitaciones. Obligatorio 1 a 5 en Departamentos. No lo envíes en Terrenos."}},"required":["address","latitude","longitude","operation","listingType","listingTypeDetail","age","totalArea"]}}}}}},"/api/valiacion/{id}":{"get":{"operationId":"obtener-valuacion","summary":"Obtener valuación","description":"Recupera el resultado de una valuación ya publicada. La respuesta es el objeto snapshot directamente, sin un envoltorio extra.","security":[{"ValiacionKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"UUID de la valuación en la ruta.","schema":{"type":"string","description":"UUID de la valuación en la ruta."}}],"responses":{"200":{"description":"Snapshot publicado. Objeto snapshot (status valued o insufficient-data).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Sin x-valiacion-key, o clave inválida."},"404":{"description":"Valuación no encontrada."}}}}}}