# Atributos

Administra y consulta atributos.

**Tipos de campo**

| **tipo** | **descripción** |
| --- | --- |
| `1` | Selección única |
| `2` | Selección múltiple |
| `3` | Valor libre (único) |
| `4` | Valores libres (múltiples) |
| `5` | Archivos adjuntos |
| `6` | Área de texto |
| `7` | Fecha/hora |
| `8` | Número |
| `9` | Booleano |
| `10` | Color |
| `11` | JSON |
| `12` | Ubicación |
| `13` | Archivo de audio |
| `14` | Archivo de vídeo |

### Formato de valor por tipo de campo

| **tipo de campo** | **formato del valor** |
| --- | --- |
| Selección única (`1`) | Un identificador o valor de atributo. |
| Selección múltiple (`2`) | Matriz de identificadores o valores de atributo. |
| Valor libre (`3`) | Una cadena o valor escalar libre. |
| Varios valores libres (`4`) | Matriz de valores libres. |
| Archivos adjuntos (`5`) | Matriz de URL o referencias de archivos cargados. |
| Área de texto (`6`) | Cadena libre, normalmente multilínea. |
| Fecha/hora (`7`) | Cadena de fecha y hora ISO-8601. |
| Número (`8`) | Valor numérico. |
| Booleano (`9`) | `true` o `false`. |
| Color (`10`) | Cadena de color, por ejemplo un valor hexadecimal (`#FF0000`). |
| JSON (`11`) | Objeto o matriz JSON válidos. |
| Ubicación (`12`) | Objeto de ubicación, normalmente con latitud y longitud. |
| Archivo de audio (`13`) | URL o referencia de un archivo de audio cargado. |
| Archivo de vídeo (`14`) | URL o referencia de un archivo de vídeo cargado. |

## Objeto de respuesta del atributo

Un atributo describe un campo personalizado de un tipo de objeto (por ejemplo, un anuncio o una cuenta). `field_type` define el formato de entrada/valor; `type` define el ámbito del objeto y no debe confundirse con `field_type`.

**Ejemplo de objeto**

```
{
    "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
                }
            ]
        }
    ]
}

```

**Campos del objeto atributo**

| **nombre** | **tipo** | **descripción** |
| --- | --- | --- |
| `id` | `integer` | Identificador único del atributo |
| `name` | `string` | Nombre del atributo |
| `field_type` | `integer` | Tipo de campo del atributo; consulta la leyenda anterior |
| `icon_path` | `string \| null` | Icono o imagen opcional asociada al atributo |
| `optional` | `boolean` | Indica si el atributo es opcional |
| `private` | `boolean` | Indica si el atributo es privado; solo los administradores ven los atributos privados |
| `show_in_filter` | `boolean` | Indica si el atributo aparece en la lista de filtros |
| `visible` | `boolean` | Controla si el atributo se muestra a los clientes |
| `active` | `boolean` | Indica si el atributo está activo |
| `order_by` | `integer` | Orden de visualización entre atributos |
| `type` | `string` | Tipo del objeto que se devuelve |
| `attribute_group_id` | `integer \| null` | Grupo opcional para organizar atributos relacionados |
| `metadata` | `object \| array \| null` | Configuración adicional definida por el tenant; conserva su estructura JSON |
| `tooltip` | `string \| null` | Texto de ayuda opcional que se muestra para el campo |
| `categories` | `array` | Categorías asignadas al atributo; consulta el objeto categoría |
| `values` | `array` | Opciones activas para los tipos de campo 1 y 2; cada una incluye `id`, `name`, `active`, `order_by` y `metadata` |

`values` solo se devuelve para atributos de selección. Usa el `id` de una opción al enviar un valor de selección; no inventes identificadores.

## Enviar y guardar valores

Los atributos de productos o cuentas se envían como una matriz de objetos. Cada objeto contiene el ID del atributo y una matriz llamada `values`, incluso si el campo solo acepta un valor:

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

Los campos de valor único deben tener exactamente un elemento en `values`. Los campos de selección usan IDs de la lista `values` del atributo. Los archivos deben cargarse antes de proporcionar su URL o referencia. La API guarda los valores enviados como JSON; conserva el tipo JSON documentado y no envíes una cadena que represente un booleano, número u objeto.

## Reglas específicas por tipo

| **tipo de campo** | **valor esperado** | **regla importante** |
| --- | --- | --- |
| Selección única (`1`) | Un ID de opción | La opción debe estar activa y pertenecer a este atributo |
| Selección múltiple (`2`) | Matriz de IDs de opciones | Todas las opciones deben estar activas y pertenecer a este atributo |
| Valor libre (`3`) | Un valor escalar/libre | Exactamente un elemento |
| Varios valores libres (`4`) | Matriz de valores libres | Se permiten varios elementos |
| Archivos adjuntos (`5`) | Matriz de URL o referencias de archivos | Carga los archivos antes de enviarlos |
| Área de texto (`6`) | Una cadena | Se admite texto multilínea |
| Fecha/hora (`7`) | Una cadena de fecha/hora | Usa un valor ISO-8601 válido, preferiblemente UTC (`2026-09-15T10:30:00Z`) |
| Número (`8`) | Un número | Envía un número JSON, no una cadena formateada |
| Booleano (`9`) | Un booleano | Envía `true`/`false`, no `"true"`/`"false"` |
| Color (`10`) | Una cadena de color | Formato hexadecimal (`#RGB`/`#RRGGBB`) o `rgb(a)`/`hsl(a)` |
| JSON (`11`) | Un objeto o matriz JSON | Debe ser JSON válido y conservar su estructura |
| Ubicación (`12`) | Un objeto | Incluye `latitude` numérica (-90..90) y `longitude` (-180..180) |
| Archivo de audio (`13`) | URL/referencia de audio cargado | Carga primero el archivo y conserva la referencia devuelta |
| Archivo de vídeo (`14`) | URL/referencia de vídeo cargado | Carga primero el archivo y conserva la referencia devuelta |