Tarjetahabientes (CMS)

API RESTRINGIDA

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

Gestión de tarjetahabientes orientada al operador. Cada endpoint está acotado a un partnerId.

Listar tarjetahabientes de un partner

curl "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders?page=1&limit=50&searchText=maria" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>"

Parámetros de consulta: page, limit, searchText (email, teléfono, documento), sortBy, sortOrder.

Crear un tarjetahabiente

curl -X POST "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "María",
    "lastName": "Ramírez",
    "address": "Calle Principal 123",
    "countryOfBirth": "GT",
    "dateOfBirth": "1990-05-12",
    "maritalStatus": "soltero",
    "gender": "F",
    "phoneNumber": "50255551234",
    "email": "maria@example.com",
    "documentType": "DPI",
    "documentNumber": "2345678901234",
    "cardId": 1
  }'

Todos los campos son obligatorios. Valores de enumeración:

• countryOfBirth — código de país ISO (p. ej. GT).
• maritalStatus — soltero | casado | viudo | divorciado | separado.
• gender — F | M | OTHER.
• documentType — DPI | NIT | PASSPORT | LEGAL_ID | PERSONAL_ID | RESIDENCE_ID.
• dateOfBirth — YYYY-MM-DD.
• cardId — ID numérico de la tarjeta que se asignará al nuevo tarjetahabiente.

La llamada de creación delega en los servicios de orquestador / op-users; el envoltorio de respuesta concreto es el estándar { success, message, data }.

Obtener un tarjetahabiente (detalle)

El detalle del tarjetahabiente se obtiene mediante POST (no GET). El cuerpo es opcional y solo transporta un OTP cuando el operador está sujeto a elevación por OTP (impuesto por el guard de OTP condicional).

curl -X POST "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/{cardholderId}" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>" \
  -H "Content-Type: application/json" \
  -d '{ "otp": "123456" }'

otp es un código numérico de 6 dígitos, requerido solo cuando el usuario posee el permiso de OTP; de lo contrario, omite el cuerpo.

Listar todas las tarjetas de un partner

Lista todas las tarjetas asociadas al partner/cliente.

curl "https://api.ali.app/cms/rest/app/partners/{partnerId}/cards" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>"

Tarjetas de un tarjetahabiente

# Todas las tarjetas (propias + vinculadas)
curl "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/{cardholderId}/cards" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>"

Acciones sobre tarjetas

Activar / bloquear / desbloquear por tarjeta usan PATCH:

# Activar
PATCH /app/partners/{partnerId}/cardholders/{cardholderId}/cards/{cardId}/activate

# Bloquear
PATCH /app/partners/{partnerId}/cardholders/{cardholderId}/cards/{cardId}/block

# Desbloquear
PATCH /app/partners/{partnerId}/cardholders/{cardholderId}/cards/{cardId}/unblock

Bloqueo / desbloqueo masivo por lista de card id (ambos endpoints requieren un OTP de 6 dígitos):

# Bloqueo masivo
curl -X PATCH "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/cards/block" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>" \
  -H "Content-Type: application/json" \
  -d '{ "cardIds": [1, 2, 3], "otp": "123456" }'

# Desbloqueo masivo
curl -X PATCH "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/cards/unblock" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>" \
  -H "Content-Type: application/json" \
  -d '{ "cardIds": [1, 2, 3], "otp": "123456" }'

Operaciones de fondos de tarjeta

amount es un número; observations es opcional.

# Agregar fondos
POST /app/partners/{partnerId}/cardholders/{cardholderId}/cards/funds/add
{ "cardId": 10, "amount": 150.0, "observations": "Monthly allowance" }

# Retirar fondos
POST /app/partners/{partnerId}/cardholders/{cardholderId}/cards/funds/withdraw
{ "cardId": 10, "amount": 25.0 }

# Transferir entre dos tarjetas del MISMO tarjetahabiente
POST /app/partners/{partnerId}/cardholders/{cardholderId}/cards/transfers
{ "fromCardId": 10, "toCardId": 20, "amount": 50.0, "observations": "Balance reallocation" }

Las transferencias mueven fondos entre dos tarjetas que pertenecen al mismo tarjetahabiente; ambas tarjetas deben estar activas.

Movimientos / historial de transacciones por tarjeta

# Listar
GET /app/partners/{partnerId}/cardholders/{cardholderId}/cards/{cardId}/movements?from=2026-03-01&to=2026-03-31

# Movimiento individual
GET /app/partners/{partnerId}/cardholders/{cardholderId}/cards/{cardId}/movements/{transferId}

# Descargar un reporte en PDF (adjunto binario)
GET /app/partners/{partnerId}/cardholders/{cardholderId}/cards/{cardId}/movements/report?from=2026-03-01&to=2026-03-31

El endpoint de reporte es un GET que transmite un PDF binario (Content-Disposition: attachment). Filtra con from / to (y los parámetros de consulta estándar page, limit, sortBy, sortOrder); no hay un campo format — la salida siempre es PDF.

Asociar una tarjeta de terceros

curl -X POST "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/{cardholderId}/cards/association" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "suffix": "4321",
    "alias": "Personal Visa"
  }'

email es el correo del propietario de la tarjeta de terceros y suffix son los últimos dígitos del número de tarjeta.

Lista las tarjetas de terceros ya asociadas a un tarjetahabiente:

curl "https://api.ali.app/cms/rest/app/partners/{partnerId}/cardholders/{cardholderId}/cards/association" \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: Bearer <cms-user-token>"

Consulta Wallet → Tarjetas de terceros para la mitad de tokenización del flujo.