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 (mxcep_…) 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 un job de importación activo (no terminal) a la vez por usuario. Cancela o espera a que el job 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.example.com/v1/beneficiaries/imports/template' \
  -H 'Authorization: Bearer mxcep_••••' \
  --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.example.com/v1/beneficiaries/imports' \
  -H 'Authorization: Bearer mxcep_••••' \
  -F 'file=@beneficiarios.csv;type=text/csv' \
  -F 'parse_mode=template'

Respuesta 202 — job creado:

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

3. Sondear hasta preview_ready

El job pasa por los estados pending → parsing → preview_ready. Sondea GET /v1/beneficiaries/imports/{id} cada 2 segundos:

curl 'https://api.example.com/v1/beneficiaries/imports/42' \
  -H 'Authorization: Bearer mxcep_••••'

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

{
  "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 cubetas:

4. Revisar y corregir filas en el preview

Consulta el preview para ver las filas individuales, filtrando opcionalmente por cubeta:

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

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

curl -X PATCH \
  'https://api.example.com/v1/beneficiaries/imports/42/rows/102' \
  -H 'Authorization: Bearer mxcep_••••' \
  -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 el override 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 el preview, dispara el commit:

curl -X POST 'https://api.example.com/v1/beneficiaries/imports/42/commit' \
  -H 'Authorization: Bearer mxcep_••••'

Respuesta 202 — commit 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 del commit: 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 el job mientras esté en pending, parsing o preview_ready:

curl -X DELETE 'https://api.example.com/v1/beneficiaries/imports/42' \
  -H 'Authorization: Bearer mxcep_••••'

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.