ImobyFlowParcerias Imobiliárias
Navegar na documentação
English

Lotes

Até 500 imóveis ou clientes numa chamada, processados no ritmo da plataforma, com o desfecho de cada item.

As rotas

POST/v1/properties/batch

Lote de imóveis

Até 500 imóveis e 4 MB numa chamada. Cada item é o PUT pelo código (externalRef obrigatório) — as mesmas regras, os mesmos desfechos. Item mal formado volta REJECTED e não barra os outros; o mesmo código duas vezes no lote é recusado. Responde 202 na hora e processa no ritmo da plataforma (4 itens por segundo): 500 itens levam de 2 a 3 minutos.

Permissão: properties:writeAceita modo ensaioAceita Idempotency-Key

Filtros e paginação

dryRunboolean
true = modo ensaio: valida e diz o que aconteceria, sem gravar nada.

Corpo do pedido

itemslista de PropertyInputobrigatório
Os itens (1 a 500).

Exemplo de corpo

{
  "items": [
    {
      "externalRef": "AP1234",
      "title": "Apartamento 3 quartos no Bigorrilho",
      "type": "APARTAMENTO",
      "purposes": [
        "VENDA"
      ],
      "salePrice": 890000,
      "address": {
        "cityId": "4106902",
        "neighborhoodSlug": "bigorrilho",
        "street": "Rua Padre Anchieta",
        "number": "1500",
        "complement": "Ap 82"
      },
      "bedrooms": 3,
      "suites": 1,
      "bathrooms": 2,
      "parkingSpots": 2,
      "area": 98,
      "photos": [
        "https://www.suaimobiliaria.com.br/fotos/AP1234/1.jpg",
        "https://www.suaimobiliaria.com.br/fotos/AP1234/2.jpg"
      ]
    }
  ]
}

Resposta202Aceito

dataBatchCreatedobrigatório
O lote recebido.

Exemplo

# Modo ensaio: nada é gravado. Tire o ?dryRun=true para gravar de verdade.
curl -X POST 'https://api.imobyflow.com.br/v1/properties/batch?dryRun=true' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: pt-BR' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "items": [
    {
      "externalRef": "AP1234",
      "title": "Apartamento 3 quartos no Bigorrilho",
      "type": "APARTAMENTO",
      "purposes": [
        "VENDA"
      ],
      "salePrice": 890000,
      "address": {
        "cityId": "4106902",
        "neighborhoodSlug": "bigorrilho",
        "street": "Rua Padre Anchieta",
        "number": "1500",
        "complement": "Ap 82"
      },
      "bedrooms": 3,
      "suites": 1,
      "bathrooms": 2,
      "parkingSpots": 2,
      "area": 98,
      "photos": [
        "https://www.suaimobiliaria.com.br/fotos/AP1234/1.jpg",
        "https://www.suaimobiliaria.com.br/fotos/AP1234/2.jpg"
      ]
    }
  ]
}
JSON

Erros desta rota

E os erros comuns a toda rota

GET/v1/properties/batch/{batchId}

Acompanhar o lote

O status, a contagem e o desfecho de cada item, na ordem do pedido. O lote fica disponível por 7 dias.

Permissão: properties:read

Parâmetros no caminho

batchIdstringobrigatório
Id do lote (b-…).

Resposta200OK

dataBatchobrigatório
O lote.

Exemplo

curl -X GET 'https://api.imobyflow.com.br/v1/properties/batch/b-4c1d9e2f7a3b8c6d' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: pt-BR'

Erros desta rota

E os erros comuns a toda rota

POST/v1/leads/batch

Lote de clientes

Até 500 clientes e 4 MB numa chamada. Cada item é o PUT pelo código (externalRef obrigatório) — as mesmas regras, os mesmos desfechos. Item mal formado volta REJECTED e não barra os outros; o mesmo código duas vezes no lote é recusado. Responde 202 na hora e processa no ritmo da plataforma (4 itens por segundo): 500 itens levam de 2 a 3 minutos.

Permissão: leads:writeAceita modo ensaioAceita Idempotency-Key

Filtros e paginação

dryRunboolean
true = modo ensaio: valida e diz o que aconteceria, sem gravar nada.

Corpo do pedido

itemslista de LeadInputobrigatório
Os itens (1 a 500).

Exemplo de corpo

{
  "items": [
    {
      "externalRef": "CLI-889",
      "name": "Carlos Pereira",
      "phones": [
        {
          "number": "(41) 99999-8888",
          "isWhatsApp": true
        }
      ],
      "email": "carlos@example.com",
      "status": "ATTENDING",
      "ownerEmail": "marina@suaimobiliaria.com.br",
      "interest": {
        "purposes": [
          "VENDA"
        ],
        "propertyTypes": [
          "APARTAMENTO"
        ],
        "locations": [
          {
            "cityId": "4106902",
            "neighborhoodSlug": "bigorrilho"
          }
        ],
        "salePriceMax": 950000,
        "bedrooms": 3
      },
      "lastActivityAt": "2026-10-02T15:00:00Z",
      "consentGiven": true
    }
  ]
}

Resposta202Aceito

dataBatchCreatedobrigatório
O lote recebido.

Exemplo

# Modo ensaio: nada é gravado. Tire o ?dryRun=true para gravar de verdade.
curl -X POST 'https://api.imobyflow.com.br/v1/leads/batch?dryRun=true' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: pt-BR' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "items": [
    {
      "externalRef": "CLI-889",
      "name": "Carlos Pereira",
      "phones": [
        {
          "number": "(41) 99999-8888",
          "isWhatsApp": true
        }
      ],
      "email": "carlos@example.com",
      "status": "ATTENDING",
      "ownerEmail": "marina@suaimobiliaria.com.br",
      "interest": {
        "purposes": [
          "VENDA"
        ],
        "propertyTypes": [
          "APARTAMENTO"
        ],
        "locations": [
          {
            "cityId": "4106902",
            "neighborhoodSlug": "bigorrilho"
          }
        ],
        "salePriceMax": 950000,
        "bedrooms": 3
      },
      "lastActivityAt": "2026-10-02T15:00:00Z",
      "consentGiven": true
    }
  ]
}
JSON

Erros desta rota

E os erros comuns a toda rota

GET/v1/leads/batch/{batchId}

Acompanhar o lote

O status, a contagem e o desfecho de cada item, na ordem do pedido. O lote fica disponível por 7 dias.

Permissão: leads:read

Parâmetros no caminho

batchIdstringobrigatório
Id do lote (b-…).

Resposta200OK

dataBatchobrigatório
O lote.

Exemplo

curl -X GET 'https://api.imobyflow.com.br/v1/leads/batch/b-4c1d9e2f7a3b8c6d' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: pt-BR'

Erros desta rota

E os erros comuns a toda rota

Os objetos

BatchCreated

O lote recebido.

idstringobrigatório
Id do lote (b-…).
typestringobrigatório
properties ou leads.um de properties leads
statusstringobrigatório
QUEUED, ou DONE quando nenhum item era válido.um de QUEUED RUNNING DONE
totalintegerobrigatório
Itens recebidos.
acceptedintegerobrigatório
Itens que seguiram para o processamento.
rejectedintegerobrigatório
Itens recusados na forma (veja o resultado).
dryRunbooleanobrigatório
O lote inteiro é um ensaio.

BatchItem

O resultado de um item.

indexintegerobrigatório
Posição no pedido.
externalRefstringobrigatóriopode vir nulo
O código do item.
outcomestringobrigatório
O desfecho do item — os mesmos do PUT pelo código, mais PENDING (ainda na fila) e REJECTED.
idstringobrigatóriopode vir nulo
O id do imóvel ou cliente.
codestringobrigatóriopode vir nulo
O código de erro, quando recusado.
detailstringobrigatóriopode vir nulo
Detalhe.
invalidParamslista de objetoobrigatóriopode vir nulo
Os problemas de forma.
photosstringobrigatóriopode vir nulo
A galeria (imóveis).

Batch

Um lote, com o desfecho de cada item.

idstringobrigatório
Id do lote.
typestringobrigatório
properties ou leads.um de properties leads
statusstringobrigatório
QUEUED, RUNNING ou DONE.um de QUEUED RUNNING DONE
dryRunbooleanobrigatório
Ensaio.
totalintegerobrigatóriopode vir nulo
Itens.
processedintegerobrigatóriopode vir nulo
Itens com desfecho.
countsmapaobrigatório
Contagem por desfecho (CREATED, UPDATED, REJECTED…).
createdAtstringobrigatóriopode vir nulo
Quando foi recebido.
startedAtstringobrigatóriopode vir nulo
Quando começou.
finishedAtstringobrigatóriopode vir nulo
Quando terminou.
resultslista de BatchItemobrigatório
O desfecho de cada item, na ordem do pedido.