`ValidationImportJob`

JSON:API envelope for a bulk validation import job. State lifecycle: pending → parsing → preview_ready → committing → completed (or failed / cancelled).

Properties

Field	Type	Description
`type`	`string`	JSON:API resource type (always `validation_import`).
`id`	`string`	Numeric job ID as a string (JSON:API convention).
`attributes`	`object`	Import job attributes.
`status`	`string`	Current lifecycle state: `pending` = received, awaiting parsing; `parsing` = extracting and validating rows; `preview_ready` = parsing complete, awaiting user review; `committing` = processing approved rows against Banxico; `completed` = all rows processed; `failed` = unrecoverable error; `cancelled` = cancelled by the user.
`upload_type`	`string`	Uploaded file type: `text` = text file (CSV, XLSX, TXT, JSON); `images` = ZIP file containing receipt images.
`file_format`	`string`	Format of the uploaded file (`csv`, `xls`, `xlsx`, `txt`, `json`, `zip_text`, or `zip_images`).
`parse_mode`	`string`	Parse mode: `template` = columns in predefined template order; `free` = automatic column detection with Gemini as fallback.
`total_rows`	`integer`	Total rows detected in the file after parsing.
`valid_count`	`integer`	Valid rows in preview (complete data ready to send to Banxico).
`correctable_count`	`integer`	Correctable rows in preview (one or more missing or incorrect fields that the user can edit).
`fatal_count`	`integer`	Fatal rows in preview (not processable even after editing, e.g. invalid tracking key).
`duplicate_count`	`integer`	Rows duplicated within the same batch (same clave_rastreo or other repeated key fields).
`dispatched_count`	`integer`	Rows dispatched to the validation stream after commit. Available only in `committing` and `completed` states.
`completed_valid_count`	`integer`	Rows whose Banxico CEP validation returned `valid`.
`completed_not_found_count`	`integer`	Rows whose Banxico CEP validation was not found in its records.
`completed_invalid_count`	`integer`	Rows rejected by Banxico for invalid data.
`completed_cep_unavailable_count`	`integer`	Rows where Banxico CEP was unavailable during validation.
`completed_error_count`	`integer`	Rows with unresolvable terminal errors (network, captcha, preflight failure).
`skipped_count`	`integer`	Rows skipped from processing (cross-batch duplicates or cancelled by the user).
`ocr_invoked`	`boolean`	true if Gemini OCR was invoked during parsing. Only relevant when `upload_type = images`.
`ocr_input_tokens`	`integer`	Input tokens consumed by Gemini for batch OCR. 0 if `ocr_invoked = false`.
`ocr_output_tokens`	`integer`	Output tokens generated by Gemini for batch OCR. 0 if `ocr_invoked = false`.
`error_code`	`string \| null`	Error code if the job ended in `failed` state. null in all other states.
`error_summary`	`string \| null`	Error description if the job ended in `failed` state. null if the job did not fail.
`created_at`	`string (date-time)`	ISO 8601 timestamp in UTC with explicit `Z` suffix. Example: `"2026-05-01T05:14:38Z"`. Every datetime field uses this shape. The descriptor at `meta.datetime` makes the contract runtime-assertable.
`parsed_at`	`string \| null`	ISO 8601 timestamp when parsing was completed. `null` if not yet completed.
`committed_at`	`string \| null`	ISO 8601 timestamp when the commit was completed. `null` if not yet performed.
`completed_at`	`string \| null`	ISO 8601 timestamp when all rows were processed. `null` if the job has not completed.

Used in operations

GET /v1/validations/imports/{id}
GET /v1/validations/imports/{id}/preview