← Volver al índice de esquemas
BeneficiaryImportJob
Importación masiva de beneficiarios. Ciclo de vida: `pending` → `parsing` → `preview_ready` → `committing` → `completed` (o `failed` / `cancelled`). Envuelto bajo `{ type, id, attributes }` siguiendo el formato JSON:API.
ExtiendeJsonApiResourceBase
Propiedades
| Campo | Tipo | Descripción |
|---|---|---|
type | string | Tipo del recurso JSON:API. Siempre `beneficiary_import`. |
id | string | Identificador numérico del trabajo de importación (expresado como string). |
attributes | object | Datos del trabajo de importación. |
plan_cap | object | Cupo de beneficiarios activos del plan y ocupación actual de la cuenta autenticada. |
max | integer | Tope de beneficiarios activos. `-1` significa sin tope. |
current | integer | Cantidad de beneficiarios activos guardados, independientemente del filtro de archivados. |
required | integer | Cantidad de lugares necesarios para crear o reactivar cuentas del trabajo de importación. |
exceeded | boolean | `true` cuando el trabajo de importación necesita lugares nuevos y supera el cupo disponible. |
status | string | Estado del trabajo de importación — `pending`: Subido y en espera de parseo; `parsing`: En proceso de extracción de filas; `preview_ready`: Listo para revisión del usuario; `committing`: Persistiendo filas confirmadas; `completed`: Importación completada; `failed`: Fallo no recuperable (ver `error_code`); `cancelled`: Cancelado por el usuario. |
file_format | string | Formato del archivo subido. Aceptados: `csv`, `xls`, `xlsx`, `txt`, `json` o `pdf`. |
parse_mode | string | Modo de lectura del archivo — `template`: Respeta los encabezados canónicos; `free`: Formato libre, el sistema deduce la estructura. |
total_rows | integer | Cantidad de filas extraídas del archivo. Sólo disponible cuando el estado es `preview_ready` o posterior. |
valid_count | integer | Cantidad de filas sin errores, listas para la confirmación. |
correctable_count | integer | Cantidad de filas con errores que admiten corrección. Se persisten salvo que el usuario las rechace. |
fatal_count | integer | Cantidad de filas que no pueden procesarse con sus datos actuales. No se persisten y se omiten de la confirmación. |
duplicate_count | integer | Cantidad de filas detectadas como duplicadas dentro del trabajo. Las de `duplicate_account` se omiten de la confirmación, salvo que la cuenta esté archivada, en cuyo caso se reactiva; las de `duplicate_alias` se persisten con un sufijo en el alias. |
committed_count | integer | Filas efectivamente persistidas en la lista de beneficiarios (solo disponible una vez que el estado es `completed`). |
skipped_count | integer | Cantidad de filas omitidas durante la ejecución del trabajo. Son las fatales y las `duplicate_account` sin reactivación posible. |
llm_invoked | boolean | `true` cuando el motor de IA (LLM) se utilizó durante el parseo para resolver filas ambiguas en modo libre. |
error_code | string | null | Código estable del fallo del trabajo. `null` cuando no terminó en `failed`. Por ejemplo, `file_corrupt` o `empty_file`. |
error_summary | string | null | Resumen legible del fallo del trabajo. `null` cuando no terminó en `failed`. Los números de tarjeta aparecen enmascarados. |
created_at | string (date-time) | Timestamp ISO 8601 en UTC con sufijo `Z` explícito; por ejemplo, `"2026-05-01T05:14:38Z"`. Los campos `*_at`, `*_end`, `*_start` y `*_date` adoptan esta forma. `meta.datetime` describe el mismo contrato en la respuesta. |
parsed_at | string | null | Fecha y hora del fin de la lectura del archivo, en ISO 8601 UTC. `null` mientras no haya terminado. |
committed_at | string | null | Fecha y hora del inicio de la confirmación, en ISO 8601 UTC. `null` mientras no se haya confirmado. |
completed_at | string | null | Fecha y hora de la finalización, en ISO 8601 UTC. `null` mientras no haya terminado. |
Usado en operaciones
GET /v1/beneficiaries/imports/{id}GET /v1/beneficiaries/imports/{id}/preview