Estado de un job de importación

GET https://api.veriko.mx/v1/beneficiaries/imports/{id}

Audiencia: public
Autenticación: API key
Permiso: beneficiaries:create

Devuelve el estado del job y los contadores por bucket: valid, correctable, fatal, duplicate_account (sumados en duplicate_count) y committed/skipped post-commit. Sondea este endpoint cada 2 s hasta que status sea preview_ready, completed, failed o cancelled.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`id` *	path	`integer`	obligatorio	ID numérico del job de importación.

Petición

cURLPython•JavaScript•PHP•

curl -X GET 'https://api.veriko.mx/v1/beneficiaries/imports/{id}' \
  -H 'Authorization: Bearer mxcep_••••'

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 200** `BeneficiaryImportJobResponse` — Estado actual del job con contadores por bucket.
Campo	Tipo	Descripción
`type`	`string`	Tipo del recurso JSON:API (siempre `beneficiary_import`).
`id`	`string`	ID numérico del job expresado como string (formato JSON:API).
`attributes`	`object`	Campos del job de importación.
`status`	`string`	Estado del job: `pending` — subido, 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` — commit finalizado; `failed` — fallo no recuperable (ver `error_code`); `cancelled` — cancelado por el usuario.
`file_format`	`string`	Formato del archivo subido. Aceptados: CSV, Excel (xls/xlsx), texto plano y PDF.
`parse_mode`	`string`	Modo de parseo: `template` — formato de columnas fijo (plantilla descargable desde `/v1/beneficiaries/imports/template`); `free` — formato libre, el sistema deduce la estructura.
`total_rows`	`integer`	Total de filas extraídas del archivo. Disponible una vez que el estado es `preview_ready` o posterior.
`valid_count`	`integer`	Filas sin errores, listas para commit directo.
`correctable_count`	`integer`	Filas con correcciones automáticas aplicadas (p.ej. alias auto-asignado). Se persisten salvo que el usuario las rechace.
`fatal_count`	`integer`	Filas con errores no corregibles automáticamente. No se persisten y se omiten del commit.
`duplicate_count`	`integer`	Suma de filas `duplicate_account` y `duplicate_alias`. Las `duplicate_account` se omiten del commit 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. 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 se utilizó durante el parseo para resolver filas ambiguas en modo libre.
`error_code`	`string \| null` anulable	Código estable del error cuando `status=failed` (p.ej. `file_corrupt`, `plan_cap_exceeded`). `null` en estados no fallidos.
`error_summary`	`string \| null` anulable	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` anulable	Timestamp (ISO 8601 UTC) de finalización del parseo. `null` hasta que el parseo completa.
`committed_at`	`string \| null` anulable	Timestamp (ISO 8601 UTC) del inicio del commit. `null` hasta que el commit comienza.
`completed_at`	`string \| null` anulable	Timestamp (ISO 8601 UTC) de finalización del job. `null` mientras el job no ha completado.

**Códigos de respuesta** `GET /v1/beneficiaries/imports/{id}`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Estado actual del job con contadores por bucket.	`BeneficiaryImportJobResponse`
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
404	`4xx`	El recurso no existe o no es visible para el llamador	`Error`

**Errores de `GET /v1/beneficiaries/imports/{id}`**
Código	Clave	Detalle
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c0`