Synupv1
Crear clave
v1Recursos/Custom Fields

Custom Fields

Defina y gestione el esquema de campos personalizados para ubicaciones y clientes de su agencia, y lea o escriba los valores almacenados para una entidad específica. El esquema de campos en sí es de toda la agencia; los valores por entidad siguen restringidos a los clientes para los que está autorizada una clave limitada.

Devuelve el esquema de campos personalizados definido para el tipo de entidad indicado (location o client), en el mismo orden en que se muestran en la interfaz.

Listar definiciones de campos personalizados

get/api/v1/custom-fields/definitions
custom-fields:read
Parámetros de consulta
entityTypestring (location | client)obligatorio
El esquema de qué tipo de entidad listar: "location" o "client".
Respuesta
dataarray of objectopcional
idstringopcional
Identificador único de la definición de campo personalizado.
entityTypestring (location | client)opcional
El tipo de entidad al que se aplica esta definición: "location" o "client".
keystringopcional
Slug inmutable que identifica este campo, derivado de su etiqueta al crearlo. Úselo para referenciar el campo al establecer valores.
labelstringopcional
La etiqueta visible del campo personalizado.
typestring (text | number | date | single_select | multi_select)opcional
El tipo de valor del campo.
requiredbooleanopcional
Si el campo está marcado como obligatorio. Esto no se aplica en la API — es solo una indicación para la interfaz.
optionsarray of stringopcional
Las opciones seleccionables del campo, para campos single_select y multi_select. Null para otros tipos.
createdBystringopcional
Quién creó esta definición de campo: "user" o "agent".
ordernumberopcional
El orden de visualización del campo respecto a otras definiciones del mismo tipo de entidad, del más bajo al más alto.
Errores
400A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
401La clave de API falta, es inválida, expiró o fue revocada.
403A la clave le falta el permiso requerido, o no está autorizada para este cliente/ubicación.
429Demasiadas solicitudes. Reintente tras el número de segundos indicado en el encabezado Retry-After.
get/api/v1/custom-fields/definitions
Su clave 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/postCrear una definición de campo personalizado

Agrega un nuevo campo personalizado al esquema del tipo de entidad indicado. La clave del campo se deriva de su etiqueta y es inmutable después de creada; los campos de tipo selección requieren al menos una opción.

Crear una definición de campo personalizado

post/api/v1/custom-fields/definitions
custom-fields:write
Cuerpo de la solicitud
entityTypestring (location | client)obligatorio
El tipo de entidad al que se aplica este campo: "location" o "client".
labelstringobligatorio
La etiqueta visible del campo personalizado.
typestring (text | number | date | single_select | multi_select)obligatorio
El tipo de valor del campo: text, number, date, single_select o multi_select.
requiredbooleanopcional
Si el campo debe marcarse como obligatorio. Opcional; el valor predeterminado es false.
optionsarray of stringopcional
Las opciones seleccionables del campo. Obligatorio (al menos una) para campos single_select y multi_select; se ignora para otros tipos.
Respuesta
dataobjectopcional
definitionobjectopcional
idstringopcional
Identificador único de la definición de campo personalizado.
entityTypestring (location | client)opcional
El tipo de entidad al que se aplica esta definición: "location" o "client".
keystringopcional
Slug inmutable que identifica este campo, derivado de su etiqueta al crearlo. Úselo para referenciar el campo al establecer valores.
labelstringopcional
La etiqueta visible del campo personalizado.
typestring (text | number | date | single_select | multi_select)opcional
El tipo de valor del campo.
requiredbooleanopcional
Si el campo está marcado como obligatorio. Esto no se aplica en la API — es solo una indicación para la interfaz.
optionsarray of stringopcional
Las opciones seleccionables del campo, para campos single_select y multi_select. Null para otros tipos.
createdBystringopcional
Quién creó esta definición de campo: "user" o "agent".
ordernumberopcional
El orden de visualización del campo respecto a otras definiciones del mismo tipo de entidad, del más bajo al más alto.
Errores
400A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
401La clave de API falta, es inválida, expiró o fue revocada.
403A la clave le falta el permiso requerido, o no está autorizada para este cliente/ubicación.
422A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
429Demasiadas solicitudes. Reintente tras el número de segundos indicado en el encabezado Retry-After.
post/api/v1/custom-fields/definitions
Su clave de API
Cuerpo de la solicitud*
{
  "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/patchActualizar una definición de campo personalizado

Edita la etiqueta, el indicador de obligatorio, las opciones o el orden de visualización de una definición de campo personalizado. El tipo y la clave del campo no se pueden cambiar después de crearlo.

Actualizar una definición de campo personalizado

patch/api/v1/custom-fields/definitions
custom-fields:write
Cuerpo de la solicitud
definitionIdstringobligatorio
ID de la definición de campo personalizado a actualizar.
labelstringopcional
La etiqueta visible del campo personalizado.
requiredbooleanopcional
Si el campo debe marcarse como obligatorio. Opcional; el valor predeterminado es false.
optionsarray of stringopcional
Las opciones seleccionables del campo. Obligatorio (al menos una) para campos single_select y multi_select; se ignora para otros tipos.
ordernumberopcional
Nuevo orden de visualización de esta definición respecto a otras del mismo tipo de entidad.
Respuesta
dataobjectopcional
definitionobjectopcional
idstringopcional
Identificador único de la definición de campo personalizado.
entityTypestring (location | client)opcional
El tipo de entidad al que se aplica esta definición: "location" o "client".
keystringopcional
Slug inmutable que identifica este campo, derivado de su etiqueta al crearlo. Úselo para referenciar el campo al establecer valores.
labelstringopcional
La etiqueta visible del campo personalizado.
typestring (text | number | date | single_select | multi_select)opcional
El tipo de valor del campo.
requiredbooleanopcional
Si el campo está marcado como obligatorio. Esto no se aplica en la API — es solo una indicación para la interfaz.
optionsarray of stringopcional
Las opciones seleccionables del campo, para campos single_select y multi_select. Null para otros tipos.
createdBystringopcional
Quién creó esta definición de campo: "user" o "agent".
ordernumberopcional
El orden de visualización del campo respecto a otras definiciones del mismo tipo de entidad, del más bajo al más alto.
Errores
400A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
401La clave de API falta, es inválida, expiró o fue revocada.
403A la clave le falta el permiso requerido, o no está autorizada para este cliente/ubicación.
404El recurso no se encontró, o no pertenece a su agencia.
422A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
429Demasiadas solicitudes. Reintente tras el número de segundos indicado en el encabezado Retry-After.
patch/api/v1/custom-fields/definitions
Su clave de API
Cuerpo de la solicitud*
{
  "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/deleteArchivar una definición de campo personalizado

Archiva una definición de campo personalizado para que deje de aparecer en el esquema y de aceptar nuevos valores. Los valores ya almacenados bajo su clave quedan intactos. Un definitionId desconocido o ya archivado no hace nada — no es un error.

Archivar una definición de campo personalizado

delete/api/v1/custom-fields/definitions
custom-fields:write
Parámetros de consulta
definitionIdstringobligatorio
ID de la definición de campo personalizado a archivar.
Respuesta
dataobjectopcional
archivedbooleanopcional
Errores
400A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
401La clave de API falta, es inválida, expiró o fue revocada.
403A la clave le falta el permiso requerido, o no está autorizada para este cliente/ubicación.
429Demasiadas solicitudes. Reintente tras el número de segundos indicado en el encabezado Retry-After.
delete/api/v1/custom-fields/definitions
Su clave de API
definitionId *
{
  "data": {
    "archived": true
  }
}
v1Recursos/Custom Fields/getObtener los valores de campos personalizados de una entidad

Devuelve los valores de campos personalizados almacenados en una ubicación o cliente, organizados por la clave del campo.

Obtener los valores de campos personalizados de una entidad

get/api/v1/custom-fields/values
custom-fields:read
Parámetros de consulta
entityTypestring (location | client)obligatorio
El tipo de la entidad: "location" o "client".
entityIdstringobligatorio
ID de la ubicación o cliente del que leer los valores.
Respuesta
dataobjectopcional
valuesobjectopcional
Los valores de campos personalizados de la entidad, organizados por la clave del campo. Un valor es una cadena, un número, un array de cadenas (para multi_select), o está ausente cuando no se ha establecido.
Errores
400A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
401La clave de API falta, es inválida, expiró o fue revocada.
403A la clave le falta el permiso requerido, o no está autorizada para este cliente/ubicación.
404El recurso no se encontró, o no pertenece a su agencia.
429Demasiadas solicitudes. Reintente tras el número de segundos indicado en el encabezado Retry-After.
get/api/v1/custom-fields/values
Su clave de API
entityType *
entityId *
{
  "data": {
    "values": {
      "parking_notes": "Free lot behind the building."
    }
  }
}
v1Recursos/Custom Fields/putEstablecer un valor de campo personalizado

Establece un valor de campo personalizado en una ubicación o cliente. Indique null (o un valor vacío) para vaciar el campo. El valor se valida frente a la definición del campo — por ejemplo, el valor de un campo de selección debe ser una de sus opciones definidas.

Establecer un valor de campo personalizado

put/api/v1/custom-fields/values
custom-fields:write
Cuerpo de la solicitud
entityTypestring (location | client)obligatorio
El tipo de entidad al que se aplica este campo: "location" o "client".
entityIdstringobligatorio
ID de la ubicación o cliente en el que establecer el valor.
keystringobligatorio
Clave de la definición de campo personalizado a establecer, tal como se devuelve en su propiedad key.
valueobjectobligatorio
El valor a almacenar. Debe estar presente en el cuerpo de la solicitud, pero puede ser null o vacío para vaciar el campo. Se valida frente al tipo y las opciones del campo.
Respuesta
dataobjectopcional
valuesobjectopcional
Los valores de campos personalizados de la entidad, organizados por la clave del campo. Un valor es una cadena, un número, un array de cadenas (para multi_select), o está ausente cuando no se ha establecido.
Errores
400A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
401La clave de API falta, es inválida, expiró o fue revocada.
403A la clave le falta el permiso requerido, o no está autorizada para este cliente/ubicación.
404El recurso no se encontró, o no pertenece a su agencia.
422A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
429Demasiadas solicitudes. Reintente tras el número de segundos indicado en el encabezado Retry-After.
put/api/v1/custom-fields/values
Su clave de API
Cuerpo de la solicitud*
{
  "data": {
    "values": {
      "parking_notes": "Free lot behind the building."
    }
  }
}