Glosario y Estados

Esta guía es tu

diccionario de referencia para entender todos los términos y estados que encontrarás al usar Place Analyzer API.

📚 Glosario de Términos

Identificadores

`requestCode`

Definición: Identificador único de una solicitud de avalúo
Formato: Cadena alfanumérica (ej: abc-123-xyz-456)
Propósito: Rastrear y consultar el estado de un avalúo específico
Duración: Permanente, nunca se reutiliza
Uso: Obtener resultados, consultar estado y reintentar avalúos

// Ejemplo de uso
const requestCode = "abc-123-xyz-456";
const statusUrl = `/valuation-request/${requestCode}`;
const resultUrl = `/valuation-request/${requestCode}/result`;

Ubicación

`latitude`, `longitude`

Definición: Coordenadas geográficas de la propiedad
Formato: Números decimales con hasta 6 decimales
Rango: latitude (-90 a 90), longitude (-180 a 180)
Precisión: 6 decimales ≈ 10 cm de precisión
Uso: Especificar ubicación exacta de la propiedad

// Buenos Aires, Argentina
{
  "latitude": -34.603722,
  "longitude": -58.381592
}

Campos requeridos

latitude y longitude son campos obligatorios para crear una solicitud de avalúo.

Propiedad

`propertyType`

Definición: Tipo de propiedad según uso principal
Ubicación: Dentro del objeto property
Valores válidos:
- Terreno: Terreno baldío
- Casa: Casa unifamiliar
- Duplex: Duplex
- Departamento: Departamento en edificio
- Deposito: Depósito
- Tinglado: Tinglado
- Oficina: Oficina
- Local Comercial: Local comercial
- Propiedad rural: Propiedad rural
- Casa quinta: Casa quinta
- Edificio: Edificio completo
Impacto: Afecta el modelo de tasación y comparables
Requerido: ✅ Sí

`propertyAge`

Definición: Antigüedad del inmueble
Ubicación: Dentro del objeto property
Valores válidos:
- En pozo: En construcción/pozo
- Nuevo: Nuevo o a estrenar
- Semi nuevo: Semi nuevo
- Medio: Antigüedad media
- Antiguo: Antiguo
Requerido: Según propertyType (Departamento y demás tipos; no exigido para Terreno)

`propertyCondition`

Definición: Estado de conservación de la propiedad
Ubicación: Dentro del objeto property
Valores válidos:
- Excelente: Excelente estado
- Bueno: Buen estado
- Regular: Estado regular
- Malo: Mal estado
Requerido: Según propertyType (demás tipos; no exigido para Terreno ni Departamento)

`m2Land` (Metros cuadrados de terreno)

Definición: Área total del terreno en metros cuadrados
Ubicación: Dentro del objeto property
Validación: Debe ser >= 0
Requerido: Según propertyType (Terreno y demás tipos; no exigido para Departamento)
Ejemplo: Casa con 300 m² de terreno
Uso: Valor del terreno y regulaciones urbanas

`m2Built` (Metros cuadrados construidos)

Definición: Área construida en metros cuadrados
Ubicación: Dentro del objeto property
Validación: Debe ser >= 0
Requerido: Según propertyType (demás tipos; no exigido para Terreno ni Departamento)
Ejemplo: Casa con 200 m² construidos
Uso: Valor de la construcción

`m2Covered` (Metros cuadrados cubiertos)

Definición: Área cubierta en metros cuadrados
Ubicación: Dentro del objeto property
Validación: Debe ser >= 0
Requerido: Según propertyType (requerido para Departamento)
Ejemplo: Departamento con 80 m² cubiertos

`m2SemiCovered` (Metros cuadrados semicubiertos)

Definición: Área semicubierta en metros cuadrados
Ubicación: Dentro del objeto property
Validación: Debe ser >= 0
Requerido: Según propertyType (requerido para Departamento)
Ejemplo: Departamento con 10 m² semicubiertos

Valores de Tasación

`priceLand`

Definición: Valor estimado del terreno
Moneda: Especificada en currency
Componente: Solo el valor del terreno
Ejemplo: 150000.00 (USD)
Disponible en: Endpoint /result

`priceBuild`

Definición: Valor estimado de la construcción
Moneda: Especificada en currency
Componente: Solo el valor de lo construido
Ejemplo: 200000.00 (USD)
Disponible en: Endpoint /result

Calcular valor total

El valor total de la propiedad se calcula sumando ambos valores:

const totalValue = priceLand + priceBuild;
// 150000 + 200000 = 350000 USD

`currency`

Definición: Moneda de la tasación
Valor disponible: USD
Uso: Interpretar correctamente los valores
Formato: Código ISO 4217

`mlModelCode`

Definición: Código del modelo de machine learning utilizado
Formato: Cadena alfanumérica (ej: V1)
Propósito: Trazabilidad del modelo de tasación
Uso: Referencia técnica

🔄 Estados del Ciclo de Vida

Los avalúos pasan por diferentes estados durante su procesamiento:

Estados de Solicitud

`CREATED`

Definición: Solicitud recibida, en cola para procesar
¿Resultado disponible?: ❌ No
Tiempo típico: 0-30 segundos
Acción recomendada: Esperar y consultar estado (polling cada 5-10 segundos)

`READY`

Definición: Tasación finalizada exitosamente
¿Resultado disponible?: ✅ Sí
Tiempo típico: N/A (estado final)
Acción recomendada: Obtener resultado con GET /valuation-request/{requestCode}/result

`ERROR_VALUATION`

Definición: Error durante el procesamiento
¿Resultado disponible?: ❌ No
Causa común: Datos insuficientes, coordenadas inválidas, zona sin cobertura o servicio temporalmente no disponible.
Acción recomendada:
1. Revisar failedMessage para entender el error
2. Crear nueva solicitud con datos corregidos

Tabla resumen de estados

Estado	Descripción	Resultado	Acción
`CREATED`	En cola	❌	Polling
`READY`	Completado	✅	Obtener resultado
`ERROR_VALUATION`	Error	❌	Nueva solicitud

🚨 Códigos de Error

Principales categorías:

Validación (`400 Bad Request`)

Datos faltantes o inválidos
Formato incorrecto
Valores fuera de rango

{
  "error": "VALIDATION_ERROR",
  "message": "El campo property.propertyType es requerido"
}

Autenticación (`401 Unauthorized`)

INVALID_API_KEY: API Key incorrecta
MISSING_API_KEY: Falta API Key en header
API_KEY_EXPIRED: API Key vencida

Recursos (`404 Not Found`)

REQUEST_NOT_FOUND: requestCode no existe
RESULT_NOT_AVAILABLE: Avalúo no está READY

Rate Limiting (`429 Too Many Requests`)

RATE_LIMIT_EXCEEDED: Límite de peticiones excedido

Campo `failedMessage`

Cuando un avalúo tiene estado ERROR_VALUATION, el campo failedMessage contiene información sobre el error:

{
  "requestCode": "abc-123-xyz-456",
  "status": "ERROR_VALUATION",
  "failedMessage": "No se encontraron suficientes comparables en la zona"
}

📊 Estructura de Datos Principal

Request (CreateValuationInput)

{
  "latitude": -34.603722,      // Requerido
  "longitude": -58.381592,     // Requerido
  "property": {                // Requerido
    "propertyType": "Casa",       // Requerido
    "propertyAge": "Semi nuevo", // Requerido para Casa (y demás tipos / Departamento)
    "propertyCondition": "Bueno",   // Requerido para Casa (y demás tipos)
    "m2Land": 300,                 // Requerido para Casa (y Terreno / demás tipos)
    "m2Built": 200,                // Requerido para Casa (y demás tipos)
    // m2Covered / m2SemiCovered: requeridos para Departamento
    // ... más campos opcionales
  }
}

Response de creación (CreateValuationOutputRestDto)

{
  "id": 12345,
  "requestCode": "abc-123-xyz-456",
  "requestDate": "2025-01-15T10:30:00Z",
  "status": "CREATED"
}

Response de resultado (ValuationResultResponseDto)

{
  "requestCode": "abc-123-xyz-456",
  "requestDate": "2025-01-15T10:30:00Z",
  "status": "READY",
  "currency": "USD",
  "mlModelCode": "V1",
  "priceLand": 150000.00,
  "priceBuild": 200000.00
}

Conclusión

Este glosario cubre los términos esenciales para trabajar con Place Analyzer API:

✅ Conceptos clave:

requestCode para rastrear avalúos
Estados del ciclo de vida (CREATED → READY)
Estructura del objeto property con campos requeridos

✅ Valores de tasación:

priceLand: Valor del terreno
priceBuild: Valor de la construcción
Total = priceLand + priceBuild

✅ Mejores prácticas:

Validar campos requeridos antes de enviar
Implementar polling para estados asíncronos (cada 5-10 segundos)
Manejar errores apropiadamente

¿Falta algún término? Consulta la

referencia completa de API o guía de manejo de errores.

📚 Glosario de Términos

Identificadores

requestCode

Ubicación

latitude, longitude

Propiedad

propertyType

propertyAge

propertyCondition

m2Land (Metros cuadrados de terreno)

m2Built (Metros cuadrados construidos)

m2Covered (Metros cuadrados cubiertos)

m2SemiCovered (Metros cuadrados semicubiertos)