Engage / API v1
Conceito

Como funcionam os campos customizados

Campos customizados permitem estender clientes, produtos e vendas com informações próprias do seu negócio. Eles são definidos uma vez pelo painel do Engage e, a partir daí, ficam disponíveis para leitura e escrita nas chamadas da API v1.

Criando um campo no painel

A criação e a remoção de campos customizados são feitas pelo painel — a API v1 não expõe endpoints para isso. Siga este fluxo:

  1. 01
    Acesse Configurações → Campos PersonalizadosNa barra lateral do Engage, entre em Configurações e selecione a aba Campos Personalizados.
  2. 02
    Escolha a entidadeUse as abas do topo para alternar entre Clientes, Produtos e Vendas. Cada entidade tem sua própria lista de campos.
  3. 03
    Clique em + Novo CampoPreencha “Nome do Campo” (ex.: Cargo, Departamento) e escolha o “Tipo de Campo” entre Texto, Número ou Data. O nome deve ser único dentro da entidade.
  4. 04
    SalveO campo passa a aparecer imediatamente nos formulários da entidade e fica disponível nas chamadas da API v1.
Remoção apaga os valores salvos
Excluir um campo remove também todos os valores preenchidos nas entidades. A ação não pode ser desfeita — revise antes de confirmar.

Tipos suportados

O Engage oferece três tipos fixos. Cada tipo determina como o valor é validado pelo servidor e o formato em que é retornado nas respostas da API.

  • textTexto
    String livre. Aceita qualquer valor de texto. Retornado como string.
  • numberNúmero
    Inteiro ou decimal. Enviado como string (ex.: "150.5"). Retornado como string. Valor não numérico retorna 400 Bad Request.
  • dateData
    Aceita DD/MM/AAAA, DD/MM/AAAA HH:MM ou ISO 8601. Retornado em ISO 8601. Valor inválido retorna 400 Bad Request.

Enviando valores via API

Nos endpoints de criação (POST /v1/customers, POST /v1/products, POST /v1/sales) envie um objeto customFields no body. As chaves são os nomes exatos dos campos criados no painel e os valores são strings (ou null).

bash
curl -X POST https://api.engage.app/v1/customers \
  -H "x-api-key: $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "email": "maria@exemplo.com",
    "customFields": {
      "Cargo": "Gerente de Compras",
      "Data de contrato": "15/04/2026",
      "Limite de crédito": "12000"
    }
  }'
A chave precisa bater com o nome no painel
O Engage procura cada chave do objeto customFields pelo nome exato — inclusive acentos e maiúsculas. Se a chave não existir como definição, a resposta é 400 Bad Request com a mensagem Unknown custom fields: <nomes>.

Lendo valores via API

Ao buscar uma entidade por ID (GET /v1/customers/id/:id, GET /v1/products/id/:id, GET /v1/sales/id/:id) a resposta inclui o objeto customFields com os valores normalizados pelo tipo:

json
{
  "id": "f7e8d9c0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "name": "Maria Silva",
  "email": "maria@exemplo.com",
  "status": "active",
  "preferredChannel": "whatsapp",
  "tags": [],
  "location": null,
  "company": null,
  "birthDate": null,
  "createdAt": "2026-04-24T12:34:56.000Z",
  "customFields": {
    "Cargo": "Gerente de Compras",
    "Data de contrato": "2026-04-15T00:00:00.000Z",
    "Limite de crédito": "12000"
  }
}

Observe que o valor de Data de contrato foi enviado como 15/04/2026 e retornado em ISO 8601 (2026-04-15T00:00:00.000Z). Números são sempre retornados como string.

Validação e erros

Todos os erros de campos customizados retornam 400 Bad Request. As mensagens são fixas e indicam exatamente o campo problemático:

  • Unknown custom fields: <nomes>Alguma chave do objeto customFields não existe como definição na entidade.
  • Valor numérico inválido: <valor>Campo do tipo number recebeu um valor que não pôde ser convertido para número.
  • Data inválida: <valor>Campo do tipo date recebeu valor fora dos formatos aceitos (DD/MM/AAAA, DD/MM/AAAA HH:MM ou ISO 8601).