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
400nomeando a chave —numbersó aceita número nativo do JSON (nunca string),datesóAAAA-MM-DD,selectsó uma dasoptionscadastradas,booleansótrue/false(nunca"sim", nunca1). - Chave que não existe na conta devolve
400nomeando a chave — a API nunca cria uma definição nova a partir de um valor recebido. PATCHtoca só as chaves ENVIADAS — mandarnullnuma chave apaga só aquele valor; as demais chaves gravadas antes continuam intactas.- O
GETunitário e a listagem sempre devolvemcustom_fields, chaveado porkey—{}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.