Campos personalizados

Uma definição de campo personalizado pertence a UM tipo de registro (applies_to: contact, company, deal ou product) — o mesmo rótulo em dois tipos vira duas…

Uma definição de campo personalizado pertence a UM tipo de registro (applies_to: contact, company, deal ou product) — o mesmo rótulo em dois tipos vira duas definições separadas. Definições e valores de contato, empresa e negócio são cobertos: POST/PATCH/GET unitário, lote (POST/PATCH .../batch), POST/api/leads (só negócio) e exportação em CSV (§15) — uma coluna por definição, em cada um dos três recursos. Produto também tem campo personalizado, com o mesmo formato de custom_fields descrito abaixo — ver a referência de Produtos.

{ "id": "…", "key": "produto_de_interesse", "label": "Produto de interesse", "type": "text", "options": [], "applies_to": "deal", "position": 0 }
Campo Obrigatório Regras
label sim 1–80
type sim text, number, date, select, boolean — imutável depois de criado
applies_to sim contact, company, deal ou product (singular — uma definição, uma entidade)
options só em select [{ "value": "…", "label": "…" }] — pelo menos 1, no máximo 50; value e label com 1–80 cada, e nenhuma outra chave dentro da opção
position não (só na edição) inteiro ≥ 0 — a ordem na tela
key não slug único por conta e entidade — ⛔ só a-z, 0-9 e _, até 80 caracteres. Hífen é recusado com 400 (cpf-do-cliente não passa; cpf_do_cliente passa). Omitido, é derivado do label
Método Escopo Descrição
GET/api/custom-fields contacts:read/companies:read/deals:read/products:read Lista definições da conta. ?applies_to= filtra por entidade e exige o escopo daquela entidade; sem filtro, devolve as entidades juntas (só as que a chave tiver escopo pra ler)
POST/api/custom-fields contacts:write/companies:write/deals:write/products:write conforme applies_to Cria (201). key repetida na conta e na mesma entidade devolve 409 com existing_id
PATCH/api/custom-fields/{id} idem Edita label, key, options, position. Mandar type no corpo devolve 400 (unknown_field) — o tipo não muda depois de criado
DELETE/api/custom-fields/{id} idem Apaga a definição e todos os valores gravados nela (204)

GET/api/custom-fields devolve tudo sem paginação (next_cursor: null) — não aceita ?limit=/?cursor= (mesma ressalva dos catálogos de origem e motivo de perda, seção 9.2).

Valor no registro — o campo custom_fields aceita um objeto onde cada chave é a key ou o id (uuid) da definição, igual nas 3 entidades. Em POST/PATCH /api/{contacts,companies, deals} (unitário e lote) o campo vai direto no corpo:

{ "custom_fields": { "produto_de_interesse": "Plano PRO", "cpf": "123.456.789-00" } }

⛔ Em POST/api/leads ele também fica na RAIZ do corpo, nunca dentro de deal. O objeto deal não aceita chave desconhecida: custom_fields ali dentro devolve 400 unknown_field — "O campo deal.custom_fields não existe nesta chamada" — e o lead inteiro se perde. Os valores vão para o negócio, então o corpo precisa ter deal; sem negócio, é 400 (leads só criam negócio, nunca contato ou empresa avulsos com campo personalizado próprio).

{
  "external_ref": "form-8412",
  "contact": { "name": "Maria Souza", "phone": "+5511999998888" },
  "deal": { "name": "Orçamento — Maria Souza" },
  "custom_fields": { "produto_de_interesse": "Plano PRO" }
}
  • Valor incompatível com o tipo devolve 400 nomeando a chave — number só aceita número nativo do JSON (nunca string), date só AAAA-MM-DD, select só uma das options cadastradas, boolean só true/false (nunca "sim", nunca 1).
  • Chave que não existe na conta devolve 400 nomeando a chave — a API nunca cria uma definição nova a partir de um valor recebido.
  • PATCH toca só as chaves ENVIADAS — mandar null numa chave apaga só aquele valor; as demais chaves gravadas antes continuam intactas.
  • O GET unitário e a listagem sempre devolvem custom_fields, chaveado por key — {} quando o registro não tem nenhum valor gravado, nunca campo ausente. Vale para contato, empresa e negócio.

⛔⛔ Existe um 2xx em que o registro nasceu e o campo personalizado NÃO. Se a gravação dos valores falhar depois de o registro já estar criado, a resposta continua 201/200 — o registro existe mesmo — e traz o cabeçalho:

x-salos-custom-fields-write-failed: custom_fields

⛒ Por que não é 500: desfazer a criação seria pior (você reenviaria e criaria de novo). ⛔ O que fazer: numa importação em massa, cheque esse cabeçalho. Se ele vier, reenvie só PATCH { "custom_fields": … } naquele registro — sem ele, um pipeline de milhares de registros perde valores sem nenhum sinal na tela.