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.
• 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. Llena tus datos y guarda. Los códigos de banco se derivan automáticamente del prefijo CLABE o del BIN de la tarjeta.

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

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. Las cuentas previamente archivadas con el mismo número se reactivan en lugar de duplicarse.

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.