@horizon-integrations/jetimob-crm/docs/API_JETIMOB.md

Adapter de integração com o CRM Jetimob — padrão Airbyte (@horizon-js/integrations-core)

# API Jetimob — referência da API externa

Referência da API webservice da Jetimob, **verificada contra a API real** em
2026-05. Doc oficial: <https://docs.jetimob.com/>.

> Versões antigas desta doc afirmavam coisas erradas ("array direto", "sem
> paginação", "sem filtro de data confiável"). Tudo abaixo foi testado.

## Autenticação

Uma única **`webserviceKey`**, embutida no path da URL. Sem header, sem token,
sem OAuth.

```
https://api.jetimob.com/webservice/{WEBSERVICE_KEY}/imoveis?v=4
```

## Endpoints

### `GET /webservice/{KEY}/imoveis`

Dump de imóveis. Cada imóvel traz **~96 campos completos** (~9.5KB).

| Param | Tipo | Descrição |
|---|---|---|
| `v` | Number | Versão do webservice. Influencia os campos retornados (v1≈86, v4≈96, v6≈100 campos). Default 0 |
| `page` | Number | Página (a partir da v4). Default 1 |
| `pageSize` | Number | Registros por página (a partir da v4). Default 100 |
| `start` | Number | **Unix timestamp** — filtra por data de última atualização (≥). Testado: funciona |
| `end` | Number | **Unix timestamp** — filtra por data de última atualização (≤) |
| `codigos` | Array | Lista de `codigo` separada por vírgula. Ex: `codigos=123,456` |
| `id` | Number | Filtra por `id_imovel` específico |

**Não existe** parâmetro de seleção de campos (`fields`, `campos`, `select`,
`only` — todos testados, todos ignorados).

**Resposta** — envelope com metadados de paginação:

```json
{
  "total": 1069,
  "page": 1,
  "pageSize": 100,
  "totalPages": 11,
  "data": [ { "codigo": "1408", "id_imovel": 6570922, ... }, ... ]
}
```

### `GET /webservice/{KEY}/imoveis-ativos`

**Endpoint leve.** Devolve só os `id_imovel` dos imóveis ativos, todos numa
resposta (~0.3s, ~9KB pra 1000+ imóveis). Não traz timestamp.

```json
{ "total": 1069, "page": 1, "pageSize": 100, "totalPages": 1,
  "data": { "total": 1069, "result": [6570922, 6571179, ...] } }
```

### `GET /webservice/{KEY}/condominios`

Lista de condomínios. Params: `v`, `page`.

### `GET /webservice/{KEY}/leads/{TOKEN}` · `POST .../leads/{TOKEN}`

API de leads (token próprio + header `Authorization-Key`). Não consumida por
este pacote ainda.

## `id_imovel` vs `codigo` — IMPORTANTE

São identificadores **diferentes**:

| | Exemplo | De onde vem | Filtra com |
|---|---|---|---|
| `id_imovel` | `6570922` | `/imoveis-ativos`, campo `id_imovel` | `?id=` |
| `codigo` | `1408` | campo `codigo` | `?codigos=` |

No formato Horizon: `reference` = `codigo`; `id_imovel` é exposto como campo extra.

## Observações

1. **Datas**: `data_update` vem como `"YYYY-MM-DD HH:mm:ss"`. `start`/`end` esperam Unix timestamp (segundos).
2. **Booleanos como número**: vários campos vêm `0`/`1` (ex: `mobiliado` 0/1/2).
3. **Campos opcionais vêm `null`** (não `undefined`).
4. **502 transiente**: o nginx da Jetimob devolve 502 Bad Gateway esporádico — o adapter trata com retry.