Ir para o conteúdo
Pipefácil

Criar campo personalizado

Ver como MarkdownConfigurar agente
POST/api/v1/custom-fields

Cria a definição de um campo personalizado no workspace da chave. Exige settings.custom_fields.

Exemplos

A URL usa o servidor de produção. Defina PIPEFACIL_API_KEY e as variáveis de caminho (como SEQ ou ID) com os identificadores reais. Ajuste o corpo antes de executar: requisições de escrita alteram dados do workspace.

cURL

curl --request POST \
  --url "https://pipefacil-server.matchsales.com.br/api/v1/custom-fields" \
  --header "Authorization: Bearer $PIPEFACIL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Segmento",
  "fieldType": "text"
}'
JavaScript
const response = await fetch(`https://pipefacil-server.matchsales.com.br/api/v1/custom-fields`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PIPEFACIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Segmento",
  "fieldType": "text"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const text = await response.text();
const data = text ? JSON.parse(text) : null;
Python
import os
import json
import requests

response = requests.request(
    "POST",
    f"https://pipefacil-server.matchsales.com.br/api/v1/custom-fields",
    headers={"Authorization": f"Bearer {os.environ['PIPEFACIL_API_KEY']}"},
    json=json.loads("{\n  \"name\": \"Segmento\",\n  \"fieldType\": \"text\"\n}"),
)
response.raise_for_status()
data = response.json() if response.content else None

Corpo da requisição

Content-Type: application/json · obrigatório

{
  "name": "Segmento",
  "fieldType": "text"
}
CampoTipoObrigatório no objetoDescrição
namestringSimAté 255 caracteres.
slugstringNãoGerado a partir do nome quando omitido. Aceita null. Até 255 caracteres.
descriptionstringNãoAceita null. Até 1000 caracteres.
placeholderstringNãoTexto de exemplo exibido no campo vazio do aplicativo. Apenas visual; não é salvo como valor. Aceita null. Até 255 caracteres.
fieldTypestringSimmembers apresenta os membros atuais do workspace; o valor salvo é um userId, e options enviado é descartado. event armazena data e hora e cria uma reunião na agenda do responsável, conforme config.event. Alterar o campo move a reunião; limpar o campo a exclui. Mover ou excluir a reunião no calendário ou no Google atualiza ou limpa o campo. Disponível apenas para campos de negócio. Valores: text, textarea, number, currency, boolean, date, datetime, select, multi_select, url, email, phone, file_upload, members, event.
optionsarrayNãoObrigatório para tipos com opções (select, multi_select). Ignorado para members. Aceita null.
configobjectNãoConfiguração por tipo de campo. Para event, informe event com título, duração e configuração da reunião. member_field usa fieldSlug para ler um membro a partir de um campo members do lead. Aceita null.
config.eventEventFieldConfigNão—
config.event.titlestringSimAté 255 caracteres.
config.event.descriptionstringNãoAceita null. Até 2000 caracteres.
config.event.durationMinutesintegerSimMínimo: 1. Máximo: 1440.
config.event.conferenceModestringNãoValores: none, google_meet, custom_field. Aceita null.
config.event.conferenceFieldSlugstringNãoAceita null.
config.event.recordWithBotbooleanNãoAceita null.
config.event.attendeesarrayNãoAceita null.
config.event.attendees[].typestringNãoValores: lead_contact, deal_co_owner, member, contact, member_field.
config.event.attendees[].userIdstringNãoAceita null.
config.event.attendees[].contactIdstringNãoAceita null.
config.event.attendees[].fieldSlugstringNãoSlug do campo members cujo usuário será convidado. Lido novamente quando o campo mudar. Aceita null.
config.event.attendees[].labelstringNãoRótulo usado pelo editor; não determina a identidade do convidado. Aceita null. Até 255 caracteres.
isRequiredbooleanNãoAceita null.
apiOnlybooleanNãoQuando verdadeiro, os valores do campo no negócio só podem ser alterados pela API pública; o aplicativo exibe o campo como somente leitura. Aceita null.
displayOrderintegerNãoAceita null. Mínimo: 0.
sectionstringNãoAceita null. Até 255 caracteres.
entityTypestringNãoPadrão: deal. Aceita null. Até 50 caracteres.
visibilityRuleobjectNãoAceita null.
visibilityRule.parentFieldIdstringSim—
visibilityRule.valuesarraySim—
Esquema OpenAPI
{
  "type": "object",
  "required": [
    "name",
    "fieldType"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 255
    },
    "slug": {
      "type": "string",
      "maxLength": 255,
      "nullable": true,
      "description": "Gerado a partir do nome quando omitido."
    },
    "description": {
      "type": "string",
      "maxLength": 1000,
      "nullable": true
    },
    "placeholder": {
      "type": "string",
      "maxLength": 255,
      "nullable": true,
      "description": "Texto de exemplo exibido no campo vazio do aplicativo. Apenas visual; não é salvo como valor."
    },
    "fieldType": {
      "type": "string",
      "enum": [
        "text",
        "textarea",
        "number",
        "currency",
        "boolean",
        "date",
        "datetime",
        "select",
        "multi_select",
        "url",
        "email",
        "phone",
        "file_upload",
        "members",
        "event"
      ],
      "description": "`members` apresenta os membros atuais do workspace; o valor salvo é um `userId`, e `options` enviado é descartado. `event` armazena data e hora e cria uma reunião na agenda do responsável, conforme `config.event`. Alterar o campo move a reunião; limpar o campo a exclui. Mover ou excluir a reunião no calendário ou no Google atualiza ou limpa o campo. Disponível apenas para campos de negócio."
    },
    "options": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "additionalProperties": true
      },
      "description": "Obrigatório para tipos com opções (`select`, `multi_select`). Ignorado para `members`."
    },
    "config": {
      "type": "object",
      "additionalProperties": true,
      "nullable": true,
      "description": "Configuração por tipo de campo. Para event, informe event com título, duração e configuração da reunião. member_field usa fieldSlug para ler um membro a partir de um campo members do lead.",
      "properties": {
        "event": {
          "$ref": "#/components/schemas/EventFieldConfig"
        }
      }
    },
    "isRequired": {
      "type": "boolean",
      "nullable": true
    },
    "apiOnly": {
      "type": "boolean",
      "nullable": true,
      "description": "Quando verdadeiro, os valores do campo no negócio só podem ser alterados pela API pública; o aplicativo exibe o campo como somente leitura."
    },
    "displayOrder": {
      "type": "integer",
      "minimum": 0,
      "nullable": true
    },
    "section": {
      "type": "string",
      "maxLength": 255,
      "nullable": true
    },
    "entityType": {
      "type": "string",
      "maxLength": 50,
      "nullable": true,
      "description": "Padrão: `deal`."
    },
    "visibilityRule": {
      "allOf": [
        {
          "$ref": "#/components/schemas/CustomFieldVisibilityRule"
        }
      ],
      "nullable": true
    }
  },
  "example": {
    "name": "Segmento",
    "fieldType": "text"
  }
}

Respostas

201Criado
CampoTipoDescrição
dataCustomFieldDefinition—
data.idstring—
data.entityTypestring—
data.namestring—
data.slugstring—
data.descriptionstringAceita null.
data.placeholderstringTexto de exemplo exibido no campo vazio. Aceita null.
data.fieldTypestring—
data.optionsarrayOpções de seleção. Em select e multi_select, ficam na definição. Em members, são calculadas a partir dos membros do workspace a cada leitura; value é o userId do membro. Aceita null.
data.options[].valuestring—
data.options[].labelstring—
data.options[].colorstringAceita null.
data.options[].imagestringURL da foto. Somente para members. Aceita null.
data.options[].inactivebooleanSomente para members. Verdadeiro para membro desativado. Ele permanece na lista para resolver nomes de valores anteriores. Não o ofereça para novas escolhas nem altere valores já salvos por causa dessa marcação.
data.configobjectConfiguração por tipo de campo. Para event, informe event com título, duração e configuração da reunião. member_field usa fieldSlug para ler um membro a partir de um campo members do lead. Aceita null.
data.config.eventEventFieldConfig—
data.config.event.titlestringAté 255 caracteres.
data.config.event.descriptionstringAceita null. Até 2000 caracteres.
data.config.event.durationMinutesintegerMínimo: 1. Máximo: 1440.
data.config.event.conferenceModestringValores: none, google_meet, custom_field. Aceita null.
data.config.event.conferenceFieldSlugstringAceita null.
data.config.event.recordWithBotbooleanAceita null.
data.config.event.attendeesarrayAceita null.
data.config.event.attendees[].typestringValores: lead_contact, deal_co_owner, member, contact, member_field.
data.config.event.attendees[].userIdstringAceita null.
data.config.event.attendees[].contactIdstringAceita null.
data.config.event.attendees[].fieldSlugstringSlug do campo members cujo usuário será convidado. Lido novamente quando o campo mudar. Aceita null.
data.config.event.attendees[].labelstringRótulo usado pelo editor; não determina a identidade do convidado. Aceita null. Até 255 caracteres.
data.isRequiredboolean—
data.apiOnlybooleanValores dos negócios são somente leitura no aplicativo e podem ser alterados por /api/v1.
data.displayOrderinteger—
data.sectionstringAceita null.
data.pipelineConfigobjectAceita null.
data.createdAtstringFormato: date-time.
data.updatedAtstringFormato: date-time.
data.visibilityRuleobjectAceita null.
data.visibilityRule.parentFieldIdstring—
data.visibilityRule.valuesarray—
messagestringAceita null.
Esquema OpenAPI
{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/CustomFieldDefinition"
    },
    "message": {
      "type": "string",
      "nullable": true
    }
  }
}
400Falha de validação dos campos; `fieldErrors` contém os erros.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
401Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
403Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
409Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
429Limite de requisições excedido por workspace ou IP.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
OpenAPI JSONMarkdown desta operação

Precisa de ajuda?

Encontrou um problema ou ficou com uma dúvida? Fale com a equipe pelo WhatsApp.

Chamar no WhatsApp
Pipefácil