Informações gerais

Campos personalizados podem ser adicionados a leads, contatos, empresas e listas
A URL do método depende da entidade

Tipos de campos disponíveis

Tipo	Nome
text	Texto
numeric	Número
checkbox	Caixa de seleção
select	Lista
multiselect	Lista de múltipla seleção
date	Data
url	URL
textarea	Área de texto
radiobutton	Interruptor
streetaddress	Endereço curto
smart_address	Endereço
birthday	Data de aniversário
legal_entity	ID fiscal
date_time	Data e hora
price	Preço
category	Categoria
file	Arquivo

Field types availability for entities

Tipo de campo	Contato	Lead	Empresa	Lista
Texto	✅	✅	✅	✅
Número	✅	✅	✅	✅
Caixa de seleção	✅	✅	✅	✅
Lista	✅	✅	✅	✅
Lista de múltipla seleção	✅	✅	✅	✅
Multitext	✅	❌	❌	❌
Data	✅	✅	✅	✅
URL	✅	✅	✅	✅
Data e hora	✅	✅	✅	✅
Área de texto	✅	✅	✅	✅
Interruptor	✅	✅	✅	✅
Endereço curto	✅	✅	✅	✅
Endereço	✅	✅	✅	❌
Data de aniversário	✅	✅	✅	❌
ID fiscal	✅	✅	✅	❌
Preço	❌	❌	❌	✅
Categoria	❌	❌	❌	✅
Produtos	❌	❌	❌	✅
Arquivo	✅	✅	✅	✅

Exemplos de preenchimento de diferentes tipos de campos via API

A seguir, consideraremos exemplos de solicitações para preenchimento de valores de diferentes tipos de campos.

Independentemente do tipo de campo, todos os valores são passados nos objetos do array custom_fields_values. Para preencher um campo, você precisa passar seu ID ou código de caractere, bem como os próprios valores.

Parâmetro	Tipo de dado	Descrição
custom_fields_values	array	Um array contendo informações sobre os valores de campos adicionais definidos para a entidade
custom_fields_values[0]	object	Um objeto contendo informações sobre o valor do campo opcional definido para a entidade
custom_fields_values[0][field_id]	int	ID do campo cujo valor você está preenchendo
custom_fields_values[0][field_code]	string	O código de caractere do campo cujo valor você está preenchendo (você deve passar field_id ou field_code para preenchê-lo)
custom_fields_values[0][values]	array	Array de valores preenchíveis
custom_fields_values[0][values][0]	object	Objeto do valor do campo. A estrutura do objeto depende do tipo de campo

Tipo de campo:

text, numeric, textarea, price, streetaddress, tracking_data, monetary

Neste exemplo, considere uma consulta para preencher campos do tipo text, numeric, textarea, price, streetaddress, tracking_datay monetary.

Parâmetro	Tipo de dado	Descrição
value	string	Valor do campo

...
"custom_fields_values": [
    {
        "field_id": 3,
        "values": [
            {
                "value": "Valor do campo"
            }
        ]
    },
    {
        "field_id": 103,
        "values": [
            {
                "value": "1.5"
            }
        ]
    },
    {
        "field_id": 203,
        "values": [
            {
                "value": "string1\nstring2"
            }
        ]
    },
    {
        "field_id": 303,
        "values": [
            {
                "value": "100"
            }
        ]
    },
    {
        "field_id": 403,
        "values": [
            {
                "value": "São Paulo, Rua Saburo Kagawa 6, 09751-510"
            }
        ]
    }
],
...

checkbox

Neste exemplo, vamos considerar uma solicitação para preencher campos do tipo checkbox.

Parâmetro	Tipo de dado	Descrição
value	bool	Valor do campo

...
"custom_fields_values": [
    {
        "field_id": 5,
        "values": [
            {
                "value": true
            }
        ]
    }
],
...

url

Neste exemplo, vamos considerar uma solicitação para preencher campos do tipo url.

Parameter	Data type	Descrição
value	string	Valor do campo. URL delegada

...
"custom_fields_values": [
    {
        "field_id": 7,
        "values": [
            {
                "value": "https://www.kommo.com/"
            }
        ]
    }
],
...

date, date_time, birthday

Neste exemplo, considere uma consulta para preencher campos do tipo date, date_timey birthday.

Parameter	Data type	Description
value	int\|string	Valor do campo - Timestamp Unix o timestamp no formato RFC-3339

...
"custom_fields_values": [
    {
        "field_id": 9,
        "values": [
            {
                "value": 1577836800
            }
        ]
    },
    {
        "field_id": 109,
        "values": [
            {
                "value": 1591965296
            }
        ]
    },
    {
        "field_id": 209,
        "values": [
            {
                "value": 1586476800
            }
        ]
    }
],
...

select, multiselect, radiobutton, category

Neste exemplo, considere uma consulta para preencher campos como select, multiselect, radiobutton y category. Um valor pode ser passado como um valor, seja um código de caractere do valor ou o ID do valor.

Parameter	Data type	Description
value	string	Valor do campo
enum_id	int	ID do valor do campo (enum)
enum code	string	Código simbólico do valor do campo (enum)

...
"custom_fields_values": [
    {
        "field_id": 11,
        "values": [
            {
                "value": "valor 1"
            }
        ]
    },
    {
        "field_id": 111,
        "values": [
            {
                "enum_id": 17
            },
            {
                "enum_id": 19
            }
        ]
    },
    {
        "field_id": 211,
        "values": [
            {
                "value": "valor 4"
            }
        ]
    }
],
...

smart_address

Neste exemplo, considere uma consulta para preencher campos do tipo smart_address. O campo aceita múltiplos valores. Os campos value e enum_id ou enum_code devem ser passados no valor.

Parameter	Data type	Description
value	string	Valor do campo
enum_id	int	Valor do campo. Valores disponíveis: 1 - Primeira linha do endereço, 2 - Segunda linha do endereço, 3 - Cidade, 4 - Região, 5 - CEP, 6 - País
enum_code	string	Código do valor do campo. Valores disponíveis: address_line_1 - Primeira linha do endereço, address_line_2 - Segunda linha do endereço, city - Cidade, state - Região, zip - CEP, country - País

...
"custom_fields_values": [
    {
        "field_id": 13,
        "values": [
            {
                "value": "Rua Saburo Kagawa 6",
                "enum_id": 1
            },
            {
                "value": "São Bernardo Do Campo",
                "enum_code": "cidade"
            },
            {
                "value": "São Paulo",
                "enum_code": "equipe"
            },
            {
                "value": "09751-510",
                "enum_id": 5
            },
            {
                "value": "Brasil",
                "enum_code": "País"
            }
        ]
    }
],
...

multitext

Neste exemplo, vamos considerar uma solicitação para preencher campos do tipo multitext (Telefone, Email). O campo aceita vários valores. Os campos value e enum_id ou enum_code devem ser passados no valor.

Parameter	Data type	Description
value	string	Valor do campo
enum_id	int	ID do alor do campo
enum_code	string	Código do valor do campo. Os valores disponíveis para o campo Phone são: WORK - trabalho, WORKDD - ramal de trabalho, MOB - celular, FAX - fax, HOME - casa, OTHER - outro. Os valores disponíveis para o campo E-mail são: WORK - trabalho, PRIV - pessoal, OTHER - outro.

...
"custom_fields_values": [
    {
        "field_id": 31,
        "values": [
            {
                "value": "+55(11) 9462-8268",
                "enum_id": 48224
            },
            {
                "value": "+55(84) 2462-6526",
                "enum_code": "INÍCIO"
            }
        ]
    }
],
...

legal_entity

Neste exemplo, vamos considerar uma consulta para preencher campos do tipo legal_entity. É obrigatório passar o campo nome no valor.

Parameter	Data type	Description
value	string	Valor do campo
value[name]	string	Nome da organização
value[entity_type]	int	Tipo de entidade jurídica. 1 - Privada, 2 - Jurídica
value[address]	string	Endereço da organização
value[real_address]	string	Endereço real da organização
value[bank_account_number]	int	Número da conta bancária
value[director]	string	Nome SEO
value[vat_id]	int	Número de identificação fiscal da organização (ou equivalente no seu país)
value[tax_registration_reason_code]	string	Código do motivo do registro fiscal
value[bank_code]	string	Código do banco
value[external_uid]	string	ID do sistema externo

...
"custom_fields_values": [
    {
        "field_id": 25,
        "values": [
            {
                "value": {
                    "name": "De Goiânia",
                    "entity_type": 1,
                    "vat_id": "123123123",
                    "tax_registration_reason_code": 213,
                    "address": "Rua Saburo Kagawa 6, São Bernardo Do Campo",                  
                    "external_uid": "uuid"
                }
            }
        ]
    }
],
...

linked_entity

Neste exemplo, considere uma consulta para preencher campos do tipo linked_entity.

Parameter	Data type	Description
value	object	Valor do campo
value[name]	string	Valor do campo exibido. Transmitido para exibição instantânea.
value[entity_id]	int	ID da entidade vinculada.
value[entity_type]	string	Tipo de entidade vinculada (contatos, empresas, etc.).
value[catalog_id]	int\|null	ID da lista, se o link for especificado.

...
"custom_fields_values": [
  {
    "field_id": 1150977,
    "values": [
      {
        "value": {
          "name": "João Silva",
          "entity_id": 24833339,
          "entity_type": "contactos",
          "catalog_id": null
        }
      }
    ]
  },
  {
    "field_id": 1150979,
    "values": [
      {
        "value": {
          "name": "Producto 1",
          "entity_id": 527597,
          "entity_type": "elementos_do_catalogo",
          "catalog_id": 6319
        }
      }
    ]
  }
],
...

chained_list

Neste exemplo, considere uma solicitação para preencher um campo do tipo chained_list.
O campo suporta múltiplos valores, até 5 elementos.

Parameter	Data type	Description
catalog_id	int	ID da lista, se um link para a lista for especificado.
catalog_element_id	int	ID do item da lista, se um link para a lista for especificado.

...
"custom_fields_values": [
  {
    "field_id": 1150985,
    "values": [
      {
        "catalog_id": 1001,
        "catalog_element_id": 12235
      },
      {
        "catalog_id": 1007,
        "catalog_element_id": 12243
      }
    ]
  }
],
...

file

Neste exemplo, considere uma consulta para preencher um campo do tipo file.

Parameter	Data type	Description
value	object	Valor do campo
value[file_uuid]	string	UUID de um arquivo no serviço de arquivos
value[version_uuid]	string	UUID da versão do arquivo no serviço de arquivos
value[file_name]	string	Nome do arquivo
value[file_size]	int	Tamanho do arquivo

...
"custom_fields_values": [
  {
    "field_id": 1150985,
    "values": [
      {
        "value": {
          "file_uuid": "3b454645-5c7f-4539-9ef9-0dd1b3638dad",
          "version_uuid": "13db6652-b3ed-4fff-aed8-0c6f3c43b887",
          "file_name": "wiki.odt",
          "file_size": 20763,
        }
      }
    ]
  }
],
...