← 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 | Campos de la importación. |
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` o `pdf`. |
parse_mode | string | Modo de parseo — `template`: Formato de columnas fijo (plantilla descargable); `free`: Formato libre, el sistema deduce la estructura. |
total_rows | integer | Total de filas extraídas del archivo (solo disponible una vez que el estado es `preview_ready` o posterior). |
valid_count | integer | Conteo de filas sin errores, listas para confirmación de persistencia. |
correctable_count | integer | Filas con correcciones automáticas aplicadas. Se persisten salvo que el usuario las rechace. |
fatal_count | integer | Filas con errores no corregibles automáticamente. No se persisten y se omiten de la confirmación. |
duplicate_count | integer | Suma de filas `duplicate_account` y `duplicate_alias`. Las filas con `duplicate_account` se omiten de la confirmación salvo que la cuenta esté archivada (en cuyo caso se reactiva); las `duplicate_alias` se persisten con sufijo de alias. |
committed_count | integer | Filas efectivamente persistidas en la lista de beneficiarios (solo disponible una vez que el estado es `completed`). |
skipped_count | integer | Filas no persistidas (fatales o `duplicate_account` sin reactivación posible). |
llm_invoked | boolean | `true` si 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 error cuando `status=failed` (p.ej. `file_corrupt`, `plan_cap_exceeded`). `null` en estados no fallidos. |
error_summary | string | null | Mensaje diagnóstico legible cuando `status=failed`. Los números de tarjeta (PANs) aparecen enmascarados en este campo. |
created_at | string (date-time) | Timestamp ISO 8601 en UTC con sufijo `Z` explícito. Ejemplo: `"2026-05-01T05:14:38Z"`. Cada campo `*_at`, `*_end`, `*_start`, `*_date` de la API usa esta forma. El descriptor compañero en `meta.datetime` permite afirmar el contrato en tiempo de ejecución sin volver a leer este spec. El `new Date(value)` nativo del navegador, el `datetime.fromisoformat` (≥3.11) de Python y el `time.Parse(time.RFC3339)` de Go parsean este formato directamente. |
parsed_at | string | null | Timestamp (ISO 8601 UTC) de finalización del parseo. `null` hasta que el parseo completa. |
committed_at | string | null | Timestamp (ISO 8601 UTC) del inicio de la confirmación. `null` hasta que la confirmación comienza. |
completed_at | string | null | Timestamp (ISO 8601 UTC) de finalización de la importación. `null` mientras la importación no ha completado. |
Usado en operaciones
GET /v1/beneficiaries/imports/{id}GET /v1/beneficiaries/imports/{id}/preview