Criar ou atualizar contato sem duplicar

A primeira escrita que toda integração precisa: mandar uma pessoa pro all4sales sem criar duplicado. O endpoint de upsert faz isso: se já existe um contato com o mesmo telefone ou e-mail, atualiza; se não existe, cria.

A chamada

curl -X POST "https://services.leadconnectorhq.com/contacts/upsert" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "ID_DA_CONTA",
    "firstName": "Maria",
    "lastName": "Souza",
    "phone": "+5524999990000",
    "email": "maria@exemplo.com.br",
    "source": "Site institucional",
    "tags": ["site", "orcamento"],
    "customFields": [
      { "id": "ID_DO_CAMPO_INTERESSE", "field_value": "Apartamento 2 quartos" }
    ]
  }'

Escopo necessário: contacts.write.

A resposta

{
  "new": true,
  "contact": {
    "id": "ocQHyuzHvysMo5N5VsXc",
    "firstName": "Maria",
    "phone": "+5524999990000",
    "tags": ["site", "orcamento"]
  }
}

new: true criou; new: false encontrou e atualizou. Guarde o id no seu sistema: as próximas chamadas (criar oportunidade, mandar mensagem) usam ele.

Como ele decide que é a mesma pessoa

Pelo telefone e pelo e-mail. Se qualquer um dos dois bate com um contato existente, é atualização. Por isso:

• Telefone sempre com DDI: +5524999990000. Sem o +55, a plataforma pode entender como outro número e criar duplicado.
• E-mail em minúsculo e sem espaço.
• Se você manda só nome, sem telefone nem e-mail, cria um contato novo toda vez. Não faça isso.

O que sobrescreve o quê

• Campo enviado substitui o valor que estava lá. Se você manda firstName, troca o nome.
• Campo não enviado fica como está. Pra limpar um campo, mande string vazia.
• tags enviadas são somadas às existentes, não substituídas.
• customFields segue a mesma regra de substituir só o que foi enviado.

Regra prática pra ERP: mande só os campos de que o ERP é a fonte da verdade (nome, documento, cidade). Não mande etiqueta nem dono, que são da equipe de vendas. Veja Sincronizar com ERP ou planilha.

Achar o id do campo personalizado

curl "https://services.leadconnectorhq.com/locations/ID_DA_CONTA/customFields?model=contact" \
  -H "Authorization: Bearer SEU_TOKEN" -H "Version: 2021-07-28"

Escopo locations/customFields.readonly. A resposta lista cada campo com id, name e dataType. O id não muda; busque uma vez e guarde. Detalhes em Campo personalizado pela API.

Depois do contato

Lead que chegou pelo site normalmente vira oportunidade na hora: Criar oportunidade no pipeline certo. E uma etiqueta como site pode ser o gatilho da automação de lead novo, sem precisar de nenhuma chamada a mais.