tag: BETA

Este webservice é usado para enviar uma solicitação de comercialização de imóvel de vendedor a partir de aplicações móveis. Permite que proprietários enviem seus imóveis para venda ou locação com informações detalhadas e anexos opcionais (imagens e PDFs).

A solicitação do proprietário fica registrada na conta Mapaprop da imobiliária (a dona do token): é salva como contato no CRM e a imobiliária é notificada por e-mail com os anexos. A conta de destino é resolvida a partir do token, não é enviada como parâmetro.

URL do recurso

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

Autenticação

Este endpoint requer autenticação OAuth2. Você deve incluir um Bearer token válido no cabeçalho Authorization.

Authorization: Bearer {your-oauth2-token}

O customerId é extraído automaticamente do token autenticado. Não o inclua no corpo da requisição.

Parâmetros

Parâmetros obrigatórios

Parâmetros opcionais - Informações de contato

Parâmetros opcionais - Detalhes do imóvel

Parâmetros opcionais - Anexos de arquivos

Parâmetros opcionais - Metadados do app móvel

Formato de upload de arquivos

Imagens e PDFs devem ser enviados como Data URLs codificadas em Base64:

Formato de imagem:

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

Formato PDF:

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

Tipos de imagem suportados:

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

Limites de tamanho de arquivo:

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

Segurança:

• Os arquivos são validados usando validação por número mágico (não apenas o MIME type)
• Todos os arquivos são verificados em busca de ameaças de segurança
• Os arquivos são enviados para armazenamento seguro no S3

Exemplo de requisição

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"
}

Resposta

A resposta JSON indica se o envio do vendedor foi bem-sucedido e fornece detalhes sobre o contato criado.

Resposta de sucesso

Resposta de erro

Exemplo de resposta - Sucesso

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

Exemplos de resposta - Erros

Propriedade inválida do site:

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

Limite de taxa excedido:

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

Formato de arquivo inválido:

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

Campo obrigatório ausente:

{
    "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"
}

Limite de taxa

Este endpoint tem limite de taxa para prevenir abusos:

• Limite de requisições: 10 requisições por hora por cliente
• Limite de bandwidth: 10MB por hora por cliente

Quando o limite de taxa é excedido, você receberá:

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

Funcionalidades de segurança

Detecção de spam

Todos os envios são verificados contra spam usando a integração com Akismet no ambiente de produção. Os envios marcados como spam são registrados mas não bloqueados automaticamente.

Segurança de arquivos

• Validação por número mágico: Os arquivos são validados pelo conteúdo real, não apenas pelo MIME type
• Limites de tamanho de arquivo: 2MB por arquivo, 10MB de bandwidth total por hora
• Formatos suportados: Apenas formatos de imagem e PDF incluídos na lista de permitidos são aceitos
• Armazenamento seguro: Arquivos enviados para buckets S3 criptografados

Validação de entrada

• Todos os campos de texto são higienizados e validados
• Endereços de e-mail devem ter formato RFC válido
• Números de telefone são validados por formato
• Prevenção de injeção SQL por meio de prepared statements
• Prevenção de XSS por meio de escape de templates

O que acontece após o envio

1. Criação de contato: Um novo contato é criado no CRM com tipo "SELLER"
2. Armazenamento de arquivos: Imagens e PDFs são enviados para armazenamento seguro no S3
3. Notificação por e-mail: Um e-mail é enfileirado (via SQS) e enviado ao cliente com:
   • Todos os detalhes do imóvel
   • Arquivos anexados (imagem e PDF)
   • Informações de contato
   • Metadados do envio (plataforma, versão do app, timestamp)
4. Estatísticas: O evento é registrado com metadados detalhados para análises
5. Registro de auditoria: Um registro de auditoria completo é criado para conformidade

Códigos de erro

Boas práticas

1. Sempre inclua o token OAuth2: O endpoint requer autenticação
2. Valide no lado do cliente: Verifique os campos obrigatórios antes de enviar
3. Comprima as imagens: Otimize as imagens antes de codificá-las em Base64 para ficar abaixo do limite de 2MB
4. Trate os limites de taxa: Implemente backoff exponencial se receber rate limit
5. Registre a versão do app: Sempre envie platform e appVersion para análises
6. Forneça o IP real: Envie o IP real do usuário para maior precisão na detecção de spam
7. Use HTTPS: Sempre use conexão segura em produção

Notas de integração

• customerId é automático: Não inclua customerId no corpo da requisição; ele é extraído do token OAuth2
• Propriedade do websiteId: O endpoint valida que o websiteId pertence ao cliente autenticado
• DEV vs PROD: A detecção de spam é ignorada no ambiente de desenvolvimento, mas está ativa em produção
• Redirecionamento de e-mail em DEV: Em desenvolvimento, os e-mails são redirecionados para info@mapaprop.com em vez do e-mail do cliente

Documentação relacionada

Para ver o fluxo completo de como funciona a captação de imóveis no sistema, consulte:

Captação de Imóveis - Vender (Fluxo Prático)

Histórico de versões

Versão da API: 1.0 Última atualização: 2025-10-22 Status: Pronto para produção