# Integração para desenvolvedores

XML Quadra Um v1, XML de CRM, API REST, webhooks e CSV para plataformas que enviam imóveis ao portal.

Página: https://quadraum.com.br/parceiros/docs
Markdown: https://quadraum.com.br/parceiros/docs.md

Esta página descreve como uma plataforma envia imóveis à Quadra Um. A imobiliária continua no CRM. O portal lê o estoque, publica no catálogo e devolve o lead.

## Visão geral

Há cinco caminhos. Use o que o produto já tem.

- **XML Quadra Um v1.** O formato canônico do portal. A plataforma gera o feed no schema Quadra Um e a sincronização entra sem mapeamento extra.
- **XML do CRM.** Feed que o CRM já publica para outros portais. O adaptador mapeia nós conhecidos (Vista, Imoview, Jetimob e afins).
- **API REST.** A plataforma envia e atualiza imóveis via HTTPS. Serve quem já tem um conector e não quer expor um XML público.
- **Webhook push.** O CRM avisa a Quadra Um quando um imóvel nasce, muda ou sai do ar. Complementa XML ou REST para o catálogo acompanhar na hora.
- **CSV / planilha.** Arquivo delimitado por ponto e vírgula, com cabeçalho fixo. Útil para homologação e para quem ainda não tem feed.

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`.

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

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.

| Campo Quadra Um | Nós comuns no feed |
| --- | --- |
| CodigoExterno | Codigo, ListingID, Referencia, Id |
| Titulo | Titulo, Title, Destaque |
| Preco | PrecoVenda, Valor, Price |
| Transacao | Finalidade, Operacao, BusinessType |
| Bairro / Cidade / UF | Bairro, Cidade, Estado, Location |
| Fotos | Foto, Media, Pictures/Picture |

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`.

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

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

## Webhooks

A plataforma chama a Quadra Um quando o imóvel muda. Endpoint: `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`.

## 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.

## 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. O portal pode empurrar o contato por webhook, ou a imobiliária puxa com a chave do painel.

- `GET /v1/leads` lista os leads da conta.
- `GET /v1/leads/{id}` devolve o detalhe: contato, anúncio, consentimento, avaliação e status de entrega.

Responda 2xx em até 5 segundos no callback. 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

| Código | Quando |
| --- | --- |
| 401 | Token ausente ou inválido |
| 403 | Plataforma ainda não homologada |
| 409 | Código externo de outra imobiliária |
| 413 | Feed acima de 80 MB |
| 422 | Schema inválido ou campo obrigatório vazio |
| 429 | Mais de 120 req/min no REST |

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

## Homologação

1. Cadastre a plataforma em [Seja um parceiro](https://quadraum.com.br/seja-um-parceiro.md).
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](https://quadraum.com.br/parceiros.md) e o conector aparece no painel da imobiliária.

Exemplos completos de XML, REST, webhook e CSV estão na página HTML.