Champs personnalisés¶

Ces routes gèrent les champs personnalisés des courriers. Elles ne concernent pas les champs personnalisés des contacts. Toutes sont authentifiées, les mutations exigent admin_custom_fields et portent sur l’instance complète.

Authentification, privilège et périmètre¶

Toutes les actions exigent une authentification et portent sur le référentiel global de l’instance. La lecture n’ajoute aucun contrôle de privilège, sauf pour activer la représentation d’administration demandée par admin=true. Les créations, modifications et suppressions exigent admin_custom_fields.

Structure d’un champ¶

Valeur	Type	Description
`id`	integer	Identifiant technique
`label`	string	Libellé unique
`type`	string	`string`, `integer`, `select`, `date`, `radio`, `checkbox`, `banAutocomplete` ou `contact`
`mode`	string	`form` ou `technical`
`values`	array ou object	Valeurs statiques ou définition SQL autorisée
`SQLMode`	boolean	Indique que les valeurs proviennent d’une table autorisée

Lister les champs personnalisés¶

Route¶

GET /rest/customFields

Paramètres de query string¶

Valeur	Type	Obligatoire	Description
`admin`	valeur non vide	Non	Avec `admin_custom_fields`, conserve la définition d’administration des valeurs
`resId`	integer	Non	Identifiant de courrier injecté dans les valeurs SQL dynamiques

Sans le mode administrateur, les valeurs sont normalisées sous la forme {key, label}. Les clés des listes sont converties en chaînes, une valeur de type integer est convertie en entier.

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Champs triés par libellé	`{"customFields":[{"id":12,"label":"Nature","type":"select","mode":"form","values":[{"key":"Courrier","label":"Courrier"}],"SQLMode":false}]}`

Créer un champ personnalisé¶

Route¶

POST /rest/customFields

Body¶

Valeur	Type	Obligatoire	Description
`label`	string	Oui	Libellé unique
`type`	string	Oui	Une des valeurs indiquées dans la structure
`mode`	string	Oui	`form` ou `technical`
`values`	array	Non	Valeurs statiques
`SQLMode`	boolean	Non	Active une source SQL autorisée

En mode SQL, values contient key (colonne), label (tableau de colonnes et délimiteurs), table (table autorisée) et clause (clause sans SELECT). Les colonnes contenant password ou token sont interdites.

{
  "label": "Nature du courrier",
  "type": "select",
  "mode": "form",
  "values": ["Information", "Réclamation"]
}

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Champ créé	`{"customFieldId":12}`
`400`	object	Libellé invalide	`{"errors":"Body label is empty or not a string"}`
`400`	object	Type ou mode invalide	Message exact de la propriété concernée
`400`	object	Libellé déjà utilisé	`{"errors":"Custom field with this label already exists"}`
`400`	object	Définition SQL refusée	Message exact du contrôle SQL
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Modifier un champ personnalisé¶

Route¶

PUT /rest/customFields/{id}

Paramètres d’URL¶

Valeur	Type	Obligatoire	Description
`id`	integer	Oui	Identifiant technique

Body¶

label, mode et values sont attendus. Le type existant est conservé par l'api. En mode statique, chaque valeur utilise la structure {key, label}.

{
  "label": "Nature du courrier",
  "mode": "form",
  "values": [
    {"key": 0, "label": "Information"},
    {"key": 1, "label": "Réclamation"}
  ],
  "SQLMode": false
}

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Champ modifié	`{"customField":{"id":12,"label":"Nature du courrier","type":"select","mode":"form","values":[{"key":0,"label":"Information"}],"SQLMode":false}}`
`400`	object	Identifiant invalide	`{"errors":"Param id is empty or not an integer"}`
`400`	object	Champ absent	`{"errors":"Custom field not found"}`
`400`	object	Valeurs dupliquées ou valeurs existantes omises	Message exact du contrôle
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Supprimer un champ personnalisé¶

Route¶

DELETE /rest/customFields/{id}

La suppression retire aussi le champ des courriers, modèles d’indexation, actions, bannettes, configurations de recherche et modèles de recherche concernés.

Paramètres d’URL¶

Valeur	Type	Obligatoire	Description
`id`	integer	Oui	Identifiant technique

Retour¶

Code HTTP	Type	Description	Exemple
`204`	vide	Champ supprimé	Aucune réponse
`400`	object	Identifiant invalide	`{"errors":"Param id is empty or not an integer"}`
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Lister les tables et colonnes autorisées¶

Route¶

GET /rest/customFieldsWhiteList

Authentification, privilège et périmètre¶

L'authentification et le privilège admin_custom_fields sont obligatoires. La liste est globale à l'instance.

Les tables proviennent de config/customFieldsWhiteList.json. Pour chacune, l'api interroge les colonnes réellement présentes et exclut celles dont le nom contient password ou token, sans tenir compte de la casse.

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Tables et colonnes utilisables par le mode SQL	`{"allowedTables":[{"name":"<table-autorisée>","columns":["<colonne-autorisée>"]}]}`
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Données¶

Valeur	Type	Description
`allowedTables`	array	Tables déclarées dans la liste blanche
`allowedTables[].name`	string	Nom technique de la table
`allowedTables[].columns`	array	Noms techniques des colonnes autorisées