POST api/v1/crm/contato

Descrição

Cria ou atualiza um contato do CRM (upsert). A regra é: se id for informado, atualiza aquele contato; senão, se o email casar um contato existente da loja, atualiza-o; caso contrário, cria um novo.

Na atualização o merge é NÃO-DESTRUTIVO: campos não enviados preservam o valor atual (nada é apagado por omissão). A lista informada em idLista é adicionada (união) — nunca remove listas existentes.

Obs.: Utilizar tokenAPI (Authorization: Bearer). Corpo em application/json (ou form-data).

Limite de requisições: 120 requisições por minuto.

Códigos de erro:

Código	Descrição
400	Requisição inválida — informe ao menos nome, email ou telefone.
401	Não autorizado — Token ausente, inválido, inativo ou sem permissão.
429	Limite de requisições ultrapassada.

Body da Requisição

{
  "id": "",
  "nome": "Maria Souza",
  "email": "maria@empresa.com.br",
  "telefone": "5511999998888",
  "empresa": "Empresa Exemplo Ltda",
  "idEmpresa": "",
  "cargo": "Compradora",
  "documento": "12345678901",
  "cidade": "São Paulo",
  "uf": "SP",
  "tags": ["cliente-vip"],
  "idLista": "507f1f77bcf86cd799439077",
  "origem": "api",
  "consentimentoEmail": true
}

Parâmetros de Entrada

Campo	Descrição	Tipo	Obrigatório
id	Força atualização deste contato. Vazio = cria ou casa por e-mail.	string	não
nome	Nome do contato.	string	condic.
email	E-mail — usado no dedup quando não há id.	string	condic.
telefone	Telefone do contato.	string	condic.
empresa	Nome da empresa (texto).	string	não
idEmpresa	Vincula a uma empresa (conta CRM) existente.	string	não
cargo	Cargo do contato.	string	não
documento	CPF/CNPJ.	string	não
cidade	Cidade.	string	não
uf	UF (2 letras).	string	não
tags	Lista de tags (array) ou texto separado por vírgula.	array/string	não
idLista	Adiciona o contato a esta lista (união).	string	não
origem	Origem do contato. Padrão "api".	string	não
consentimentoEmail	Consentimento de e-mail (LGPD).	bool	não

Obrigatório: informe ao menos um entre nome, email ou telefone.

Exemplo de uso:
POST api/v1/crm/contato

Parâmetros de Retorno

Campo	Descrição	Tipo
id	Identificador do contato criado ou atualizado.	string
criado	true se foi criado; false se foi atualizado.	bool

Exemplo de Resposta

{
  "id": "507f1f77bcf86cd799439011",
  "criado": true
}