Integração para desenvolvedores

Visão geral

Há cinco caminhos. Use o que o produto já tem; não é preciso implementar todos.

• XML Quadra Um v1 — schema nativo, sem mapeamento.
• XML do CRM — feed que vocês já geram para outros portais.
• API REST — upsert por código externo, com token da plataforma.
• Webhook push — avisa criação, alteração ou baixa na hora.
• CSV — homologação e estoques pequenos, ponto e vírgula.

Frequência padrão do pull (XML/CSV): a cada 6 horas. REST e webhook atualizam na hora. A imobiliária liga o conector no painel colando a URL do feed ou autorizando o app.

Autenticação

REST e webhooks usam um token da plataforma, emitido depois da homologação. XML e CSV podem ser uma URL pública HTTPS ou uma URL com token na query.

Authorization: Bearer th_live_<token>

URLs internas, localhost e IPs privados são recusados. O feed precisa responder 200, Content-Type XML/CSV e HTTPS.

XML Quadra Um v1

Formato canônico. Um arquivo UTF-8, raiz <Carga>, lista em <Imoveis>. O identificador estável é CodigoExterno — não mude entre sincronizações.

Transacao: venda ou aluguel. Tipo: apartamento, casa, cobertura, terreno, comercial. Status: ativo (publica) ou inativo (tira do ar).

<Carga versao="1" geradoEm="2026-09-14T15:00:00-03:00">
  <Imoveis>
    <Imovel>
      <CodigoExterno>VS-1842</CodigoExterno>
      <Titulo>Cobertura frente mar na Barra Sul</Titulo>
      <Descricao>4 suítes, piscina privativa e vista permanente para o mar.</Descricao>
      <Transacao>venda</Transacao>
      <Tipo>cobertura</Tipo>
      <Status>ativo</Status>
      <Preco>4850000</Preco>
      <Condominio>2200</Condominio>
      <Iptu>980</Iptu>
      <AreaPrivativa>286</AreaPrivativa>
      <AreaTotal>310</AreaTotal>
      <Quartos>4</Quartos>
      <Suites>4</Suites>
      <Banheiros>5</Banheiros>
      <Vagas>3</Vagas>
      <Caracteristicas>
        <Item>Frente mar</Item>
        <Item>Piscina privativa</Item>
      </Caracteristicas>
      <Endereco>
        <Logradouro>Av. Atlântica</Logradouro>
        <Numero>1200</Numero>
        <Bairro>Barra Sul</Bairro>
        <Cidade>Balneário Camboriú</Cidade>
        <UF>SC</UF>
        <CEP>88330-000</CEP>
        <Latitude>-26.9908</Latitude>
        <Longitude>-48.6336</Longitude>
        <EnderecoExato>true</EnderecoExato>
      </Endereco>
      <Midias>
        <Foto ordem="1" url="https://cdn.plataforma.com/1842/01.jpg" />
        <Foto ordem="2" url="https://cdn.plataforma.com/1842/02.jpg" />
        <Video url="https://cdn.plataforma.com/1842/tour.mp4" titulo="Tour" />
      </Midias>
      <Corretor>
        <Nome>Ana Souza</Nome>
        <CRECI>12345-F</CRECI>
        <WhatsApp>47999990000</WhatsApp>
        <Email>[email protected]</Email>
      </Corretor>
    </Imovel>
  </Imoveis>
</Carga>

Preços em reais, sem máscara. Áreas em m². WhatsApp só com dígitos, incluindo DDD. Fotos em HTTPS; a primeira é a capa.

XML do CRM

Se o produto já gera XML para Vista, Imoview, Jetimob ou outro portal, envie a URL e o exemplo. O adaptador mapeia os nós conhecidos para o modelo canônico. Campos típicos que lemos:

Se um nó obrigatório não existir, o imóvel fica inválido no log da sincronização e não entra no catálogo.

API REST

Base: https://api.quadraum.com.br/v1. O recurso é o imóvel da imobiliária, identificado por code (o código externo no CRM).

• PUT /listings/{code} — cria ou atualiza.
• DELETE /listings/{code} — tira do ar.
• GET /listings/{code} — lê o que o portal guardou.

curl -X PUT https://api.quadraum.com.br/v1/listings/VS-1842 \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "VS-1842",
    "title": "Cobertura frente mar na Barra Sul",
    "transaction": "sale",
    "type": "penthouse",
    "status": "active",
    "price": 4850000,
    "privateArea": 286,
    "bedrooms": 4,
    "suites": 4,
    "bathrooms": 5,
    "parkingSpots": 3,
    "address": {
      "neighborhood": "Barra Sul",
      "city": "Balneário Camboriú",
      "state": "SC",
      "lat": -26.9908,
      "lng": -48.6336,
      "isExactAddress": true
    },
    "images": [
      "https://cdn.plataforma.com/1842/01.jpg"
    ]
  }'

transaction: sale | rent. type: apartment, house, penthouse, land, commercial.

Webhooks

A plataforma chama a Quadra Um quando o imóvel muda. Útil para preço, status e fotos sem esperar o ciclo de 6 horas.

Endpoint de ingestão: POST https://api.quadraum.com.br/v1/hooks/listings

Eventos: listing.created, listing.updated, listing.unpublished. Assine o corpo com HMAC-SHA256 no header X-Quadraum-Signature.

{
  "event": "listing.updated",
  "occurredAt": "2026-09-14T15:04:12-03:00",
  "listing": {
    "code": "VS-1842",
    "status": "active",
    "price": 4790000
  }
}

CSV

UTF-8, separador ponto e vírgula, primeira linha com cabeçalho fixo. Várias fotos na mesma célula, separadas por vírgula.

codigo;titulo;transacao;tipo;status;preco;area_privativa;quartos;bairro;cidade;uf;fotos
VS-1842;Cobertura frente mar;venda;cobertura;ativo;4850000;286;4;Barra Sul;Balneário Camboriú;SC;https://cdn.plataforma.com/1842/01.jpg

Fotos e vídeos

URLs públicas HTTPS. Não enviamos arquivo binário no XML. JPG ou WebP, lado maior a partir de 1200 px. A ordem define a capa. Vídeo é opcional, MP4 ou link de tour.

Se a URL falhar no download, o imóvel sobe sem aquela foto e o log registra o aviso. Três falhas seguidas na capa marcam o item como inválido.

Leads

Quando o comprador demonstra interesse, o lead fica no painel da imobiliária. Há dois caminhos para o CRM: o portal empurra o contato (webhook) ou a imobiliária puxa os leads com a chave do painel.

GET /v1/leads lista todos os leads da conta. Sem query, devolve a página mais recente. GET /v1/leads/{id} devolve o detalhe completo daquele lead: contato, anúncio, consentimento, avaliação e status de entrega.

curl -X GET https://api.quadraum.com.br/v1/leads \
  -H "Authorization: Bearer th_live_..."

curl -X GET https://api.quadraum.com.br/v1/leads/lead-104 \
  -H "Authorization: Bearer th_live_..."

Callback de push, se a plataforma preferir receber o lead na hora:

{
  "event": "lead.created",
  "occurredAt": "2026-09-14T18:12:00-03:00",
  "lead": {
    "name": "Carla Mendes",
    "phone": "47988887777",
    "email": "[email protected]",
    "message": "Quero visitar no sábado.",
    "channel": "portal",
    "listingCode": "VS-1842"
  }
}

Responda 2xx em até 5 segundos. Se falhar, tentamos de novo com backoff. O WhatsApp da imobiliária continua no fluxo do portal, mesmo com o callback ligado.

Erros e limites

XML: um arquivo por imobiliária. REST: lote de até 100 imóveis por request se usar POST /listings:batch.

Homologação

1. Cadastre a plataforma em Seja um parceiro.
2. Envie um feed ou uma chamada REST com ao menos 5 imóveis válidos.
3. Inclua venda e aluguel, foto, preço e endereço com cidade e UF.
4. Teste a baixa: status inativo ou DELETE deve tirar o anúncio do ar.
5. Depois da aprovação, a logo entra em Parceiros e integrados e o conector aparece no painel da imobiliária.