Importar Propriedades por JSON

Versão do documento: v1.0 Data: 2026-04-29 Audiência: Clientes avançados, integradores, power users

Resumo

O modo JSON é a forma mais rápida e precisa de importar uma propriedade quando você já tem os dados estruturados. Diferente de URL e HTML, este modo não usa scraping nem IA: o que você cola é o que entra no sistema, sem transformações automáticas.

É o modo recomendado se:

• Você já tem uma exportação de outro sistema (CRM, ERP, Excel convertido para JSON, etc.)
• Está fazendo uma integração personalizada
• Quer ter controle total sobre os campos sem depender do scraper

Se você nunca trabalhou com JSON, convém usar URL ou HTML primeiro.

Como funciona

Cola o JSON  ->  Mapaprop valida a estrutura  ->  Mostra os dados no Editor  ->  Você confirma  ->  Propriedade importada

O JSON é carregado direto no Editor. Ali você verá todos os campos preenchidos com o que passou — pode corrigir qualquer coisa antes de pressionar Importar.

Estrutura do JSON

O JSON é um objeto plano (sem envelope). Se sua fonte o envolve em { "data": { ... } }, não há problema — o sistema desempacota o campo data automaticamente.

O mínimo que você precisa (exemplo)

Só com isso, já pode importar uma propriedade. Depois você completa o resto no Editor.

{
    "title": "Apartamento 2 ambientes em Palermo",
    "description": "Apartamento luminoso, varanda para a rua, cozinha integrada.",
    "operation": 1,
    "type": 1,
    "price": 95000,
    "currency": "USD",
    "address": "Avenida Santa Fe 3500",
    "zone0": 1,
    "zone1": 1,
    "zone2": 23,
    "zone3": 1340,
    "rooms": 1,
    "bathrooms": 1,
    "buildingArea": 45
}

Isso é tudo. O resto dos campos (orientação, despesas, fotos, atributos) você pode adicionar no Editor.

Campos: o que é cada um

Identificação

Tipo de propriedade e operação

Lista completa de tipos em docs/mapaprop-mysql/mapaprop-database-mysql-report.md.

Localização

Mapaprop usa uma hierarquia de zonas com 4 níveis. Você deve passar pelo menos zone0, zone1, zone2. Se conhece o bairro (zone3) também, melhor.

Importante: se passar o address e os zone*, o Editor mostrará a localização no mapa para você confirmar. Se não tem certeza dos IDs de zona, pode passar só zone3Description (texto do bairro) e o Editor ajuda a mapear.

{
    "address": "Av. Santa Fe 3500",
    "zone3Description": "Palermo",
    "zone2Description": "Capital Federal"
}

Preço

Características físicas

Cuidado: rooms ≠ ambiences. Um apartamento de 3 ambientes com 2 dormitórios teria ambiences: 3 e rooms: 2.

Comodidades (booleanos)

Todos opcionais. Passe como true se a propriedade tem, omita se não (não precisa colocar false).

{
    "hasSwimmingPool": true,
    "hasPatio": true,
    "hasLaundry": true,
    "hasStorage": true,
    "hasSecurity": true,
    "hasPrivateElevator": true,
    "terrace": true,
    "frontGarden": true,
    "grill": true,
    "janitor": true,
    "suite": true,
    "playroom": true,
    "furnished": true,
    "accessible": true,
    "laundryMachine": true,
    "wifi": true,
    "alarm": true,
    "securityBox": true,
    "partySaloon": true,
    "jacuzzi": true,
    "barbecueArea": true,
    "electricGenerator": true,
    "gatedCommunity": true,
    "countryClub": true,
    "park": true,
    "mortgageReady": true,
    "professionalAvailable": true,
    "petsReady": true,
    "telephoneLine": true,
    "cableIncluded": true
}

Imagens

{
    "mainImage": "https://meusite.com/foto-principal.jpg",
    "images": [
        { "url": "https://meusite.com/foto1.jpg", "description": "Sala" },
        { "url": "https://meusite.com/foto2.jpg", "description": "Cozinha" },
        { "url": "https://meusite.com/foto3.jpg", "description": "Dormitório" }
    ]
}

• As URLs devem ser públicas e acessíveis pela Internet (Mapaprop as baixa no servidor).
• Se você só tem uma foto principal, passe mainImage e deixe images vazio ou não coloque — o sistema monta o array a partir de mainImage.
• Máximo recomendado: 20 fotos por propriedade.

Estado do negócio

{
    "reserved": false,
    "sold": false,
    "rented": false,
    "suspended": false,
    "published": true,
    "publishedOnlyWebsite": false
}

• published: false deixa a propriedade como rascunho (visível só no seu painel, não se publica em redes nem website).
• publishedOnlyWebsite: true a publica só no seu site sem enviar para portais (Zonaprop, MercadoLibre, etc).

Atributos avançados (não obrigatórios)

O array attributes permite passar comodidades com detalhe (categoria, label em espanhol, código legacy). Se não passar, Mapaprop infere os atributos dos booleanos da seção anterior.

{
    "attributes": [
        {
            "locale": "es_AR",
            "country": "ar",
            "id": "swimming-pool",
            "label": "Piscina",
            "group": "propertyAttribute",
            "group_sub": "label",
            "group_subtype": "ammenities",
            "type": "bool",
            "key_legacy": "hasSwimmingPool",
            "selected": true,
            "status": true
        }
    ]
}

Só recomendamos usar attributes se você está migrando de um sistema que já os exporta neste formato. Para uso normal, os booleanos bastam.

Exemplo completo realista

Este é um JSON válido e completo, pronto para colar no formulário:

{
    "code": "JSON-001",
    "title": "Apartamento 2 ambientes em Palermo com varanda",
    "description": "Apartamento luminoso, em andar alto, com varanda para a rua. Cozinha integrada à sala. Dormitório com armário embutido. Banheiro completo com banheira. Edifício com zelador e porteiro eletrônico. Perto de metrô e ônibus. Aceita financiamento.",
    "operation": 1,
    "type": 1,
    "address": "Av. Santa Fe 3500",
    "betweenStreets": "Entre Coronel Diaz e Pueyrredon",
    "zone0": 1,
    "zone1": 1,
    "zone2": 23,
    "zone3": 22097,
    "zipcode": "1425",
    "mapLatitude": "-34.5955856",
    "mapLongitude": "-58.382166",
    "price": 95000,
    "currency": "USD",
    "expensesPrice": 80000,
    "expensesCurrency": "ARS",
    "rooms": 1,
    "ambiences": 2,
    "bathrooms": 1,
    "toilettes": 0,
    "buildingArea": 45,
    "landArea": 45,
    "floors": 7,
    "totalFloors": 12,
    "apartmentsPerFloor": 4,
    "yearsOld": 8,
    "orientation": "1",
    "airConditioner": 2,
    "heatingType": 4,
    "waterHeaterType": 2,
    "balconyType": 1,
    "hasLaundry": true,
    "laundryMachine": true,
    "hasSecurity": true,
    "janitor": true,
    "mortgageReady": true,
    "terrace": true,
    "mainImage": "https://meusite.com/apto-foto-1.jpg",
    "images": [
        { "url": "https://meusite.com/apto-foto-1.jpg", "description": "Sala" },
        { "url": "https://meusite.com/apto-foto-2.jpg", "description": "Cozinha" },
        { "url": "https://meusite.com/apto-foto-3.jpg", "description": "Dormitório" },
        { "url": "https://meusite.com/apto-foto-4.jpg", "description": "Varanda" }
    ],
    "published": true,
    "urlWebExternal": "https://meusite.com/propriedades/apto-palermo"
}

Erros comuns

Validação antes de colar

1. Valide o JSON em https://jsonlint.com/ ou https://jsonformatter.org/. Se o site marcar um erro de sintaxe, também não funcionará no Mapaprop.
2. Verifique que tem todos os campos obrigatórios: title, description, operation, type, price, currency, address, zone0, zone1, zone2.
3. Teste com o exemplo mínimo primeiro. Se funciona, vá adicionando campos aos poucos.

Diferenças entre os 3 modos

Suporte e referências

• Doc técnica do objeto Property: .claude/rules/java-backend/property-object-reference.md
• Schema MySQL: docs/mapaprop-mysql/mapaprop-database-mysql-report.md
• Regras gerais de import: property-import-url-rules.md
• Arquitetura: property-import-url-architecture.md
• Exemplo JSON full: mapaprop-apps/mapaprop-v2/pages/properties/property-post-v3.json

Se encontrar um caso que não cobre esta documentação, copie o relatório do modal de erro e envie em um ticket de suporte.