Criar um campo personalizado

POST

/custom-fields

const url = 'https://dattacrm.com.br/api/v1/custom-fields';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"label":"example","key":"example","type":"text","options":[{"label":"example","value":"example"}],"group":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://dattacrm.com.br/api/v1/custom-fields \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "label": "example", "key": "example", "type": "text", "options": [ { "label": "example", "value": "example" } ], "group": "example" }'

Cria um campo personalizado de lead, no grupo informado ou no padrão. Não cria campo que repete um campo padrão do CRM (contato, UTMs e rastreio, como email, utm_source ou fbclid, pela chave ou pelo nome): responde 400. Idempotente pela chave, sem diferenciar maiúsculas: se já existe um campo com a mesma chave e o mesmo tipo, devolve ele como está (200, result: matched), sem mudar nome, opções nem grupo; com outro tipo, responde 409 conflict com details.field = type. Campo novo responde 201 com result: created e já vale em customFields de create_or_update_lead.

Authorizations

bearerAuth

Request Body^required

application/json

Dados do novo campo personalizado de lead.

object

label

required

Nome do campo, como aparece na tela, de 1 a 60 caracteres.

string

>= 1 characters <= 60 characters

key

Chave do campo em customFields, de 1 a 40 caracteres: letras sem acento, números e _. É gravada em minúsculas (Cargo vira cargo). Sem ela, deriva do nome (Cargo do lead vira cargo_do_lead). Não pode ser a de um campo nativo: name, email, phone, company, address ou notes.

string

>= 1 characters <= 40 characters /^[A-Za-z0-9_]+$/

type

Tipo do campo: text (padrão), number, date, select, multi_select ou boolean.

string

Allowed values: text number date select multi_select boolean

options

Opções de select e multi_select, até 100: textos (["Sim", "Não"]) ou { label, value }. Ignoradas nos outros tipos.

Array

<= 100 items

Any of:

string
object

Texto da opção; o valor deriva dele.

string

group

Grupo do campo em Leads > Campos, pelo id ou pelo nome (sem diferenciar maiúsculas). O grupo precisa existir: crie-o na tela de Campos. Sem ele, o campo vai para o grupo padrão (Geral).

string

>= 1 characters <= 80 characters

Responses

200

O campo já existia com a mesma chave e o mesmo tipo e foi devolvido como está (result: matched).

application/json

object

data

required

Campo personalizado de lead, criado ou já existente.

object

key

required

Chave estável do campo, usada em customFields do lead.

string

label

required

Nome do campo, como aparece na tela.

string

type

required

Tipo do campo: text, number, date, select, multi_select ou boolean.

string

Allowed values: text number date select multi_select boolean

options

required

Opções permitidas; vazio nos campos que não são de seleção.

Array<object>

Opção de um campo de seleção.

object

label

required

Texto da opção, como aparece para a pessoa.

string

value

required

Valor gravado no lead quando a opção é escolhida.

string

group

required

Grupo do campo em Leads > Campos. Todo campo tem um; o padrão é Geral.

object

required

Id do grupo.

string

name

required

Nome do grupo, como aparece em Leads > Campos.

string

result

required

created quando o campo foi criado agora; matched quando já existia com a mesma chave e o mesmo tipo.

string

Allowed values: created matched

Example

{
  "data": {
    "type": "text",
    "result": "created"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

X-RateLimit-Limit

integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining

integer

Requisições restantes na janela atual.

X-RateLimit-Reset

integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

201

Campo criado (result: created).

application/json

object

data

required

Campo personalizado de lead, criado ou já existente.

object

key

required

Chave estável do campo, usada em customFields do lead.

string

label

required

Nome do campo, como aparece na tela.

string

type

required

Tipo do campo: text, number, date, select, multi_select ou boolean.

string

Allowed values: text number date select multi_select boolean

options

required

Opções permitidas; vazio nos campos que não são de seleção.

Array<object>

Opção de um campo de seleção.

object

label

required

Texto da opção, como aparece para a pessoa.

string

value

required

Valor gravado no lead quando a opção é escolhida.

string

group

required

Grupo do campo em Leads > Campos. Todo campo tem um; o padrão é Geral.

object

required

Id do grupo.

string

name

required

Nome do grupo, como aparece em Leads > Campos.

string

result

required

created quando o campo foi criado agora; matched quando já existia com a mesma chave e o mesmo tipo.

string

Allowed values: created matched

Example

{
  "data": {
    "type": "text",
    "result": "created"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

X-RateLimit-Limit

integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining

integer

Requisições restantes na janela atual.

X-RateLimit-Reset

integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

400

Dados inválidos (validation_error): chave fora do formato, chave ou nome de campo padrão do CRM, nome do qual não sai chave ou grupo que não existe, ou chave enviada na URL (api_key_in_url).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

401

Chave ausente, inválida (invalid_api_key), vencida (api_key_expired) ou revogada (api_key_revoked).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

403

A chave é somente leitura e a operação grava dados (insufficient_scope).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

409

Conflito com o estado atual (conflict), contato oculto, cujo negócio não muda (lead_hidden), ou limite do plano atingido (plan_limit).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

413

O corpo da requisição passa de 256 KB (payload_too_large).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

429

Limite de requisições atingido (rate_limited). Aguarde Retry-After segundos.

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

X-RateLimit-Limit

integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining

integer

Requisições restantes na janela atual.

X-RateLimit-Reset

integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

Retry-After

integer

Segundos até poder tentar de novo.

500

Erro interno (internal_error). Informe o requestId ao suporte.

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

503

O CRM está em modo somente leitura durante uma migração (maintenance). Tente de novo depois de Retry-After segundos.

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

Retry-After

integer

Segundos até poder tentar de novo.

Criar um campo personalizado

Authorizations

Request Body required

Responses

200

Example

Headers

201

Example

Headers

400

Example generated

Headers

401

Example generated

Headers

403

Example generated

Headers

409

Example generated

Headers

413

Example generated

Headers

429

Example generated

Headers

500

Example generated

Headers

503

Example generated

Headers

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated