Synupv1
Criar chave
v1Recursos/Custom Fields

Custom Fields

Defina e gerencie o esquema de campos personalizados para locais e clientes na sua agência, e leia ou grave os valores armazenados para uma entidade específica. O esquema de campos em si é de toda a agência; os valores por entidade ainda são restritos aos clientes para os quais uma chave limitada está autorizada.

Retorna o esquema de campos personalizados definido para o tipo de entidade informado (location ou client), na ordem em que são exibidos na interface.

Listar definições de campos personalizados

get/api/v1/custom-fields/definitions
custom-fields:read
Parâmetros de consulta
entityTypestring (location | client)obrigatório
Qual tipo de entidade listar o esquema: "location" ou "client".
Resposta
dataarray of objectopcional
idstringopcional
Identificador único da definição de campo personalizado.
entityTypestring (location | client)opcional
O tipo de entidade ao qual esta definição se aplica: "location" ou "client".
keystringopcional
Slug imutável identificando este campo, derivado do seu label na criação. Use isto para referenciar o campo ao definir valores.
labelstringopcional
O rótulo de exibição do campo personalizado.
typestring (text | number | date | single_select | multi_select)opcional
O tipo de valor do campo.
requiredbooleanopcional
Se o campo está marcado como required. Isto não é aplicado pela API — é apenas uma dica para a interface.
optionsarray of stringopcional
As opções selecionáveis do campo, para campos single_select e multi_select. Null para outros tipos.
createdBystringopcional
Quem criou esta definição de campo: "user" ou "agent".
ordernumberopcional
A ordem de exibição do campo em relação a outras definições do mesmo tipo de entidade, a menor primeiro.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/custom-fields/definitions
Sua chave de API
entityType *
{
  "data": [
    {
      "id": "cm_def_abc123",
      "entityType": "location",
      "key": "parking_notes",
      "label": "Parking notes",
      "type": "text",
      "required": false,
      "options": null,
      "createdBy": "user",
      "order": 0
    }
  ]
}
v1Recursos/Custom Fields/postCriar uma definição de campo personalizado

Adiciona um novo campo personalizado ao esquema para o tipo de entidade informado. A key do campo é derivada do seu label e é imutável depois disso; campos do tipo select exigem pelo menos uma opção.

Criar uma definição de campo personalizado

post/api/v1/custom-fields/definitions
custom-fields:write
Corpo da solicitação
entityTypestring (location | client)obrigatório
O tipo de entidade ao qual este campo se aplica: "location" ou "client".
labelstringobrigatório
O rótulo de exibição do campo personalizado.
typestring (text | number | date | single_select | multi_select)obrigatório
O tipo de valor do campo: text, number, date, single_select ou multi_select.
requiredbooleanopcional
Se o campo deve ser marcado como required. Opcional; o padrão é false.
optionsarray of stringopcional
As opções selecionáveis do campo. Obrigatório (pelo menos uma) para campos single_select e multi_select; ignorado para outros tipos.
Resposta
dataobjectopcional
definitionobjectopcional
idstringopcional
Identificador único da definição de campo personalizado.
entityTypestring (location | client)opcional
O tipo de entidade ao qual esta definição se aplica: "location" ou "client".
keystringopcional
Slug imutável identificando este campo, derivado do seu label na criação. Use isto para referenciar o campo ao definir valores.
labelstringopcional
O rótulo de exibição do campo personalizado.
typestring (text | number | date | single_select | multi_select)opcional
O tipo de valor do campo.
requiredbooleanopcional
Se o campo está marcado como required. Isto não é aplicado pela API — é apenas uma dica para a interface.
optionsarray of stringopcional
As opções selecionáveis do campo, para campos single_select e multi_select. Null para outros tipos.
createdBystringopcional
Quem criou esta definição de campo: "user" ou "agent".
ordernumberopcional
A ordem de exibição do campo em relação a outras definições do mesmo tipo de entidade, a menor primeiro.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
422Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/custom-fields/definitions
Sua chave de API
Corpo da solicitação*
{
  "data": {
    "definition": {
      "id": "cm_def_abc123",
      "entityType": "location",
      "key": "parking_notes",
      "label": "Parking notes",
      "type": "text",
      "required": false,
      "options": null,
      "createdBy": "user",
      "order": 0
    }
  }
}
v1Recursos/Custom Fields/patchAtualizar uma definição de campo personalizado

Edita o label, a flag required, as opções ou a ordem de exibição de uma definição de campo personalizado. O type e a key do campo não podem ser alterados após a criação.

Atualizar uma definição de campo personalizado

patch/api/v1/custom-fields/definitions
custom-fields:write
Corpo da solicitação
definitionIdstringobrigatório
ID da definição de campo personalizado a ser atualizada.
labelstringopcional
O rótulo de exibição do campo personalizado.
requiredbooleanopcional
Se o campo deve ser marcado como required. Opcional; o padrão é false.
optionsarray of stringopcional
As opções selecionáveis do campo. Obrigatório (pelo menos uma) para campos single_select e multi_select; ignorado para outros tipos.
ordernumberopcional
Nova ordem de exibição para esta definição em relação a outras do mesmo tipo de entidade.
Resposta
dataobjectopcional
definitionobjectopcional
idstringopcional
Identificador único da definição de campo personalizado.
entityTypestring (location | client)opcional
O tipo de entidade ao qual esta definição se aplica: "location" ou "client".
keystringopcional
Slug imutável identificando este campo, derivado do seu label na criação. Use isto para referenciar o campo ao definir valores.
labelstringopcional
O rótulo de exibição do campo personalizado.
typestring (text | number | date | single_select | multi_select)opcional
O tipo de valor do campo.
requiredbooleanopcional
Se o campo está marcado como required. Isto não é aplicado pela API — é apenas uma dica para a interface.
optionsarray of stringopcional
As opções selecionáveis do campo, para campos single_select e multi_select. Null para outros tipos.
createdBystringopcional
Quem criou esta definição de campo: "user" ou "agent".
ordernumberopcional
A ordem de exibição do campo em relação a outras definições do mesmo tipo de entidade, a menor primeiro.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
422Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
patch/api/v1/custom-fields/definitions
Sua chave de API
Corpo da solicitação*
{
  "data": {
    "definition": {
      "id": "cm_def_abc123",
      "entityType": "location",
      "key": "parking_notes",
      "label": "Parking notes",
      "type": "text",
      "required": true,
      "options": null,
      "createdBy": "user",
      "order": 0
    }
  }
}
v1Recursos/Custom Fields/deleteArquivar uma definição de campo personalizado

Arquiva uma definição de campo personalizado para que ela não apareça mais no esquema nem aceite novos valores. Valores já armazenados sob sua key permanecem intactos. Um definitionId desconhecido ou já arquivado é um no-op, não um erro.

Arquivar uma definição de campo personalizado

delete/api/v1/custom-fields/definitions
custom-fields:write
Parâmetros de consulta
definitionIdstringobrigatório
ID da definição de campo personalizado a ser arquivada.
Resposta
dataobjectopcional
archivedbooleanopcional
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
delete/api/v1/custom-fields/definitions
Sua chave de API
definitionId *
{
  "data": {
    "archived": true
  }
}
v1Recursos/Custom Fields/getObter os valores de campos personalizados de uma entidade

Retorna os valores de campos personalizados armazenados em um local ou cliente, indexados pela key do campo.

Obter os valores de campos personalizados de uma entidade

get/api/v1/custom-fields/values
custom-fields:read
Parâmetros de consulta
entityTypestring (location | client)obrigatório
O tipo da entidade: "location" ou "client".
entityIdstringobrigatório
ID do local ou cliente para o qual ler os valores.
Resposta
dataobjectopcional
valuesobjectopcional
Os valores de campos personalizados da entidade, indexados pela key do campo. Um valor é uma string, um número, um array de strings (para multi_select), ou ausente quando não definido.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/custom-fields/values
Sua chave de API
entityType *
entityId *
{
  "data": {
    "values": {
      "parking_notes": "Free lot behind the building."
    }
  }
}
v1Recursos/Custom Fields/putDefinir um valor de campo personalizado

Define um valor de campo personalizado em um local ou cliente. Passe null (ou um valor vazio) para limpar o campo. O valor é validado contra a definição do campo — por exemplo, o valor de um campo select deve ser uma de suas opções definidas.

Definir um valor de campo personalizado

put/api/v1/custom-fields/values
custom-fields:write
Corpo da solicitação
entityTypestring (location | client)obrigatório
O tipo de entidade ao qual este campo se aplica: "location" ou "client".
entityIdstringobrigatório
ID do local ou cliente no qual definir o valor.
keystringobrigatório
Key da definição de campo personalizado a ser definida, conforme retornada em sua propriedade key.
valueobjectobrigatório
O valor a ser armazenado. Deve estar presente no corpo da solicitação, mas pode ser null ou vazio para limpar o campo. Validado contra o type e as options do campo.
Resposta
dataobjectopcional
valuesobjectopcional
Os valores de campos personalizados da entidade, indexados pela key do campo. Um valor é uma string, um número, um array de strings (para multi_select), ou ausente quando não definido.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
422Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
put/api/v1/custom-fields/values
Sua chave de API
Corpo da solicitação*
{
  "data": {
    "values": {
      "parking_notes": "Free lot behind the building."
    }
  }
}