# Attributs

Gérez et récupérez les attributs.

**Types de champs**

| **type** | **description** |
| --- | --- |
| `1` | Sélection unique |
| `2` | Sélection multiple |
| `3` | Valeur libre (unique) |
| `4` | Valeurs libres (multiples) |
| `5` | Pièces jointes |
| `6` | Zone de texte |
| `7` | Date/heure |
| `8` | Nombre |
| `9` | Booléen |
| `10` | Couleur |
| `11` | JSON |
| `12` | Emplacement |
| `13` | Fichier audio |
| `14` | Fichier vidéo |

### Format des valeurs selon le type de champ

| **type de champ** | **format de valeur** |
| --- | --- |
| Sélection unique (`1`) | Un identifiant ou une valeur d’attribut. |
| Sélection multiple (`2`) | Tableau d’identifiants ou de valeurs d’attribut. |
| Valeur libre (`3`) | Une chaîne ou valeur scalaire libre. |
| Valeurs libres multiples (`4`) | Tableau de valeurs libres. |
| Pièces jointes (`5`) | Tableau d’URL ou de références de fichiers téléversés. |
| Zone de texte (`6`) | Chaîne libre, généralement multiligne. |
| Date/heure (`7`) | Chaîne de date/heure ISO-8601. |
| Nombre (`8`) | Valeur numérique. |
| Booléen (`9`) | `true` ou `false`. |
| Couleur (`10`) | Chaîne de couleur, par exemple une valeur hexadécimale (`#FF0000`). |
| JSON (`11`) | Objet ou tableau JSON valide. |
| Emplacement (`12`) | Objet emplacement, généralement avec latitude et longitude. |
| Fichier audio (`13`) | URL ou référence d’un fichier audio téléversé. |
| Fichier vidéo (`14`) | URL ou référence d’un fichier vidéo téléversé. |

## Objet attribut renvoyé

Un attribut décrit un champ personnalisé d’un type d’objet (par exemple une annonce ou un compte). `field_type` définit le format de saisie/valeur ; `type` définit le périmètre de l’objet et ne doit pas être confondu avec `field_type`.

**Exemple d’objet**

```
{
    "id": 71,
    "type": "listings",
    "field_type": 4,
    "icon_path": null,
    "optional": true,
    "private": false,
    "show_in_filter": true,
    "visible": true,
    "active": true,
    "order_by": 1,
    "attribute_group_id": 12,
    "metadata": {},
    "name": "Fabric",
    "tooltip": "Select all applicable fabrics",
    "categories": [
        {
            "id": 252,
            "parent": 9,
            "type": "listings",
            "active": true,
            "image_path": "https://cdn2.iconfinder.com/data/icons/shirts-glyph/48/Clothing_Shirts_Artboard_2-512.png",
            "order_by": 1,
            "sub_category": [],
            "name": "V-Neck",
            "hierarchy": [
                {
                    "id": 252,
                    "name": "V-Neck",
                    "level": 3
                }
            ]
        }
    ]
}

```

**Champs de l’objet attribut**

| **nom** | **type** | **description** |
| --- | --- | --- |
| `id` | `integer` | Identifiant unique de l’attribut |
| `name` | `string` | Nom de l’attribut |
| `field_type` | `integer` | Type de champ de l’attribut ; voir la légende des types de champ ci-dessus |
| `icon_path` | `string \| null` | Icône ou image facultative associée à l’attribut |
| `optional` | `boolean` | Indique si cet attribut est facultatif |
| `private` | `boolean` | Indique si l’attribut est privé ; les attributs privés ne sont visibles que par les administrateurs |
| `show_in_filter` | `boolean` | Indique si l’attribut apparaît dans la liste des filtres |
| `visible` | `boolean` | Détermine si l’attribut est visible par les clients |
| `active` | `boolean` | Indique si l’attribut est actif |
| `order_by` | `integer` | Ordre d’affichage parmi les attributs |
| `type` | `string` | Type de l’objet renvoyé |
| `attribute_group_id` | `integer \| null` | Groupe facultatif utilisé pour organiser les attributs associés |
| `metadata` | `object \| array \| null` | Configuration supplémentaire définie par le tenant ; conservez sa structure JSON |
| `tooltip` | `string \| null` | Texte d’aide facultatif affiché pour le champ |
| `categories` | `array` | Catégories associées à l’attribut ; voir l’objet catégorie |
| `values` | `array` | Options actives des types de champ 1 et 2 ; chaque option contient `id`, `name`, `active`, `order_by` et `metadata` |

`values` est renvoyé uniquement pour les attributs de sélection. Lors de l’envoi d’une valeur, utilisez l’`id` d’une option existante ; n’inventez pas d’identifiants.

## Envoyer et stocker des valeurs

Les attributs de produit ou de compte sont transmis dans un tableau d’objets. Chaque objet contient l’identifiant de l’attribut et un tableau nommé `values`, même si le champ n’accepte qu’une seule valeur :

```json
{
  "attributes": [
    { "id": 71, "values": ["cotton", "linen"] },
    { "id": 72, "values": [true] }
  ]
}
```

Les champs à valeur unique doivent contenir exactement un élément dans `values`. Les champs de sélection utilisent les identifiants de la liste `values` de l’attribut. Les fichiers doivent être téléversés avant de transmettre leur URL ou référence. L’API stocke les valeurs soumises en JSON : conservez donc le type JSON documenté au lieu d’envoyer une chaîne représentant un booléen, un nombre ou un objet.

## Règles par type

| **type de champ** | **valeur attendue** | **règle importante** |
| --- | --- | --- |
| Sélection unique (`1`) | Un identifiant d’option | L’option doit être active et appartenir à cet attribut |
| Sélection multiple (`2`) | Tableau d’identifiants d’options | Chaque option doit être active et appartenir à cet attribut |
| Valeur libre (`3`) | Une valeur scalaire/libre | Exactement un élément |
| Valeurs libres multiples (`4`) | Tableau de valeurs libres | Plusieurs éléments sont autorisés |
| Pièces jointes (`5`) | Tableau d’URL ou références de fichiers | Téléversez les fichiers avant l’envoi |
| Zone de texte (`6`) | Une chaîne | Le texte multiligne est autorisé |
| Date/heure (`7`) | Une chaîne de date/heure | Utilisez une valeur ISO-8601 analysable, de préférence en UTC (`2026-09-15T10:30:00Z`) |
| Nombre (`8`) | Un nombre | Envoyez un nombre JSON, pas une chaîne formatée |
| Booléen (`9`) | Un booléen | Envoyez `true`/`false`, pas `"true"`/`"false"` |
| Couleur (`10`) | Une chaîne de couleur | Format hexadécimal (`#RGB`/`#RRGGBB`) ou `rgb(a)`/`hsl(a)` |
| JSON (`11`) | Un objet ou tableau JSON | Le JSON doit être valide et rester structuré |
| Emplacement (`12`) | Un objet | Incluez une `latitude` numérique (-90..90) et une `longitude` (-180..180) |
| Fichier audio (`13`) | URL/référence d’un fichier audio téléversé | Téléversez d’abord le fichier et conservez la référence renvoyée |
| Fichier vidéo (`14`) | URL/référence d’un fichier vidéo téléversé | Téléversez d’abord le fichier et conservez la référence renvoyée |