tag: BETA

Este webservice se utiliza para enviar una solicitud de comercialización de propiedad de vendedor desde aplicaciones móviles. Permite a los propietarios enviar sus propiedades para venta o alquiler con información detallada y adjuntos opcionales (imágenes y PDFs).

URL del recurso

https://mapaprop.app/api/action/express-v1/seller-submissions

Autenticación

Este endpoint requiere autenticación OAuth2. Debés incluir un Bearer token válido en el encabezado Authorization.

Authorization: Bearer {your-oauth2-token}

El customerId se extrae automáticamente del token autenticado. No lo incluyas en el cuerpo de la solicitud.

Parámetros

Parámetros requeridos

Parámetros opcionales - Información de contacto

Parámetros opcionales - Detalles de la propiedad

Parámetros opcionales - Adjuntos de archivos

Parámetros opcionales - Metadatos de la app móvil

Formato de subida de archivos

Las imágenes y PDFs deben subirse como Data URLs codificadas en Base64:

Formato de imagen:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ...

Formato PDF:

data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsKBw4XDqsOPDQoxIDAgb2Jq...

Tipos de imagen admitidos:

• image/jpeg
• image/png
• image/gif
• image/webp

Límites de tamaño de archivo:

• Máximo por archivo: 2MB
• Máximo de bandwidth total: 10MB por hora

Seguridad:

• Los archivos se validan usando validación por número mágico (no solo el MIME type)
• Todos los archivos se escanean para detectar amenazas de seguridad
• Los archivos se suben a almacenamiento seguro en S3

Ejemplo de solicitud

POST /api/action/express-v1/seller-submissions HTTP/1.1
Host: mapaprop.app
Content-Type: application/json
Authorization: Bearer {access_token}

{
    "websiteId": 869,
    "name": "Juan Carlos Rodriguez",
    "email": "juan.rodriguez@gmail.com",
    "phone": "+54 11 4567-8901",
    "contactHours": "Lunes a Viernes de 9 a 18hs",
    "propertyType": "Casa",
    "propertyOperation": "Venta",
    "propertyAddress": "Av. Corrientes 1234",
    "propertyZone": "Barrio Norte",
    "propertyLandArea": "250",
    "propertyBuildingArea": "180",
    "propertyPrice": "150000000",
    "propertyCurrency": "ARS",
    "propertyRooms": "3",
    "propertyBathrooms": "2",
    "propertyDescription": "Hermosa casa de 3 plantas con jardín y garage.",
    "propertyListed": "false",
    "propertyValuation": "true",
    "image": "data:image/png;base64,iVBORw0KGgo...",
    "pdf": "data:application/pdf;base64,JVBERi0xLjQ...",
    "platform": "iOS",
    "appVersion": "2.5.1",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)",
    "ip": "181.47.123.45",
    "referer": "https://www.mapaprop.com/publicar-propiedad",
    "domain": "www.mapaprop.com",
    "url": "https://www.mapaprop.com/publicar-propiedad/formulario"
}

Respuesta

La respuesta JSON indica si el envío del vendedor fue exitoso y provee detalles del contacto creado.

Respuesta exitosa

Respuesta de error

Ejemplo de respuesta - Éxito

{
    "error": false,
    "message": "Seller commercialization request submitted successfully",
    "contactId": 1065875,
    "websiteId": 869,
    "processingTimeMs": 5215
}

Ejemplos de respuesta - Errores

Pertenencia inválida del sitio web:

{
    "error": true,
    "message": "Website not found or does not belong to customer",
    "code": "NOT_FOUND"
}

Límite de tasa superado:

{
    "error": true,
    "message": "Too many seller submissions. Please try again later.",
    "code": "RATE_LIMIT_EXCEEDED"
}

Formato de archivo inválido:

{
    "error": true,
    "message": "Invalid file format. Only JPEG, PNG, GIF, WebP images and PDF documents are allowed.",
    "code": "INVALID_FILE"
}

Campo requerido faltante:

{
    "error": true,
    "message": "Name is required and must be between 3 and 100 characters",
    "code": "INVALID_INPUT"
}

Spam detectado:

{
    "error": true,
    "message": "Spam detected",
    "code": "SPAM_DETECTED"
}

Límite de tasa

Este endpoint tiene límite de tasa para prevenir abusos:

• Límite de solicitudes: 10 solicitudes por hora por cliente
• Límite de bandwidth: 10MB por hora por cliente

Cuando se supera el límite de tasa, recibirás:

{
    "error": true,
    "message": "Too many seller submissions. Please try again later.",
    "code": "RATE_LIMIT_EXCEEDED"
}

Funcionalidades de seguridad

Detección de spam

Todos los envíos se verifican contra spam usando la integración con Akismet en el entorno de producción. Los envíos marcados como spam se registran pero no se bloquean automáticamente.

Seguridad de archivos

• Validación por número mágico: Los archivos se validan por su contenido real, no solo por el MIME type
• Límites de tamaño de archivo: 2MB por archivo, 10MB de bandwidth total por hora
• Formatos admitidos: Solo se aceptan formatos de imagen y PDF incluidos en la lista de permitidos
• Almacenamiento seguro: Los archivos se suben a buckets S3 cifrados

Validación de entrada

• Todos los campos de texto se sanitizan y validan
• Las direcciones de email deben tener formato RFC válido
• Los números de teléfono se validan por formato
• Prevención de inyección SQL mediante sentencias preparadas
• Prevención de XSS mediante escape de plantillas

Qué ocurre después del envío

1. Creación de contacto: Se crea un nuevo contacto en el CRM con tipo "SELLER"
2. Almacenamiento de archivos: Las imágenes y PDFs se suben a almacenamiento seguro en S3
3. Notificación por email: Se encola un email (via SQS) y se envía al cliente con:
   • Todos los detalles de la propiedad
   • Archivos adjuntos (imagen y PDF)
   • Información de contacto
   • Metadatos del envío (plataforma, versión de app, timestamp)
4. Estadísticas: El evento se registra con metadatos detallados para analítica
5. Registro de auditoría: Se crea un registro de auditoría completo para cumplimiento normativo

Códigos de error

Buenas prácticas

1. Siempre incluí el token OAuth2: El endpoint requiere autenticación
2. Validá del lado del cliente: Verificá los campos requeridos antes de enviar
3. Comprimí las imágenes: Optimizá las imágenes antes de codificarlas en Base64 para mantenerte bajo el límite de 2MB
4. Manejá los límites de tasa: Implementá backoff exponencial si recibís rate limit
5. Registrá la versión de la app: Siempre enviá platform y appVersion para analítica
6. Proporcioná la IP real: Enviá la IP real del usuario para mayor precisión en la detección de spam
7. Usá HTTPS: Siempre usá conexión segura en producción

Notas de integración

• customerId es automático: No incluyas customerId en el cuerpo de la solicitud; se extrae del token OAuth2
• Pertenencia del websiteId: El endpoint valida que el websiteId pertenece al cliente autenticado
• DEV vs PROD: La detección de spam se omite en el entorno de desarrollo pero está activa en producción
• Redirección de email en DEV: En desarrollo, los emails se redirigen a info@mapaprop.com en vez del email del cliente

Documentación relacionada

Para ver el flujo completo de cómo funciona la captación de propiedades en el sistema, consultá:

Captación de Propiedades - Vender (Flujo Práctico)

Historial de versiones

Versión de API: 1.0 Última actualización: 2025-10-22 Estado: Listo para producción