Synupv1
Créer une clé
v1Ressources/Champs personnalisés

Champs personnalisés

Définissez et gérez le schéma de champs personnalisés pour les établissements et les clients de votre agence, et lisez ou écrivez les valeurs stockées pour une entité donnée. Le schéma de champs lui-même est valable pour toute l'agence ; les valeurs par entité restent restreintes aux clients pour lesquels une clé limitée est autorisée.

Renvoie le schéma de champs personnalisés défini pour le type d'entité donné (établissement ou client), dans l'ordre d'affichage dans l'interface.

Lister les définitions de champs personnalisés

get/api/v1/custom-fields/definitions
custom-fields:read
Paramètres de requête
entityTypestring (location | client)obligatoire
Le schéma de quel type d'entité lister : "location" ou "client".
Réponse
dataarray of objectfacultatif
idstringfacultatif
Identifiant unique de la définition de champ personnalisé.
entityTypestring (location | client)facultatif
Le type d'entité auquel cette définition s'applique : "location" ou "client".
keystringfacultatif
Slug immuable identifiant ce champ, dérivé de son étiquette à la création. Utilisez-le pour référencer le champ lors de la définition de valeurs.
labelstringfacultatif
L'étiquette d'affichage du champ personnalisé.
typestring (text | number | date | single_select | multi_select)facultatif
Le type de valeur du champ.
requiredbooleanfacultatif
Si le champ est marqué comme requis. Ce n'est pas imposé par l'API — c'est uniquement une indication pour l'interface.
optionsarray of stringfacultatif
Les options sélectionnables du champ, pour les champs single_select et multi_select. Null pour les autres types.
createdBystringfacultatif
Qui a créé cette définition de champ : "user" ou "agent".
ordernumberfacultatif
L'ordre d'affichage du champ par rapport aux autres définitions du même type d'entité, du plus bas au plus élevé.
Erreurs
400Il manque un paramètre requis à la requête, ou elle est invalide.
401Clé API manquante, invalide, expirée ou révoquée.
403La clé n'a pas la permission requise, ou n'est pas autorisée pour ce client/établissement.
429Trop de requêtes. Réessayez après le nombre de secondes indiqué dans l'en-tête Retry-After.
get/api/v1/custom-fields/definitions
Votre clé 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
    }
  ]
}
v1Ressources/Champs personnalisés/postCréer une définition de champ personnalisé

Ajoute un nouveau champ personnalisé au schéma pour le type d'entité donné. La clé du champ est dérivée de son étiquette et devient immuable par la suite ; les champs de type select nécessitent au moins une option.

Créer une définition de champ personnalisé

post/api/v1/custom-fields/definitions
custom-fields:write
Corps de la requête
entityTypestring (location | client)obligatoire
Le type d'entité auquel ce champ s'applique : "location" ou "client".
labelstringobligatoire
L'étiquette d'affichage du champ personnalisé.
typestring (text | number | date | single_select | multi_select)obligatoire
Le type de valeur du champ : text, number, date, single_select ou multi_select.
requiredbooleanfacultatif
Si le champ doit être marqué comme requis. Facultatif ; par défaut false.
optionsarray of stringfacultatif
Les options sélectionnables du champ. Requises (au moins une) pour les champs single_select et multi_select ; ignorées pour les autres types.
Réponse
dataobjectfacultatif
definitionobjectfacultatif
idstringfacultatif
Identifiant unique de la définition de champ personnalisé.
entityTypestring (location | client)facultatif
Le type d'entité auquel cette définition s'applique : "location" ou "client".
keystringfacultatif
Slug immuable identifiant ce champ, dérivé de son étiquette à la création. Utilisez-le pour référencer le champ lors de la définition de valeurs.
labelstringfacultatif
L'étiquette d'affichage du champ personnalisé.
typestring (text | number | date | single_select | multi_select)facultatif
Le type de valeur du champ.
requiredbooleanfacultatif
Si le champ est marqué comme requis. Ce n'est pas imposé par l'API — c'est uniquement une indication pour l'interface.
optionsarray of stringfacultatif
Les options sélectionnables du champ, pour les champs single_select et multi_select. Null pour les autres types.
createdBystringfacultatif
Qui a créé cette définition de champ : "user" ou "agent".
ordernumberfacultatif
L'ordre d'affichage du champ par rapport aux autres définitions du même type d'entité, du plus bas au plus élevé.
Erreurs
400Il manque un paramètre requis à la requête, ou elle est invalide.
401Clé API manquante, invalide, expirée ou révoquée.
403La clé n'a pas la permission requise, ou n'est pas autorisée pour ce client/établissement.
422Il manque un paramètre requis à la requête, ou elle est invalide.
429Trop de requêtes. Réessayez après le nombre de secondes indiqué dans l'en-tête Retry-After.
post/api/v1/custom-fields/definitions
Votre clé API
Corps de la requête*
{
  "data": {
    "definition": {
      "id": "cm_def_abc123",
      "entityType": "location",
      "key": "parking_notes",
      "label": "Parking notes",
      "type": "text",
      "required": false,
      "options": null,
      "createdBy": "user",
      "order": 0
    }
  }
}
v1Ressources/Champs personnalisés/patchMettre à jour une définition de champ personnalisé

Modifie l'étiquette, l'indicateur requis, les options ou l'ordre d'affichage d'une définition de champ personnalisé. Le type et la clé du champ ne peuvent pas être modifiés après création.

Mettre à jour une définition de champ personnalisé

patch/api/v1/custom-fields/definitions
custom-fields:write
Corps de la requête
definitionIdstringobligatoire
ID de la définition de champ personnalisé à mettre à jour.
labelstringfacultatif
L'étiquette d'affichage du champ personnalisé.
requiredbooleanfacultatif
Si le champ doit être marqué comme requis. Facultatif ; par défaut false.
optionsarray of stringfacultatif
Les options sélectionnables du champ. Requises (au moins une) pour les champs single_select et multi_select ; ignorées pour les autres types.
ordernumberfacultatif
Nouvel ordre d'affichage pour cette définition par rapport aux autres du même type d'entité.
Réponse
dataobjectfacultatif
definitionobjectfacultatif
idstringfacultatif
Identifiant unique de la définition de champ personnalisé.
entityTypestring (location | client)facultatif
Le type d'entité auquel cette définition s'applique : "location" ou "client".
keystringfacultatif
Slug immuable identifiant ce champ, dérivé de son étiquette à la création. Utilisez-le pour référencer le champ lors de la définition de valeurs.
labelstringfacultatif
L'étiquette d'affichage du champ personnalisé.
typestring (text | number | date | single_select | multi_select)facultatif
Le type de valeur du champ.
requiredbooleanfacultatif
Si le champ est marqué comme requis. Ce n'est pas imposé par l'API — c'est uniquement une indication pour l'interface.
optionsarray of stringfacultatif
Les options sélectionnables du champ, pour les champs single_select et multi_select. Null pour les autres types.
createdBystringfacultatif
Qui a créé cette définition de champ : "user" ou "agent".
ordernumberfacultatif
L'ordre d'affichage du champ par rapport aux autres définitions du même type d'entité, du plus bas au plus élevé.
Erreurs
400Il manque un paramètre requis à la requête, ou elle est invalide.
401Clé API manquante, invalide, expirée ou révoquée.
403La clé n'a pas la permission requise, ou n'est pas autorisée pour ce client/établissement.
404La ressource est introuvable, ou n'appartient pas à votre agence.
422Il manque un paramètre requis à la requête, ou elle est invalide.
429Trop de requêtes. Réessayez après le nombre de secondes indiqué dans l'en-tête Retry-After.
patch/api/v1/custom-fields/definitions
Votre clé API
Corps de la requête*
{
  "data": {
    "definition": {
      "id": "cm_def_abc123",
      "entityType": "location",
      "key": "parking_notes",
      "label": "Parking notes",
      "type": "text",
      "required": true,
      "options": null,
      "createdBy": "user",
      "order": 0
    }
  }
}
v1Ressources/Champs personnalisés/deleteArchiver une définition de champ personnalisé

Archive une définition de champ personnalisé afin qu'elle n'apparaisse plus dans le schéma et n'accepte plus de nouvelles valeurs. Les valeurs déjà stockées sous sa clé ne sont pas affectées. Un definitionId inconnu ou déjà archivé n'a aucun effet, ce n'est pas une erreur.

Archiver une définition de champ personnalisé

delete/api/v1/custom-fields/definitions
custom-fields:write
Paramètres de requête
definitionIdstringobligatoire
ID de la définition de champ personnalisé à archiver.
Réponse
dataobjectfacultatif
archivedbooleanfacultatif
Erreurs
400Il manque un paramètre requis à la requête, ou elle est invalide.
401Clé API manquante, invalide, expirée ou révoquée.
403La clé n'a pas la permission requise, ou n'est pas autorisée pour ce client/établissement.
429Trop de requêtes. Réessayez après le nombre de secondes indiqué dans l'en-tête Retry-After.
delete/api/v1/custom-fields/definitions
Votre clé API
definitionId *
{
  "data": {
    "archived": true
  }
}
v1Ressources/Champs personnalisés/getObtenir les valeurs de champs personnalisés d'une entité

Renvoie les valeurs de champs personnalisés stockées sur un établissement ou un client, indexées par clé de champ.

Obtenir les valeurs de champs personnalisés d'une entité

get/api/v1/custom-fields/values
custom-fields:read
Paramètres de requête
entityTypestring (location | client)obligatoire
Le type de l'entité : "location" ou "client".
entityIdstringobligatoire
ID de l'établissement ou du client dont lire les valeurs.
Réponse
dataobjectfacultatif
valuesobjectfacultatif
Les valeurs de champs personnalisés de l'entité, indexées par clé de champ. Une valeur est une chaîne, un nombre, un tableau de chaînes (pour multi_select), ou absente si non définie.
Erreurs
400Il manque un paramètre requis à la requête, ou elle est invalide.
401Clé API manquante, invalide, expirée ou révoquée.
403La clé n'a pas la permission requise, ou n'est pas autorisée pour ce client/établissement.
404La ressource est introuvable, ou n'appartient pas à votre agence.
429Trop de requêtes. Réessayez après le nombre de secondes indiqué dans l'en-tête Retry-After.
get/api/v1/custom-fields/values
Votre clé API
entityType *
entityId *
{
  "data": {
    "values": {
      "parking_notes": "Free lot behind the building."
    }
  }
}
v1Ressources/Champs personnalisés/putDéfinir une valeur de champ personnalisé

Définit une valeur de champ personnalisé sur un établissement ou un client. Passez null (ou une valeur vide) pour vider le champ. La valeur est validée par rapport à la définition du champ — par exemple, la valeur d'un champ select doit être une de ses options définies.

Définir une valeur de champ personnalisé

put/api/v1/custom-fields/values
custom-fields:write
Corps de la requête
entityTypestring (location | client)obligatoire
Le type d'entité auquel ce champ s'applique : "location" ou "client".
entityIdstringobligatoire
ID de l'établissement ou du client sur lequel définir la valeur.
keystringobligatoire
Clé de la définition de champ personnalisé à définir, telle que renvoyée dans sa propriété key.
valueobjectobligatoire
La valeur à stocker. Doit être présente dans le corps de la requête, mais peut être null ou vide pour vider le champ. Validée par rapport au type et aux options du champ.
Réponse
dataobjectfacultatif
valuesobjectfacultatif
Les valeurs de champs personnalisés de l'entité, indexées par clé de champ. Une valeur est une chaîne, un nombre, un tableau de chaînes (pour multi_select), ou absente si non définie.
Erreurs
400Il manque un paramètre requis à la requête, ou elle est invalide.
401Clé API manquante, invalide, expirée ou révoquée.
403La clé n'a pas la permission requise, ou n'est pas autorisée pour ce client/établissement.
404La ressource est introuvable, ou n'appartient pas à votre agence.
422Il manque un paramètre requis à la requête, ou elle est invalide.
429Trop de requêtes. Réessayez après le nombre de secondes indiqué dans l'en-tête Retry-After.
put/api/v1/custom-fields/values
Votre clé API
Corps de la requête*
{
  "data": {
    "values": {
      "parking_notes": "Free lot behind the building."
    }
  }
}