Saltar al contenido principal
Este Quickstart emite 100 tarjetas virtuales en una sola solicitud. Harás una orden masiva asíncrona, harás polling de su estado a medida que se crean las tarjetas y recuperarás los detalles completos de las tarjetas: 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 ve a Prepara tus cuentas y Credenciales de API.
  • Un token con el scope CREATE_VIRTUALCARD.
  • Suficiente saldo disponible para cubrir la orden: 100 tarjetas × el límite de gasto que definas. 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; mezcla configuraciones agregando más entradas en orderItems (p. ej., 80 × 25deunsolousomaˊs20×25 de un solo uso más 20 × 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 las tarjetas. Guarda el orderId; es tu identificador para todo lo que sigue.

Haz polling hasta completar

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 PAN completos, CVVs y fechas de vencimiento en texto plano. Trátala como datos sensibles del tarjetahabiente: solo TLS, nunca la registres en logs, muéstrala únicamente a usuarios autorizados.

Maneja 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 necesitan reintento. Concílialo 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 desde una sola solicitud, con un loop de polling listo para producción tal como está. A continuación:

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 alojados 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.