> ## Documentation Index > Fetch the complete documentation index at: https://developers.vendaze.com/llms.txt > Use this file to discover all available pages before exploring further. # Campos Adicionais > Como criar, configurar e associar campos adicionais a pessoas, empresas e negócios na API da Vendaze. Campos adicionais permitem que cada workspace capture informações específicas do seu processo comercial que não fazem parte do schema padrão da Vendaze: CNPJ, origem do lead, segmento de mercado, pontuação interna ou qualquer outro dado relevante. Cada campo pertence ao workspace, tem um tipo fixo e pode ser exibido em pessoas, empresas e/ou negócios conforme a configuração de visibilidade. ## Fluxo correto de uso O uso seguro de campos adicionais segue uma ordem específica que evita problemas de tipagem e inconsistências nos dados. **1. Criar o campo no workspace** Antes de associar valores a qualquer registro, o campo precisa existir com o tipo correto configurado. Use `POST /v1/custom-fields` para isso. **2. Associar valores nos registros** Com o campo criado, passe `custom_fields` no body de `POST` ou `PATCH` em pessoas, empresas ou negócios, referenciando o campo pela sua `key`. ### Por que criar o campo antes Ao enviar uma `field_key` desconhecida nas rotas de pessoa, empresa ou negócio, a API cria o campo automaticamente com `type: text`. Isso pode parecer conveniente, mas cria um problema real: se o campo precisar ser `select`, `date`, `number` ou qualquer outro tipo, ele terá sido criado com o tipo errado. Corrigir isso depois exige uma chamada separada de atualização e pode gerar inconsistências em valores já gravados. Crie sempre o campo com o tipo correto antes de começar a gravar valores. *** ## Criar um campo adicional ```bash theme={null} POST /v1/custom-fields ``` Campos obrigatórios: `label`, `key` e `type`. ```json theme={null} { "label": "Origem do Lead", "key": "origem_lead", "type": "select", "value": { "select_list": [ { "key": "sl_indicacao", "option": "Indicação" }, { "key": "sl_inbound", "option": "Inbound" }, { "key": "sl_evento", "option": "Evento" } ] }, "show_people": true, "show_companies": false, "show_deals": true } ``` Regras de criação: * `key` é imutável após a criação. Use identificadores descritivos e estáveis, como `origem_lead` ou `cnpj_empresa`. * `type` também é imutável. Escolha o tipo correto antes de criar. * Para `select` e `multi_select`, o campo `value.select_list` é obrigatório e define as opções disponíveis. * Os flags `show_people`, `show_companies` e `show_deals` controlam em quais entidades o campo aparece. O padrão é `true` para pessoas e empresas, `false` para negócios. ### Tipos disponíveis | Tipo | Descrição | | -------------- | ---------------------------------------- | | `text` | Texto em linha única | | `long_text` | Texto multilinha | | `number` | Valor numérico inteiro ou decimal | | `date` | Data no formato `YYYY-MM-DD` | | `select` | Uma opção de lista predefinida | | `multi_select` | Múltiplas opções de lista predefinida | | `cpf` | CPF brasileiro | | `cnpj` | CNPJ brasileiro | | `link` | URL completa | | `address` | Endereço físico estruturado em subcampos | *** ## Associar valores a registros Com o campo criado, inclua `custom_fields` no body ao criar ou atualizar um registro. Cada item requer `field_key` e `value`. ```bash theme={null} POST /v1/people ``` ```json theme={null} { "full_name": "Ana Costa", "emails": [{ "email": "ana@acme.com", "type": "work" }], "custom_fields": [ { "field_key": "origem_lead", "value": "sl_indicacao" }, { "field_key": "pontuacao", "value": 85 } ] } ``` A API resolve `field_key` para o ID interno do campo. Caso nenhum campo com essa chave exista no workspace, ele é criado automaticamente com `type: text`. Veja a seção acima sobre por que isso deve ser evitado. ### Modo de associação O parâmetro `association_mode` controla o comportamento ao atualizar um registro via `PATCH`: * `append` (padrão): define ou substitui o valor de cada `field_key` enviado, sem alterar os demais campos do registro. * `replace`: remove todos os valores de campos adicionais do registro e insere apenas os enviados nesta requisição. *** ## Referência de formatos por tipo ### `text` String simples, linha única. ```json theme={null} { "field_key": "cargo_interno", "value": "Gerente Comercial" } ``` ### `long_text` String com quebras de linha representadas por `\n`. ```json theme={null} { "field_key": "observacoes", "value": "Cliente preferencial.\nContactar apenas por email." } ``` ### `number` Número JSON sem aspas. Aceita inteiro ou decimal. ```json theme={null} { "field_key": "numero_funcionarios", "value": 120 } ``` ```json theme={null} { "field_key": "pontuacao_interna", "value": 7.5 } ``` ### `date` String no formato `YYYY-MM-DD`, sem horário. ```json theme={null} { "field_key": "data_contrato", "value": "2026-08-15" } ``` ### `select` Key de uma única opção da lista predefinida do campo. Para consultar as keys disponíveis, use `GET /v1/custom-fields/:id` e inspecione `value.select_list`. ```json theme={null} { "field_key": "segmento", "value": "sl_tecnologia" } ``` Enviar uma key inexistente na lista retorna erro de validação. ### `multi_select` Array JSON com as keys das opções selecionadas. ```json theme={null} { "field_key": "produtos_de_interesse", "value": ["sl_plano_basico", "sl_plano_avancado"] } ``` Para selecionar apenas uma opção, passe um array com um elemento. Para limpar todas as seleções, passe um array vazio. ```json theme={null} { "field_key": "produtos_de_interesse", "value": [] } ``` ### `cpf` String com ou sem pontuação. ```json theme={null} { "field_key": "cpf_responsavel", "value": "123.456.789-09" } ``` ### `cnpj` String com ou sem pontuação. ```json theme={null} { "field_key": "cnpj_empresa", "value": "12.345.678/0001-90" } ``` ### `link` URL completa com protocolo. ```json theme={null} { "field_key": "linkedin", "value": "https://linkedin.com/in/ana-costa" } ``` ### `address` Objeto JSON com os subcampos abaixo. Todos são opcionais: envie apenas os que estiverem disponíveis. Subcampos não enviados são armazenados como string vazia. | Subcampo | Descrição | | ---------------- | -------------------------------- | | `address_line_1` | Logradouro e número | | `address_line_2` | Complemento (sala, andar, bloco) | | `city` | Cidade | | `region` | Estado ou região | | `postal_code` | CEP ou código postal | | `country` | País | ```json theme={null} { "field_key": "endereco_sede", "value": { "address_line_1": "Avenida Paulista, 1000", "address_line_2": "Sala 42", "city": "São Paulo", "region": "SP", "postal_code": "01310-100", "country": "Brasil" } } ``` *** ## Ler valores de um registro Ao buscar um registro por ID, os valores associados retornam no array `custom_fields` com o objeto `field` embutido: ```json theme={null} { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "full_name": "Ana Costa", "custom_fields": [ { "id": "cf-assoc-uuid", "value": "sl_indicacao", "field": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "label": "Origem do Lead", "key": "origem_lead", "type": "select" } } ] } } ``` *** ## Exemplo completo O exemplo abaixo cria uma pessoa com campos de todos os tipos, considerando que cada campo já foi criado previamente via `POST /v1/custom-fields`. ```json theme={null} POST /v1/people { "full_name": "Ana Costa", "emails": [{ "email": "ana@acme.com", "type": "work" }], "custom_fields": [ { "field_key": "cpf_responsavel", "value": "123.456.789-09" }, { "field_key": "cnpj_empresa", "value": "12.345.678/0001-90" }, { "field_key": "segmento", "value": "sl_tecnologia" }, { "field_key": "produtos_interesse", "value": ["sl_plano_basico", "sl_plano_avancado"] }, { "field_key": "numero_funcionarios", "value": 120 }, { "field_key": "data_contrato", "value": "2026-08-15" }, { "field_key": "linkedin", "value": "https://linkedin.com/in/ana-costa" }, { "field_key": "observacoes", "value": "Cliente indicado pela parceira Acme." }, { "field_key": "endereco_sede", "value": { "address_line_1": "Avenida Paulista, 1000", "address_line_2": "Sala 42", "city": "São Paulo", "region": "SP", "postal_code": "01310-100", "country": "Brasil" } } ] } ```