O ID do campo — também chamado de código ou identificador simbólico — é o nome pelo qual o Bitrix24 reconhece o campo em robôs, processos de negócios, REST API e webhooks. Os campos do sistema têm códigos legíveis e fixos — TITLE, OPPORTUNITY; os de usuário recebem um código do tipo UF_CRM_ com um número. No artigo veremos onde ver o código do campo, por que o mesmo campo é escrito de formas diferentes em APIs diferentes e como usar os códigos na automação.

O que é o ID do campo e em que ele difere do nome?

Cada campo tem dois nomes. O nome — «Valor», «Origem» — é visto pelos usuários; pode ser alterado a qualquer momento, sem afetar o funcionamento do sistema. O código — OPPORTUNITY, SOURCE_ID — é o identificador interno: por ele o campo é encontrado pelos robôs, processos de negócios, requisições à API e modelos de documentos. O código é fixado na criação do campo e não muda depois. Daí a regra prática: na automação, apoie-se no código, e não no nome. Renomear o campo quebrará tudo o que estiver atrelado ao texto do nome e não tocará no que estiver atrelado ao código — por isso integrações e processos montados sobre códigos sobrevivem a qualquer ajuste cosmético da ficha.

Como descobrir o ID do campo nas configurações do CRM?

O caminho mais curto são as configurações de campos: abra CRM → Configurações, escolha a entidade e o campo desejado — o código é exibido na ficha do campo. Os códigos do sistema fazem sentido: TITLE — nome, OPPORTUNITY — valor, ASSIGNED_BY_ID — responsável, COMMENTS — comentário. Os campos de usuário recebem um código automático do tipo UF_CRM_ mais um número longo — defini-lo manualmente na criação pela interface não é possível, por isso um código «ilegível» é normal. Nas tarefas, os campos de usuário têm o prefixo UF_; nos processos inteligentes, os códigos seguem o mesmo princípio. Se o campo foi criado há tempos e ninguém lembra para quê, o código ajuda a encontrar todos os lugares onde ele é usado — de processos de negócios a webhooks.

Como obter a lista completa de campos pela API?

Quando os campos são dezenas, é mais cômodo requisitar a lista inteira de uma vez: os métodos REST do tipo crm.deal.fields e crm.contact.fields (ou o universal crm.item.fields) retornam um JSON com todos os campos da entidade — código, tipo e nome de cada um. Basta um webhook de entrada com permissões de CRM: cole a URL do método no navegador e obtenha o catálogo completo de campos do seu portal. Esse mesmo truque resolve o problema inverso — encontrar o código pelo nome quando as configurações do CRM não estão à mão. A lista de campos também é útil ao inserir valores em variáveis do processo de negócios: antes de montar o processo, vale anotar os códigos de todos os campos que ele lê e grava.

Por que TITLE e title são o mesmo campo?

No Bitrix24 há duas gerações de REST API, e os códigos são escritos de formas diferentes em cada uma. Os métodos antigos (crm.deal.update) e o designer de processos de negócios usam letras maiúsculas: TITLE, OPPORTUNITY, UF_CRM_…. A API universal crm.item.* usa camelCase: title, opportunity, assignedById. É o mesmo campo em duas grafias, e a confusão entre elas é uma causa frequente da situação «o robô rodou, mas o valor não foi gravado». Regra: confira o formato do código na documentação do método específico ou na dica do robô. Por exemplo, o robô «Atualizar negócio por ID» trabalha pela API universal e aceita JSON em camelCase: {"title":"Novo negócio","stageId":"C1:WON","opportunity":50000}.

Como usar os IDs de campos nos robôs?

Três operações típicas. Ler um valor pelo código — o robô «Obter valor de campo da entidade relacionada»: o tipo da entidade, seu ID e o código do campo (TITLE, ASSIGNED_BY_ID ou UF_CRM_…) — na saída, o valor e o indicador «encontrado» Y/N. Gravar vários campos de uma vez — «Atualizar negócio por ID»: o ID do negócio e um JSON cujas chaves são justamente os códigos dos campos. Interpretar a resposta de um sistema externo — «Extrair valor de JSON pelo caminho»: obtém o valor por um caminho separado por pontos (por exemplo, data.user.email) do JSON que um webhook ou serviço externo retornou e o devolve como string, mais o indicador «caminho encontrado» Y/N. Nos três casos, os códigos dos campos são a língua comum entre o CRM, o processo e os sistemas externos.

Conclusão

O código do campo é um identificador interno permanente: os códigos do sistema são legíveis (TITLE, OPPORTUNITY), os de usuário são gerados com o prefixo UF_CRM_. Veja os códigos nas configurações de campos do CRM ou pelos métodos *.fields e apoie-se apenas neles na automação. Os robôs para ler e gravar campos por código estão no catálogo da Roboteka; não há o de que você precisa — descreva a tarefa, fazemos o robô de graça.