Skip to main content
Este Quickstart emite 100 tarjetas virtuales en una sola solicitud. Realizarás una orden masiva asíncrona, harás polling de su estado mientras se crean las tarjetas y recuperarás los detalles completos de las tarjetas; es el mismo patrón ya sea que emitas 10 tarjetas o 10,000.
Requisitos previos
  • Una cuenta de Fluz con una aplicación de staging — Pasos 1–2 de cualquier quickstart, o consulta Prepara tus cuentas y Credenciales de la API.
  • Un token con el scope CREATE_VIRTUALCARD.
  • Suficiente saldo disponible para cubrir la orden — 100 tarjetas × el límite de gasto que establezcas. Cada mutación necesita una idempotencyKey única — consulta Idempotencia.

​
El flujo completo

Realiza la orden masiva

Una llamada a createVirtualCardBulkOrder crea las 100 tarjetas. Cada elemento en orderItems es una configuración de tarjeta con una quantity — aquí, 100 tarjetas de desembolso de un solo uso idénticas:
El offerId aplica a todas las tarjetas de la orden; combina configuraciones agregando más entradas en orderItems (p. ej., 20 cant. de 25deunsolouso+80cant.de25 de un solo uso + 80 cant. de 100 mensuales). lockCardNextUse: true hace que cada tarjeta se autodestruya después de su primer cargo — el patrón estándar de desembolso.
Las órdenes masivas son asíncronas — la respuesta es un orderId y PENDING, no tarjetas. Guarda el orderId; es tu identificador para todo lo que sigue.

Haz polling de la orden hasta completarla

Sigue el progreso con getVirtualCardBulkOrderStatus. Las tarjetas se van poblando de forma incremental mientras la orden está PENDING:
Haz polling con backoff hasta que orderStatus sea COMPLETED (o FAILED) — mientras esté pendiente, successfulCardCreations sube hacia totalCards y virtualCards se va llenando.
La respuesta contiene PANs, CVVs y fechas de vencimiento completas en texto plano. Trátala como datos sensibles del titular de la tarjeta: solo TLS, nunca la registres en logs, muéstrala solo a usuarios autorizados.

Gestiona fallas parciales

Una orden masiva puede tener éxito parcial: successfulCardCreations: 98, failedCardCreations: 2 en una orden completada significa 98 tarjetas reales y utilizables y 2 que deben reintentarse. Reconcilia comparando los conteos con totalCards, luego vuelve a emitir solo la diferencia — con una nueva idempotencyKey, ya que es una nueva orden:
Las fallas persistentes usualmente se deben a límites del programa o a fondos — revisa Códigos de error de tarjeta virtual y tu saldo disponible.

​
Listo 🎉

Cien tarjetas configuradas con una sola solicitud, con un bucle de polling listo para producción. Siguiente:

Obtener transacciones de tarjetas virtuales

Monitorea el gasto en todo el lote — hasta 10 tarjetas por consulta, o a nivel de cuenta por fecha.

Enviar tarjetas a destinatarios

¿Distribuyes a personas fuera de tu organización? Los enlaces de canje hospedados se encargan del onboarding por ti.
¿Quieres saber más? Contáctanos en support@fluz.app para hablar con nuestros expertos o solicitar una demo.