---
title: "Importar items mediante inserción, upsert o reemplazo de registros vigentes."
method: POST
path: "/collections/{collectionId}/items/import"
tags: ["Items"]
---

# Importar items mediante inserción, upsert o reemplazo de registros vigentes.

`POST /collections/{collectionId}/items/import`

## Request

- Base URL: `https://api.met.meteor.com.co/api/v1`
- URL: `https://api.met.meteor.com.co/api/v1/collections/{collectionId}/items/import`
- Auth: one of:
  - `bearer` (a scheme the document does not define)
  - HTTP bearer

Carga un lote en una sola llamada, y su comportamiento cambia por completo según mandes `keyField` o no. **Con `keyField`** hace upsert: la fila que ya exista con ese valor se actualiza en vez de duplicarse — es lo que quieres para espejar un catálogo o un inventario y poder reejecutarlo. **Sin `keyField`** inserta todo tal cual, sin deduplicar: repetir la llamada crea los items otra vez. Con `mode=replace_active`, el archivo completo pasa a ser la versión vigente: primero se valida, luego se crean o actualizan sus filas y se archivan las ausentes dentro de una única transacción. `keyFields` permite una identidad compuesta; la confirmación debe reenviar el `previewToken` de la vista previa y declarar `allowHighArchive=true` cuando archivará 30 % o más. Este modo no admite colecciones globales, internas o protegidas.

## Path parameters

- `collectionId` number, required

## Request body

- ImportItemsDto
  - `allowHighArchive` boolean: Confirmación adicional para reemplazos que archivan 30 % o más de los registros vigentes.
  - `dryRun` boolean: Valida y calcula el impacto sin escribir cambios.
  - `fileName` string: Nombre original del archivo para la bitácora.
  - `keyField` string: Field clave para upsert (match por data->>keyField). Si se omite → modo insert-only: inserta todas las filas sin deduplicar.
  - `keyFields` string[]: Campos que, combinados y en este orden, identifican cada registro. Permite claves compuestas (por ejemplo cliente + producto). Si se omite, se usa keyField.
  - `mode` 'upsert' | 'replace_active': replace_active convierte el archivo completo en la fuente de registros vigentes. Rechaza colecciones globales, internas o protegidas.
  - `previewToken` string: Token devuelto por la vista previa. Es obligatorio al confirmar y evita reemplazar si la colección cambió entretanto.
  - `revision` string: Revisión auditable del archivo. Obligatoria en replace_active.
  - `rows` object[], required: Filas a importar (máx 5000), keyed por field name.

## Response `201`

- object: Sobre en el que viaja toda respuesta correcta de la API. El recurso está en `data`. Los SDKs oficiales lo desenvuelven por ti; un cliente hecho a mano tiene que leer `.data`.
  - `success` true, required: Siempre `true` en una respuesta 2xx.
  - `data` ItemImportResultDto, required
    - `active_after` number
    - `active_before` number
    - `archive_ratio` number: Proporción de registros vigentes que serán archivados.
    - `archived` number
    - `consolidated_duplicates` number
    - `created` number, required: Filas que se insertaron como ítems nuevos.
    - `dry_run` boolean: Indica que la operación solo simuló el resultado.
    - `errors` ItemImportErrorDto[], required
      - `reason` string, required
      - `row` number, required: Índice de la fila en el arreglo que mandaste, empezando en 0.
    - `key_field` string: Campo usado como identidad durante el reemplazo.
    - `key_fields` string[]: Campos que componen la identidad estable del registro, en orden.
    - `mode` 'upsert' | 'replace_active'
    - `preview_token` string: Token de concurrencia devuelto por la vista previa y exigido al confirmar.
    - `reactivated` number
    - `revision` string
    - `skipped` number, required: Filas que matchearon pero no traían ningún cambio. Siempre 0 sin `keyField`.
    - `updated` number, required: Filas que matchearon por `keyField` y cambiaron algún valor. Siempre 0 sin `keyField`.

## Other responses

- `400`: La request no es válida: un campo no pasa validación, falta un parámetro requerido o el recurso no admite la transición solicitada.
- `401`: API key ausente, inválida, revocada o expirada — o el workspace está bloqueado.
- `403`: La key está autenticada pero no puede ejecutar esta operación: scope faltante, capacidad deshabilitada, modo test restringido o recurso fuera de su cartera.
- `404`: El recurso no existe o no está disponible dentro del alcance de la key. No revela la existencia de recursos de otros tenants.
- `409`: La operación entra en conflicto con el estado actual o con un Idempotency-Key en uso. No reintentes con el mismo key y un body distinto.
- `429`: Se superó el límite por minuto de la key o la cuota del plan. Respeta `Retry-After`; el SDK ya reintenta solo.
- `500`: Error del servidor o del Met que ejecutaba. El SDK reintenta los 5xx con backoff.

---

[API](https://skmtc.dev/meteor/apis/met-public-api.md) · [All operations](https://skmtc.dev/meteor/apis/met-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/meteor/apis/met-public-api/revisions/5d9ca294295c?raw)