Cadastrar cliente - Homfy Public API

Cadastra um cliente. Reexecutável: reenviar o mesmo partner_code devolve o cliente já existente em skipped, sem criar outro — e sem atualizar nada. Para alterar quem já existe, use PUT /partner/v1/lead.

Só partner_code, name e whatsapp são obrigatórios.

O WhatsApp é a identidade da pessoa na Homfy e é único por imobiliária. Diferente das outras entidades, aqui o número pode já estar em uso por um cliente que NÃO veio da sua integração — entrou por campanha, pelo corretor ou por importação. Nesse caso o item volta em errors com PARTNER_LEAD_WHATSAPP_ALREADY_EXISTS e, quando o cliente existente for seu, com o conflict_partner_code dele.

Serialize as chamadas por pessoa: dois cadastros SIMULTÂNEOS com o mesmo WhatsApp e partner_code diferentes não são garantidos como um só. Já o mesmo partner_code em paralelo é seguro — o segundo volta em skipped.

O cliente entra com a origem Parceiro, o que o mantém FORA da fila de atendimento da imobiliária — uma carga de integração não vira 200 avisos para os corretores. Para dizer quem responde pelo cliente, use POST /partner/v1/lead/assign-agent.

A resposta 201 pode conter falha: confira errors antes de dar o cadastro por concluído.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Body Params application/jsonRequired

Example

{
    "segment": "Investidor",
    "message_consent": "GRANTED",
    "document_type": "cpf",
    "birth_date": "1985-03-14",
    "partner_code": "CLI-8842",
    "name": "Ana Pereira",
    "whatsapp": "(48) 99999-1234",
    "email": "ana@exemplo.com",
    "phone": "(48) 3333-2222",
    "address_state": "SC",
    "address_city": "Florianópolis",
    "notes": "Procura 2 dormitórios até R$ 500 mil.",
    "document": "123.456.789-00",
    "rg": "12.345.678-9",
    "profession": "Médica",
    "marital_status": "Solteiro"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢201

application/json

Cliente criado, ou já existente em skipped.

Bodyapplication/json

Example

{
    "created": [
        {
            "partner_code": "AP-1024",
            "lead_id": 900
        }
    ],
    "skipped": [
        {
            "partner_code": "AP-1024",
            "lead_id": 900
        }
    ],
    "errors": [
        {
            "partner_code": "AP-1024",
            "errorCode": "PARTNER_PROPERTY_NOT_FOUND",
            "errorMessage": "string",
            "conflict_partner_code": "string"
        }
    ]
}

🟠400

🟠401

🟠403

🟠429

🔴500