Docs
EN
POST https://api.veriko.mx/v1/beneficiaries/imports

Iniciar importación masiva de beneficiarios

Audiencia
public
Autenticación
API key
Permiso
beneficiaries:create
Guía de uso →

Sube un archivo (CSV, XLS, XLSX, TXT o PDF, hasta 20 MB) y crea un job de importación asíncrono. El usuario solo puede tener un job activo (no terminal) por vez — un upload concurrente devuelve 422. Modos de parseo:

  • template: el archivo respeta los encabezados canónicos (descarga la plantilla desde /v1/beneficiaries/imports/template). El banco se deriva del prefijo CLABE o del BIN.
  • free: cualquier formato; el sistema extrae las cuentas automáticamente, con fallback IA para formatos no estructurados.

El job pasa por los estados pending → parsing → preview_ready y queda esperando la confirmación del usuario. Sondea GET /v1/beneficiaries/imports/{id} hasta preview_ready o failed; cuando llega a preview_ready revisa y edita las filas vía GET /v1/beneficiaries/imports/{id}/preview y finalmente confirma con POST /v1/beneficiaries/imports/{id}/commit.

Petición
curl -X POST 'https://api.veriko.mx/v1/beneficiaries/imports' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json'

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

Probar en el playground →
Respuesta 202 CreateBeneficiaryImportResponse — Job de importación creado y encolado para procesamiento.
Campo Tipo Descripción
type * string

Tipo del recurso JSON:API.
id * string

ID numérico del job expresado como string (formato JSON:API).
attributes * object

Atributos iniciales del job devueltos al crearlo.
status * string

Estado inicial del job.
Códigos de respuesta POST /v1/beneficiaries/imports
Código Clase Descripción Cuerpo
202 2xx Job de importación creado y encolado para procesamiento. CreateBeneficiaryImportResponse
401 4xx Se requiere autenticación o las credenciales son inválidas ErrorResponse
403 4xx Permisos insuficientes ErrorResponse
422 4xx Falló la validación o la pre-condición. Códigos posibles: `file_required`, `file_too_large`, `unsupported_format`, `active_job_exists`, `parse_mode_invalid`. ErrorResponse
Errores de POST /v1/beneficiaries/imports
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
422 file_required

A `file` part is required in the multipart body.

Envelope
meta.request_id
f2a3b4c5d6e7