Saltar al contenido principal
Migo Docs

Cargas Masivas

API RESTRINGIDA

Requiere autorización de partner / operador. Consulta CMS → Inicio.

Crea miles de tarjetahabientes (o emite miles de tarjetas) en una sola operación. El progreso se transmite mediante Server-Sent Events para que la interfaz del CMS pueda mostrar una barra de progreso en vivo.

Cargar tarjetahabientes​

La carga de tarjetahabientes usa el campo de formulario users:

curl -X POST "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/upload" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>" \
  -F "users=@cardholders.xlsx"

Acepta únicamente .xlsx / .xls (el CSV es rechazado). El único límite es un tamaño de archivo de 16 MB — no hay un tope de cantidad de filas.

Respuesta (HTTP 200):

{
  "success": true,
  "message": "...",
  "data": {
    "id": "bat_01HAAA"
  }
}

data.id es el ID del lote usado para suscribirse al flujo de progreso vía SSE.

Columnas requeridas (Excel)​

name,lastName,address,countryOfBirth,dateOfBirth,maritalStatus,gender,phoneNumber,email,documentType,documentNumber,cardId
María,Ramírez,Calle Principal 123,GT,1990-05-12,soltero,F,50255551234,maria@example.com,DPI,2345678901234,1
Juan,Pérez,Av. Reforma 45,GT,1985-12-03,casado,M,50255559999,juan@example.com,DPI,9876543210987,2

Todas las columnas son obligatorias. Los valores de enumeración coinciden con el payload de creación de un solo tarjetahabiente (maritalStatus, gender, documentType, countryOfBirth, dateOfBirth); cardId es la tarjeta numérica que se asignará.

Cargar tarjetas (emisión por lote)​

La carga de tarjetas usa el campo de formulario cards:

curl -X POST "https://api.ali.app/cms/rest/app/partners/{partnerId}/cards/upload" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>" \
  -F "cards=@cards.xlsx"

Seguimiento de progreso vía SSE​

Abre una conexión HTTP de larga duración para recibir el progreso en tiempo real:

curl "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/batch/{batchId}/progress" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>" \
  -H "Accept: text/event-stream" \
  --no-buffer

El flujo emite tramas data: sin nombre (sin línea event:). Cada trama transporta:

data: {"batchId":"bat_01HAAA","timestamp":"2026-03-01T10:00:00Z","stage":"processing","total":5423,"processed":2400,"successful":2378,"failed":22,"percentage":44,"message":"..."}

data: {"batchId":"bat_01HAAA","timestamp":"2026-03-01T10:01:00Z","stage":"completed","total":5423,"processed":5423,"successful":5380,"failed":43,"percentage":100,"message":"..."}

Usa el campo stage para detectar la finalización. Valores posibles: processing, completed, error, timeout.

Ejemplo con EventSource en el navegador​

const es = new EventSource(`/cms/rest/app/partners/${partnerId}/cardholders/batch/${batchId}/progress`, {
  withCredentials: true,
});

es.onmessage = (e) => {
  const p = JSON.parse(e.data);
  setProgress(p.percentage);
  if (p.stage === 'completed' || p.stage === 'error' || p.stage === 'timeout') {
    es.close();
  }
};
aviso

El progreso vía SSE es en memoria y solo de un único pod. Los eventos de progreso de NATS son fire-and-forget — si no hay ningún listener conectado cuando se dispara un evento, ese evento se pierde. La conexión también se cierra tras un tiempo de inactividad (emitiendo una trama stage: "timeout").