Declarar las columnas de una lista

PUT/v1/lists/{id}/fields

Para desarrolladores

Descripción

Declara las columnas de una lista: a qué campo del catálogo corresponde cada columna del CSV, por su posición. Reemplaza el conjunto completo: una columna que no se envía deja de estar declarada.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope list:write. Formato: Bearer <API_KEY>.

X-Instance-Slugstringheaderobligatorio

Identificador de su instancia. Ver Autenticación.

Request

Path params:

idintegerobligatorio

Identificador de la lista.

Body:

{
  "fields": [
    {
      "field_id": 1,
      "csv_pos": 1,
      "is_required": true,
      "is_unique": true,
      "unique_action": "update"
    },
    { "field_id": 12, "csv_pos": 2 }
  ]
}

fieldsobject[]obligatorio

Al menos una columna. Ni un campo ni una posición pueden repetirse.

field_idintegerobligatorio

Campo del catálogo (`GET /v1/fields`). Debe existir y estar activo.

csv_posintegerobligatorio

Posición de la columna en el CSV, contando desde 1 (1–65535).

is_requiredboolean

La importación descarta las filas sin valor en esta columna. Default: false.

is_uniqueboolean

La importación no admite dos filas con el mismo valor en esta columna. Default: false.

unique_actionstring, enum: `error | ignore | update` | null

Solo para una columna única. Qué hace la importación con una fila que repite el valor: error la descarta y la informa, ignore conserva la primera, update la reemplaza por la nueva. Default: error. Enviarlo en una columna que no es única se rechaza con 422.

Un campo que no figura en esta tabla se rechaza con 422.

Response

204 No ContentLa respuesta no trae body.

Errores

Código	Cuándo
404	La lista no existe o fue eliminada (list_not_found).
409	Un campo viene dos veces (list_field_duplicated), dos columnas comparten posición (list_field_position_duplicated), un campo no existe (list_field_not_found) o está desactivado (list_field_inactive).
422	El body no es válido.

Detalle completo en Errores genéricos.

Notas

• Las columnas se pueden cambiar aunque la lista ya tenga datos. Las importaciones siguientes usan el mapeo nuevo.
• Para una columna que todavía no existe en el catálogo, primero se crea el campo con POST /v1/fields.

Request

curl -X PUT "https://$API_HOST/v1/lists/4/fields" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG" \
-H "Content-Type: application/json" \
-d '{
  "fields": [
    {
      "field_id": 1,
      "csv_pos": 1,
      "is_unique": true
    },
    {
      "field_id": 12,
      "csv_pos": 2
    }
  ]
}'

Response

Sin cuerpo: la respuesta no trae contenido.