"Atualizar um campo do negócio" parece tarefa de uma linha — até o campo se recusar em silêncio a mudar: a requisição devolve sucesso e o card mostra o valor antigo. A causa é quase sempre uma de três: a geração errada do método, o formato errado do nome do campo ou a forma errada do valor. Veja como a atualização de campos do negócio realmente funciona no Bitrix24 (Alaio): da chamada REST crua à regra de automação sem código.

Qual método atualiza um campo do negócio?

A resposta atual é o método universal crm.item.update: passe entityTypeId 2 (negócio), o id do negócio e um objeto fields contendo apenas os campos a alterar — tudo que for omitido permanece intocado.

{"entityTypeId": 2, "id": 351, "fields": {"stageId": "C1:WON", "opportunity": 50000}}

O método antigo por entidade crm.deal.update ainda funciona e aparece na maioria dos tutoriais, mas pertence à geração legada: mesmos campos, nomenclatura diferente. Integrações novas devem adotar crm.item.update por padrão — ele cobre negócios, leads, contatos, empresas e processos inteligentes com um único contrato.

Por que o campo não atualiza?

O primeiro suspeito é a caixa das letras. A API legada e o designer de processos escrevem os códigos de campo em maiúsculas: TITLE, OPPORTUNITY, UF_CRM_1721244707107. A API universal escreve os mesmos campos em camelCase: title, opportunity, ufCrm_1721244707107. Envie TITLE para crm.item.update e ele será ignorado como chave desconhecida — com mensagem de sucesso. Se quiser que o método universal aceite os nomes originais UF_CRM_*, passe useOriginalUfNames com valor Y. O segundo suspeito é a forma do valor: um campo de lista espera o id do item, não o rótulo; um campo de data espera um formato de data correto; e um valor inválido devolve CRM_FIELD_ERROR_VALUE_NOT_VALID apontando o campo. Onde consultar os códigos de campo está no artigo sobre IDs de campos no Bitrix24.

Como atualizo telefone, e-mail e outros multicampos?

Telefones e e-mails vivem no array de multicampos fm, e na sua semântica de atualização todo mundo tropeça pelo menos uma vez: linhas existentes são endereçadas pelo id — uma linha com id altera a entrada no lugar —, enquanto linhas sem id conhecido são acrescentadas como novas. Mandar um conjunto "fresco" de valores sem ids não substitui os antigos: apenas acrescenta, e o contato do negócio acumula em silêncio telefones duplicados. Leia primeiro as linhas fm atuais e depois atualize pelo id.

Como atualizo um campo a partir de um webhook?

Para uma integração de portal único não é preciso aplicativo OAuth: um webhook de entrada entrega uma URL que carrega a autorização em si. Crie-o com o escopo crm e lembre que o webhook age com as permissões do funcionário que o criou — se essa pessoa não enxerga o funil, a chamada falha com erro de acesso mesmo com token válido. Método, id e fields entram na requisição exatamente como acima. A configuração passo a passo está no guia de webhooks; se em vez de resultado voltar um código de erro, ele aponta direto o campo ou o problema de permissão — registre o código, não só a descrição.

Como atualizar campos do negócio sem código?

Dentro do portal, a maioria das atualizações de campo nem precisa de REST — uma regra de automação na etapa resolve. A regra padrão "Editar item" cobre um campo com valor estático. Quando vários campos mudam de uma vez, ou os valores vêm de passos anteriores, a regra Atualizar negócio por ID do catálogo da Roboteka recebe um objeto JSON no mesmo formato camelCase do crm.item.update e grava tudo em uma ação. Esvaziar um campo é um caso à parte — string vazia não limpa listas, datas nem multicampos; para isso existe a regra Limpar campo, que zera corretamente qualquer tipo. Para mover um valor entre entidades — copiar a cidade do contato para o negócio, por exemplo — use Gravar campo da entidade vinculada, e contra campos críticos vazios antes de uma troca de etapa, Verificar campo preenchido devolve Y/N para ramificar com uma condição. Uma ação dentro do processo também é a resposta barata para "preciso montar um cenário externo para isso?": sem tokens para renovar, sem limites de requisição para orçar — a atualização roda onde o negócio vive.

O que vem depois

Comece pela falha que você realmente tem: caixa errada — mude para camelCase ou ative useOriginalUfNames; telefones duplicados — atualize as linhas fm pelo id; erros de acesso — confira as permissões do criador do webhook. Tudo que deve reagir a eventos do negócio em vez de chamadas externas, construa como regras de automação no Bitrix24 — as regras de atualização acima são blocos comuns por lá. E se faltar o bloco de que você precisa, descreva a tarefa: a Roboteka constrói de graça as regras de automação que faltam e as publica na biblioteca compartilhada.