Importación masiva de beneficiarios

Objetivo

Subir una hoja de cálculo o CSV con cuentas beneficiarias (CLABEs, tarjetas o números DiMo), revisar cómo se clasificó cada fila, corregir los errores subsanables y confirmar la importación — creando todas las cuentas válidas en una sola operación.

Requisitos previos

• Una API key activa (veriko_…) con el permiso beneficiaries:create.
• Un archivo en alguno de los formatos soportados: CSV, XLS, XLSX, TXT o PDF. Tamaño máximo: 20 MB.
• Las hojas XLSX/XLS admiten hasta 10 000 filas y 64 columnas; las fórmulas de XLSX se leen como texto, sin calcularlas. Los PDF admiten hasta 50 páginas.
• Solo puede haber una importación activo (no terminal) a la vez por usuario. Cancela o espera a que la importación anterior termine antes de subir un nuevo archivo.

Pasos

1. (Opcional) Descargar la plantilla

Para mejores resultados usa la plantilla canónica — el parser la maneja sin necesidad de IA:

curl 'https://api.veriko.mx/v1/beneficiaries/imports/template' \
  -H 'Authorization: Bearer veriko_••••' \
  --output plantilla-beneficiarios.csv

El CSV de la plantilla tiene las columnas alias, cuenta y banco. Llena tus datos y guarda. El banco se deriva del prefijo CLABE o del BIN; para un celular DiMo, escríbelo en banco.

2. Subir el archivo

Envía el archivo como multipart/form-data. Elige el parse_mode:

• template — el archivo sigue los encabezados de columna canónicos (recomendado).
• free — cualquier estructura; el sistema extrae cuentas automáticamente con fallback de IA para formatos no estructurados.

curl -X POST 'https://api.veriko.mx/v1/beneficiaries/imports' \
  -H 'Authorization: Bearer veriko_••••' \
  -F '[email protected];type=text/csv' \
  -F 'parse_mode=template'

Respuesta 202 — importación creado:

{
  "data": {
    "type": "beneficiary_import",
    "id": "42",
    "attributes": { "status": "pending" }
  }
}

3. Sondear hasta preview_ready

La importación pasa por los estados pending → parsing → preview_ready. Sondea GET /v1/beneficiaries/imports/{id} cada 2 segundos:

curl 'https://api.veriko.mx/v1/beneficiaries/imports/42' \
  -H 'Authorization: Bearer veriko_••••'

Cuando status es preview_ready, la respuesta incluye contadores por grupo:

{
  "data": {
    "id": "42",
    "attributes": {
      "status": "preview_ready",
      "total_rows": 150,
      "valid_count": 120,
      "correctable_count": 20,
      "fatal_count": 5,
      "duplicate_count": 5
    }
  }
}

Significado de las grupos:

4. Revisar y corregir filas en la vista previa

Consulta la vista previa para ver las filas individuales, filtrando opcionalmente por grupo:

# Solo filas corregibles
curl 'https://api.veriko.mx/v1/beneficiaries/imports/42/preview?buckets[]=correctable' \
  -H 'Authorization: Bearer veriko_••••'

Para corregir una fila (por ejemplo, asignar un código de banco a un número de celular DiMo):

curl -X PATCH \
  'https://api.veriko.mx/v1/beneficiaries/imports/42/rows/102' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "parsed_account_type": "phone",
    "parsed_bank_code": "40012",
    "parsed_bank_name": "BBVA MEXICO"
  }'

El servidor reprocesa la fila inmediatamente y devuelve su estado actualizado. Si la corrección resuelve el error, status cambia de correctable a valid.

Cinco campos son editables por fila: parsed_account, parsed_label, parsed_account_type, parsed_bank_code, parsed_bank_name.

5. Confirmar la importación

El trabajo y meta.job de la vista previa incluyen plan_cap: max es el tope del plan (-1 significa sin tope), current cuenta las cuentas activas y required suma las cuentas nuevas y las archivadas que se reactivarán.

Cuando exceeded=true, la consola bloquea Confirmar. Puedes archivar una cuenta activa o quitar filas hasta quedar dentro del cupo. Para quitar una fila:

curl -X DELETE 'https://api.veriko.mx/v1/beneficiaries/imports/42/rows/102' \
  -H 'Authorization: Bearer veriko_••••'

Devuelve 204 y recalcula grupos y contadores, conservando las correcciones de las filas restantes. Solo se permite en preview_ready; después responde 422 job_not_editable. El servidor vuelve a comprobar el cupo al confirmar y devuelve 422 plan_cap_exceeded si todavía se supera. No crea un lote parcial.

Cuando estés satisfecho con la vista previa, dispara la confirmación:

curl -X POST 'https://api.veriko.mx/v1/beneficiaries/imports/42/commit' \
  -H 'Authorization: Bearer veriko_••••'

Respuesta 202 — confirmación encolado:

{
  "data": {
    "id": "42",
    "attributes": { "status": "committing" }
  }
}

Sondea GET /v1/beneficiaries/imports/42 hasta que status sea completed o failed. Al completar, la respuesta muestra committed_count y skipped_count:

{
  "data": {
    "attributes": {
      "status": "completed",
      "committed_count": 140,
      "skipped_count": 10
    }
  }
}

Reglas de la confirmación: las filas valid y correctable se persisten. Las filas fatal y duplicate_account se omiten. Un celular sin banco válido queda como correctable con el código bank_code_required_for_phone (o invalid_bank_code si el banco no existe) y se corrige eligiendo el banco en esa fila de la vista previa; si al confirmar sigue sin banco, no se guarda en silencio: la fila se omite, queda como fatal con ese mismo código y cuenta en skipped_count, y plan_cap.required no la cuenta. Las cuentas previamente archivadas con el mismo número se reactivan en lugar de duplicarse y conservan su alias si la fila no trae uno. Si entre la vista previa y la confirmación una cuenta del archivo se registra por otra vía, esa fila se omite como duplicate_account y el resto del lote se guarda.

6. (Opcional) Cancelar antes de confirmar

Si necesitas empezar de nuevo, cancela la importación mientras esté en pending, parsing o preview_ready:

curl -X DELETE 'https://api.veriko.mx/v1/beneficiaries/imports/42' \
  -H 'Authorization: Bearer veriko_••••'

Devuelve 204 en caso de éxito.

Siguientes pasos

• Consulta los beneficiarios creados: GET /v1/beneficiaries.
• Agrega o actualiza beneficiarios individualmente: POST /v1/beneficiaries, PUT /v1/beneficiaries/{id}.
• Exporta la lista completa para conciliación: GET /v1/beneficiaries/export.