Engage / API v1
Clientes

Criar cliente

Cadastra um novo cliente vinculado à empresa dona da chave de API.

POST/v1/customers

Cria um cliente com os dados informados. Apenas uniqueKey e name são obrigatórios. O uniqueKey é o identificador de negócio do cliente (CPF, código do ERP, ID interno etc.) e deve ser único por empresa. Os campos status e preferredChannel aceitam apenas valores específicos dos enums listados abaixo.

Obrigatório

uniqueKey e name são obrigatórios. Os demais campos do body são opcionais.

Exemplo mínimo

json
{
  "uniqueKey": "CUST-001",
  "name": "Maria Silva"
}

Exemplo completo

json
{
  "uniqueKey": "CUST-001",
  "name": "Maria Silva",
  "email": "maria@exemplo.com",
  "phone": "+5511999990000",
  "status": "vip",
  "preferredChannel": "whatsapp",
  "tags": ["vip", "recorrente"],
  "location": "São Paulo, SP",
  "company": "Acme Ltda.",
  "birthDate": "1990-05-15",
  "customFields": {
    "loyalty_tier": "gold",
    "source": "indicacao"
  }
}

Parâmetros do body

  • uniqueKeystringobrigatório
    Identificador de negócio do cliente (CPF, código do ERP, ID interno etc.). Único por empresa e imutável após a criação. Espaços em branco no início/fim são removidos.
  • namestringobrigatório
    Nome do cliente.
  • emailstringopcional
    E-mail válido. Opcional.
  • phonestringopcional
    Telefone do cliente. Recomendado o formato E.164 (ex.: +5511999999999).
  • statusstringopcional
    Aceita apenas active, inactive, vip ou churned.
  • preferredChannelstringopcional
    Aceita apenas email, whatsapp, sms ou phone.
  • tagsstring[]opcional
    Lista de tags. Cada tag é uma string livre.
  • locationstringopcional
    Cidade ou região do cliente.
  • companystringopcional
    Empresa do cliente.
  • birthDatestring (ISO 8601)opcional
    Data de nascimento. Aceita apenas formato ISO (ex.: 1990-05-15).
  • customFieldsobjectopcional
    Mapa { <nome do campo>: valor } com os campos customizados da entidade Cliente. Chaves desconhecidas retornam 400 Bad Request. Veja campos customizados.

Campos da resposta

  • idstring (uuid)opcional
    Identificador único gerado pelo Engage.
  • uniqueKeystringopcional
    Identificador de negócio enviado, após trim.
  • namestringopcional
    Nome enviado.
  • emailstring | nullopcional
    E-mail enviado, ou null se omitido.
  • phonestring | nullopcional
    Telefone enviado, ou null se omitido.
  • statusstringopcional
    Valor enviado.
  • preferredChannelstringopcional
    Valor enviado.
  • tagsstring[]opcional
    Tags enviadas, ou array vazio.
  • locationstring | nullopcional
    Localização enviada, ou null se omitida.
  • companystring | nullopcional
    Empresa enviada, ou null se omitida.
  • birthDatestring (ISO 8601) | nullopcional
    Data de nascimento enviada em ISO completo, ou null.
  • createdAtstring (ISO 8601)opcional
    Data e hora de cadastro.

Possíveis erros

  • 400
    Unknown custom fields: <nomes>Alguma chave do customFields não corresponde a um campo cadastrado para a entidade Cliente.
  • 400
    ValidaçãoBody inválido: uniqueKey/name ausentes, e-mail mal formatado quando enviado, status ou preferredChannel fora dos enums, birthDate em formato inválido, etc.
  • 401
    Invalid API keyHeader x-api-key ausente, inválido ou revogado.
  • 409
    Já existe um cliente com o identificador "<uniqueKey>"Outro cliente da mesma empresa já usa esse uniqueKey. Use o GET por ID para recuperar o registro existente ou envie outro identificador.