Docs
EN
POSThttps://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) de hasta 20 MB y abre con él un trabajo de importación.

El modo de lectura decide cuánto trabajo hace el archivo y cuánto el servidor:

  • template: el archivo respeta los encabezados canónicos, que se obtienen de /v1/beneficiaries/imports/template. El banco se deriva del prefijo de la CLABE o del BIN de la tarjeta.
  • free: cualquier formato. Las cuentas se extraen del contenido, con apoyo de un LLM cuando el archivo no tiene estructura reconocible.

La importación no persiste nada por sí sola. Queda a la espera de una confirmación explícita. La secuencia completa son cuatro pasos:

  1. Esta llamada (POST /v1/beneficiaries/imports) devuelve el identificador del trabajo.
  2. GET /v1/beneficiaries/imports/{id} informa del avance hasta preview_ready o failed.
  3. GET /v1/beneficiaries/imports/{id}/preview muestra las filas extraídas, y PATCH /v1/beneficiaries/imports/{id}/rows/{row_id} corrige las que hagan falta.
  4. POST /v1/beneficiaries/imports/{id}/commit persiste el resultado.

El sondeo del paso 2 y su cadencia están descritos en las operaciones asíncronas.

Petición
curl -X POST 'https://api.veriko.mx/v1/beneficiaries/imports' \
  -H 'Authorization: Bearer veriko_••••' \
  -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 202CreateBeneficiaryImportResponse — Trabajo de importación creado y esperando procesamiento.
CampoTipoDescripción
dataobject

Payload principal de la respuesta. La forma varía según el endpoint (objeto, array, o envelope JSON:API con type, id, attributes).

type*string

Tipo del recurso JSON:API. Siempre beneficiary_import.

p. ej. beneficiary_import
id*string

Identificador numérico del trabajo de importación (expresado como string).

p. ej. 42
attributes*object

Atributos iniciales de la importación devueltos al crearlo.

status*string

Estado inicial del trabajo de importación. El único valor posible es pending.

p. ej. pending
metaobject

Metadatos de la respuesta, incluyendo versión de la API, prefijo de ruta, identificador único de la petición y marca temporal del servidor en UTC.

versionstring

Versión de la API que procesó la petición.

p. ej. 1.47.0
api_versionstring

Versión del prefijo de ruta de la API (ej. v1).

p. ej. v1
request_idstring

Identificador único de la petición (hex).

p. ej. a1b2c3d4e5f6
datetimeobject

Descriptor compañero presente en el bloque meta de cada respuesta (y en el meta del cuerpo de los webhooks salientes). Permite a los clientes afirmar el contrato de zona horaria sin releer el spec.

p. ej. {"timezone":"UTC","format":"ISO 8601"}
timezone*string

Siempre UTC — la zona canónica para cada campo datetime del cuerpo.

p. ej. UTC
format*string

Siempre ISO 8601 — sufijo Z explícito en cada datetime.

p. ej. ISO 8601
linksobject

Enlaces de paginación o relacionados, presentes solo cuando el endpoint devuelve una colección paginada.

Códigos de respuestaPOST /v1/beneficiaries/imports
CódigoClaseDescripciónCuerpo
2022xxTrabajo de importación creado y esperando procesamiento.CreateBeneficiaryImportResponse
4014xxSe requiere autenticación o las credenciales son inválidasErrorResponse
4034xxPermisos insuficientesErrorResponse
4224xxFalló la validación o la pre-condición. Códigos posibles: file_required, file_too_large, unsupported_format e import_already_in_flight.ErrorResponse
Errores de POST /v1/beneficiaries/imports
CódigoClaveEjemplo
401unauthorized

Credenciales de autenticación ausentes o inválidas.

Envelope
meta.request_id
c4d5e6f7a8b9
403forbidden

No tienes permiso para acceder a este recurso.

Envelope
meta.request_id
d5e6f7a8b9c0
422file_required

Falta la parte `file` en el cuerpo multiparte.

Envelope
meta.request_id
f2a3b4c5d6e7