Consultar campo personalizado

GET/api/v1/custom-fields/{id}

Retorna a definição de um campo de qualquer entidade pelo identificador. Fora do workspace, responde 404. Disponível para qualquer chave válida.

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 GET \
  --url "https://pipefacil-server.matchsales.com.br/api/v1/custom-fields/$ID" \
  --header "Authorization: Bearer $PIPEFACIL_API_KEY"

JavaScript

const response = await fetch(`https://pipefacil-server.matchsales.com.br/api/v1/custom-fields/${process.env.ID}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.PIPEFACIL_API_KEY}`,
  },
});

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(
    "GET",
    f"https://pipefacil-server.matchsales.com.br/api/v1/custom-fields/{os.environ['ID']}",
    headers={"Authorization": f"Bearer {os.environ['PIPEFACIL_API_KEY']}"},
)
response.raise_for_status()
data = response.json() if response.content else None

Parâmetros

Nome	Local	Tipo	Obrigatório	Descrição
`id`	`path`	`string`	Sim	Identificador do campo personalizado.

Respostas

200Sucesso

Campo	Tipo	Descrição
`data`	`CustomFieldDefinition`	—
`data.id`	`string`	—
`data.entityType`	`string`	—
`data.name`	`string`	—
`data.slug`	`string`	—
`data.description`	`string`	Aceita null.
`data.placeholder`	`string`	Texto de exemplo exibido no campo vazio. Aceita null.
`data.fieldType`	`string`	—
`data.options`	`array`	Opçõ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[].value`	`string`	—
`data.options[].label`	`string`	—
`data.options[].color`	`string`	Aceita null.
`data.options[].image`	`string`	URL da foto. Somente para `members`. Aceita null.
`data.options[].inactive`	`boolean`	Somente 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.config`	`object`	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. Aceita null.
`data.config.event`	`EventFieldConfig`	—
`data.config.event.title`	`string`	Até 255 caracteres.
`data.config.event.description`	`string`	Aceita null. Até 2000 caracteres.
`data.config.event.durationMinutes`	`integer`	Mínimo: 1. Máximo: 1440.
`data.config.event.conferenceMode`	`string`	Valores: none, google_meet, custom_field. Aceita null.
`data.config.event.conferenceFieldSlug`	`string`	Aceita null.
`data.config.event.recordWithBot`	`boolean`	Aceita null.
`data.config.event.attendees`	`array`	Aceita null.
`data.config.event.attendees[].type`	`string`	Valores: lead_contact, deal_co_owner, member, contact, member_field.
`data.config.event.attendees[].userId`	`string`	Aceita null.
`data.config.event.attendees[].contactId`	`string`	Aceita null.
`data.config.event.attendees[].fieldSlug`	`string`	Slug do campo members cujo usuário será convidado. Lido novamente quando o campo mudar. Aceita null.
`data.config.event.attendees[].label`	`string`	Rótulo usado pelo editor; não determina a identidade do convidado. Aceita null. Até 255 caracteres.
`data.isRequired`	`boolean`	—
`data.apiOnly`	`boolean`	Valores dos negócios são somente leitura no aplicativo e podem ser alterados por /api/v1.
`data.displayOrder`	`integer`	—
`data.section`	`string`	Aceita null.
`data.pipelineConfig`	`object`	Aceita null.
`data.createdAt`	`string`	Formato: date-time.
`data.updatedAt`	`string`	Formato: date-time.
`data.visibilityRule`	`object`	Aceita null.
`data.visibilityRule.parentFieldId`	`string`	—
`data.visibilityRule.values`	`array`	—
`message`	`string`	Aceita null.

Esquema OpenAPI

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/CustomFieldDefinition"
    },
    "message": {
      "type": "string",
      "nullable": true
    }
  }
}

401Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

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"
  ]
}

404Recurso não encontrado ou fora da visibilidade do membro.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

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.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

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 JSON Markdown desta operação

Consultar campo personalizado

Exemplos

cURL

Parâmetros

Respostas

Precisa de ajuda?