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.

Si la lista tiene una importación en awaiting_mapping (se subió el archivo antes de declarar las columnas), las columnas se validan contra la cabecera de ese archivo y la importación queda en cola. La vista previa (GET /v1/lists/{id}/preview) propone el campo de cada columna.

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": "replace"
    },
    { "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 | discard | replace` | null

Solo para una columna única. Qué hace la importación con una fila que repite el valor: error descarta la fila repetida y la informa, discard conserva la primera, replace reemplaza la primera por la repetida. 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. Si una importación esperaba las columnas, queda en pending y recibe su job_id, que se ve al consultarla con GET /v1/lists/{id}/imports/{import_id}.

Errores

Código	Cuándo
404	La lista no existe o fue eliminada (list_not_found).
409	La lista salió de una instantánea de un dataset (list_is_snapshot), ya tiene datos (list_has_data) o tiene una importación en curso (list_import_in_progress). También cuando 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. También list_file_columns_missing en /fields: una importación espera las columnas y a la cabecera de su archivo le falta la columna de algún campo declarado. errors[].params trae lo mismo que al subir el archivo (POST /v1/lists/{id}/imports). No se guarda nada y la importación sigue esperando.
503	No se pudo dejar en cola la importación que esperaba las columnas (service_unavailable). No se guarda nada: reintente.

Detalle completo en Errores genéricos.

Notas

• Las columnas quedan fijas cuando la lista recibe sus datos (409 list_has_data). Tampoco se pueden cambiar mientras una importación está pendiente o en curso (409 list_import_in_progress). Si la importación falla, puede corregirlas antes de volver a subir el archivo.
• Para una columna que todavía no existe en el catálogo, cree primero el campo con POST /v1/fields. La vista previa trae, en suggested_field, el nombre, la clave y el tipo listos para crearlo.

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.