# Preguntas frecuentes ## Preguntas generales ### ¿Qué es Fluxis? Fluxis es una plataforma de infraestructura de pagos que permite a las empresas aceptar pagos con criptomonedas en múltiples redes blockchain. Proporcionamos una API unificada que simplifica la integración de pagos con activos digitales en tus sistemas existentes, ya sea que gestiones una tienda de comercio electrónico, una aplicación móvil o un terminal físico de punto de venta. ### ¿En qué se diferencia Fluxis de otros procesadores de pagos con cripto? Fluxis utiliza el estándar NASPIP (Native Asset Signed Payment Instructions Protocol), que proporciona: - **Soporte multired** - Acepta stablecoins EVM en redes compatibles (p. ej., Polygon, Base, Avalanche, Arbitrum y redes adicionales según la configuración de tu cuenta) desde una sola integración - **Flexibilidad de activos** - Soporte para múltiples stablecoins y criptomonedas simultáneamente - **Seguridad criptográfica** - Todas las instrucciones de pago están firmadas y son verificables - **Protocolo estandarizado** - Compatible con cualquier billetera conforme a NASPIP Más información en nuestra [Guía de comparación](/es/docs/introduction/comparison). ### ¿Necesito conocimientos de blockchain para integrar Fluxis? No. Fluxis abstrae la complejidad de las interacciones con blockchain. Trabajas con una API REST sencilla: creas solicitudes de pago, monitorizas cambios de estado y recibes notificaciones por webhook. Nuestra API gestiona todas las operaciones específicas de blockchain en segundo plano. ### ¿Qué criptomonedas puedo aceptar? Fluxis admite cualquier token compatible con EVM en redes compatibles. La mayoría de los comercios aceptan stablecoins como USDC y USDT para evitar la volatilidad. Puedes configurar qué activos aceptar a través de las opciones de pago de tu [Point of Sale](/es/docs/key-concepts/point-of-sale). Consulta la lista completa de redes y activos compatibles en nuestra [documentación UAI](/es/docs/key-concepts/uai). ## Primeros pasos ### ¿Cómo me registro como comercio? Sigue nuestra guía de [Registro de comercios](/es/docs/merchant-integration/sign-up). Necesitarás: - Nombre legal del negocio - Número de identificación fiscal - País de registro - Dirección de correo del propietario Tras el envío, nuestro equipo revisa tu solicitud (1-2 días hábiles) y te envía credenciales API tras la aprobación. ### ¿Cuánto tarda el proceso de aprobación? Normalmente 1-2 días hábiles. Verificamos la información de tu negocio para garantizar el cumplimiento de los requisitos KYB (Know Your Business). Recibirás una notificación por correo cuando tu solicitud sea aprobada o si se necesita información adicional. ### ¿Cuáles son los requisitos de integración? Necesitas: - **Servidor backend** - Para almacenar de forma segura las credenciales API y gestionar la autenticación - **Endpoint HTTPS** - Para recibir notificaciones por webhook (recomendado) - **Conocimientos básicos de API REST** - Para realizar solicitudes HTTP a nuestra API Nuestra guía de [Autenticación y configuración](/es/docs/merchant-integration/auth-and-conf) te guía por todo el proceso de configuración. ### ¿Hay un entorno sandbox o de pruebas? Sí. Fluxis proporciona un entorno de **staging** para pruebas de integración antes del lanzamiento a producción. - **Host API staging:** `https://api.stgfluxis.us` - **Host API producción:** `https://api.fluxis.us` Las claves API de staging las emite tu representante de Fluxis (formato: `fxs.stg.`). Usa staging para construir y probar tu integración; las credenciales de producción se habilitan tras la aprobación en staging. Consulta la [Guía de integración de la API](/es/docs/developers/tutorials/api-integration-guide) para detalles de los entornos. ## Puntos de venta ### ¿Qué es un Point of Sale? Un Point of Sale (PoS) es un punto de recogida de pagos dentro de Fluxis. Piensa en él como una caja registradora virtual donde generas solicitudes de pago. Cada PoS puede tener su propia configuración, incluidas las criptomonedas aceptadas y la marca del comercio. **Los webhooks se configuran a nivel de cuenta** (`POST /v1/account/{accountID}/webhook`), no por PoS — consulta [Webhooks](/es/docs/developers/webhooks). Más información en nuestra [Guía de Point of Sale](/es/docs/key-concepts/point-of-sale). ### ¿Cuántos Point of Sales puedo crear? No hay límite en el número de Point of Sales que puedes crear. Muchos comercios crean instancias PoS separadas para: - Diferentes ubicaciones físicas - Diferentes unidades de negocio o departamentos - Diferentes categorías de productos - Entornos de desarrollo, staging y producción ### ¿Puedo actualizar la configuración de mi Point of Sale? Sí. Puedes actualizar en cualquier momento el nombre, las opciones de pago y la información del comercio de tu Point of Sale a través de la API. Usa el endpoint de actualización de Point of Sale en nuestra [Referencia de la API](/api/point-of-sale#update-point-of-sale-payment-options). ### ¿Qué son las opciones de pago? Las opciones de pago son la lista de criptomonedas y redes que acepta tu Point of Sale. Se definen mediante [Unique Asset Identifiers (UAIs)](/es/docs/key-concepts/uai). Por ejemplo: - `npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` - USDC en Polygon - `nerc20_t0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` - USDC en Ethereum Cuando creas una solicitud de pago, los clientes pueden pagar con cualquiera de las opciones de pago configuradas. ## Solicitudes de pago ### ¿Cuánto tiempo permanece activa una solicitud de pago? La expiración depende del flujo de pago: - **Intención de pago (modo cajero):** La intención activa expira **5 minutos** después de su creación. - **Solicitud de pago (después de que el pagador selecciona un activo):** La solicitud suele ser válida durante **8 minutos** desde la asignación (marca de tiempo Unix `expiration` en la respuesta de la API). Si una solicitud expira antes de completar el pago, crea una nueva solicitud de pago o intención de pago. Una vez que el estado es `expired`, la plataforma no sigue emparejando nuevos depósitos on-chain con esa solicitud — anima a los pagadores a completar el pago antes de la expiración y muestra una cuenta regresiva en tu interfaz. ### ¿Qué ocurre si un cliente paga después de la expiración? Los pagos deben llegar a la dirección asignada mientras la solicitud de pago sigue en estado `created` o `processing`. Tras marcar la solicitud como `expired`, crea una nueva solicitud de pago para cualquier intento de pago posterior. ### ¿Puedo crear solicitudes de pago sin un monto fijo? Actualmente, todas las solicitudes de pago requieren un monto específico. El campo amount garantiza la verificación y el seguimiento del estado del pago. Para escenarios de precios variables, calcula el monto en tu aplicación antes de crear la solicitud de pago. ### ¿Qué es un token NASPIP? NASPIP (Native Asset Signed Payment Instructions Protocol) es el token firmado criptográficamente que contiene todas las instrucciones de pago. Cuando creas una solicitud de pago, Fluxis genera un token NASPIP que puedes: - Mostrar como código QR para billeteras móviles - Compartir como enlace de pago para billeteras web - Compartir como deep link o URL de checkout alojado (el soporte de proximidad/NFC varía según la app de billetera) El token incluye la dirección de pago, el monto, el activo, la red y la expiración — todo lo que una billetera necesita para completar el pago. Más información sobre [NASPIP](/es/docs/key-concepts/naspip/introduction). ### ¿Puedo reutilizar una solicitud de pago? No. Cada solicitud de pago es de un solo uso y está vinculada a una transacción específica. Una vez completada, expirada o cancelada, debes crear una nueva solicitud de pago para transacciones posteriores. Esto garantiza la integridad del pago y la contabilidad correcta. ## Monitoreo de pagos ### ¿Cómo sé cuándo se completa un pago? Hay dos enfoques: 1. **Webhooks (Recomendado)** - Configura una URL de webhook para recibir notificaciones en tiempo real cuando cambie el estado del pago. Consulta [Webhooks](/es/docs/developers/webhooks). 2. **Polling** - Comprueba periódicamente el estado de la solicitud de pago usando el endpoint GET. Consulta nuestra [Referencia de la API](/api/point-of-sale#get-payment-request). Para sistemas de producción, recomendamos encarecidamente implementar webhooks para notificaciones instantáneas. ### ¿Cuál es la diferencia entre 'processing' y 'completed'? - **`processing`** - Pago detectado on-chain; en espera de comprobaciones de finalidad - **`completed`** - El monto del pago coincide con la solicitud y se cumplen los requisitos de finalidad - **`confirmed`** - Se ha registrado una transación confirmada en el ledger para el pago Espera a `completed` (o tu estado terminal acordado) antes de cumplir pedidos. Usa webhooks en lugar de polling cuando sea posible. ### ¿Qué ocurre si un cliente paga de menos o de más? Las solicitudes de pago pueden resultar en tres estados de caso límite: - **`underpaid`** - El cliente pagó menos del monto solicitado - **`overpaid`** - El cliente pagó más del monto solicitado - **`failed`** - Error inesperado durante el procesamiento Para pagos `underpaid` o `overpaid`, usa la [API de reembolsos](/api/refunds) (`POST /v1/refunds/payment-request/{paymentRequestID}`) para devolver fondos a una dirección on-chain especificada. El monto es opcional — para pagos overpaid, omitir el monto reembolsa el excedente por defecto. Contacta con [support@fluxis.us](mailto:support@fluxis.us) si necesitas ayuda para elegir la resolución correcta según tus reglas de negocio. Consulta [Casos límite del flujo de pago](/es/docs/payment-flows/edge-cases), la [Guía de integración de la API](/es/docs/developers/tutorials/api-integration-guide) y [Webhooks](/es/docs/developers/webhooks). ### ¿Cuántas confirmaciones de blockchain espera Fluxis? Los requisitos de finalidad son específicos de la red y se configuran por despliegue. Fluxis espera hasta que se cumple el umbral de finalidad configurado antes de tratar un pago como final (normalmente reflejado como estado `completed` o `confirmed`). El monitoreo de bloques en producción se ejecuta actualmente en **Polygon**, **Base**, **Avalanche** y **Arbitrum**. Otras redes pueden aparecer en las opciones de pago (UAIs) pero no todas se monitorizan activamente en cada entorno — confirma las redes compatibles con tu representante de Fluxis. No codifiques en duro los recuentos de confirmación en tu integración; confía en el estado de la solicitud de pago y los webhooks. ## Seguridad y autenticación ### ¿Cómo mantengo seguras mis credenciales API? Sigue estas buenas prácticas: - **Nunca subas credenciales** a sistemas de control de versiones - **Usa variables de entorno** o un gestor de secretos (AWS Secrets Manager, HashiCorp Vault) - **Rota credenciales regularmente** para mayor seguridad - **Limita el acceso** solo a miembros del equipo que lo necesiten - **Monitoriza el uso** en busca de actividad sospechosa Consulta nuestra guía de [Buenas prácticas de seguridad](/es/docs/security/best-practices). ### ¿Cuánto tiempo son válidos los tokens de acceso? Los tokens de acceso expiran después de **1 hora**. Almacena en caché y reutiliza tokens hasta que expiren en lugar de solicitar un token nuevo en cada llamada a la API. Implementa la renovación automática de tokens en tu aplicación para mantener un servicio ininterrumpido. ### ¿Puedo revocar credenciales API? Sí. Los administradores de la organización pueden deshabilitar claves API desde el panel de Fluxis. Las claves deshabilitadas ya no pueden obtener tokens de acceso. Si sospechas que una credencial está comprometida, deshabilítala de inmediato y solicita un reemplazo a tu representante de Fluxis. ### ¿Cómo verifico la autenticidad de los webhooks? Cuando creas un webhook de cuenta, Fluxis devuelve un secreto **una sola vez**. Cada entrega incluye los headers `X-Request-Signature` y `X-Request-Timestamp`. Verifica la firma HMAC-SHA256 sobre el cuerpo JSON completo antes de procesar el payload. Consulta [Verificación de firmas de webhooks](/es/docs/developers/webhook-signature-verification) para el algoritmo, ejemplo resuelto y endpoint de prueba. El registro y los tipos de evento se cubren en [Webhooks](/es/docs/developers/webhooks). ## Facturación y precios ### ¿Cuánto cuesta Fluxis? La información de precios y planes está disponible contactando con nuestro equipo comercial en [sales@fluxis.us](mailto:sales@fluxis.us). Ofrecemos precios flexibles según el volumen de transacciones, funcionalidades y requisitos de soporte. ### ¿Hay tarifas por transacción? Las tarifas por transacción varían según el plan y el volumen. Contacta con [sales@fluxis.us](mailto:sales@fluxis.us) para información detallada de precios adaptada a las necesidades de tu negocio. ### ¿Pago las tarifas de red blockchain? Los clientes pagan las tarifas de red blockchain (gas) al enviar su pago. Fluxis gestiona la consolidación y la tesorería, lo que puede tener costes asociados según tu plan. ## Preguntas técnicas ### ¿Qué límites de tasa tiene la API? Los límites de tasa están diseñados para ser generosos en uso normal mientras previenen abusos. Los límites específicos dependen de tu plan. Si encuentras errores de límite de tasa, implementa backoff exponencial y contacta con soporte para discutir el aumento de tus límites. ### ¿Qué lenguajes de programación son compatibles? Fluxis es una API REST que funciona con cualquier lenguaje de programación capaz de realizar solicitudes HTTP. Los SDK oficiales para Node.js/TypeScript, Python y Go están **planificados** pero aún no publicados. Integra vía HTTP usando la [Guía de integración de la API](/es/docs/developers/tutorials/api-integration-guide) y la [Referencia de la API](/api). Únete a la lista de acceso anticipado en [Documentación de SDK](/es/docs/developers/sdk) si quieres recibir notificaciones sobre SDK. ### ¿Puedo usar Fluxis en una app móvil? Sí. Sin embargo, **nunca** almacenes credenciales API en código del lado del cliente (apps móviles, navegadores web). En su lugar: 1. Tu app móvil se comunica con tu servidor backend 2. Tu servidor backend se autentica de forma segura con Fluxis 3. Tu backend crea solicitudes de pago y las devuelve a tu app 4. Tu app muestra el token NASPIP (como código QR) al cliente Esta arquitectura mantiene las credenciales seguras mientras permite la integración móvil. ### ¿Fluxis admite webhooks? Sí. Los webhooks son la forma recomendada de recibir actualizaciones de estado de pago en tiempo real. Registra endpoints de webhook a nivel de **cuenta** vía `POST /v1/account/{accountID}/webhook`. Fluxis enviará POST con cambios de estado de pago a tu endpoint cuando ocurran eventos coincidentes para esa cuenta. Consulta [Webhooks](/es/docs/developers/webhooks) y la [Guía de integración de la API](/es/docs/developers/tutorials/api-integration-guide). Más información en nuestra [Documentación de webhooks](/es/docs/developers/webhooks). ### ¿Qué métodos HTTP usa la API? La API de Fluxis sigue convenciones RESTful: - **GET** - Recuperar recursos (solicitudes de pago, Point of Sales, etc.) - **POST** - Crear nuevos recursos (solicitudes de pago, Point of Sales, etc.) - **PUT** - Actualizar recursos existentes (configuración de Point of Sale, etc.) - **DELETE** - Eliminar recursos (Point of Sales, etc.) Consulta nuestra [Referencia de la API](/api) para documentación completa de endpoints. ## Solución de problemas ### Recibo errores de autenticación. ¿Qué debo comprobar? Problemas comunes de autenticación: 1. **Credenciales inválidas** - Verifica tu clave API y secreto; obtén un token nuevo vía `POST /v1/auth/token` 2. **Token expirado** - Los tokens de acceso expiran después de 1 hora; solicita uno nuevo 3. **Headers faltantes** - Las rutas protegidas requieren **ambos** `Authorization: Bearer ` y `x-fluxis-api-key: ` 4. **Entorno incorrecto** - Usa staging (`api.stgfluxis.us` + claves `fxs.stg.*`) vs producción (`api.fluxis.us`) de forma consistente Prueba tu autenticación en nuestro [API Playground - Authentication](/api/authentication). ### La creación de solicitudes de pago falla. ¿Por qué? Causas comunes: - **ID de Point of Sale inválido** - Verifica que el PoS existe y pertenece a tu organización - **UAI inválido** - Comprueba que el Unique Asset ID tiene el formato correcto - **Monto inválido** - El monto debe ser una cadena decimal positiva (p. ej., "49.99") - **Token expirado** - Renueva tu token de autenticación Revisa el mensaje de error en la respuesta de la API para detalles específicos. ### El cliente pagó pero el estado no se actualiza. ¿Qué ocurre? Comprueba estos escenarios: - **Dirección incorrecta** - El cliente puede haber enviado el pago a una dirección incorrecta - **Red incorrecta** - Pago enviado en una red distinta a la especificada - **Activo incorrecto** - Pago enviado con un token distinto al solicitado - **Confirmación pendiente** - La transacción aún espera confirmaciones de blockchain - **Congestión de red** - La red blockchain puede estar experimentando retrasos Pide al cliente su hash de transacción y verifica en un explorador de blockchain. ### No se reciben webhooks. ¿Cómo depuro? Pasos de solución de problemas: 1. **Confirma el registro del webhook de cuenta** - Usa `POST /v1/account/{accountID}/webhook` (no la configuración del PoS) 2. **Verifica que la URL es pública** - Prueba acceder a tu endpoint de webhook externamente 3. **Comprueba el certificado SSL** - Asegura un certificado HTTPS válido 4. **Revisa los logs del servidor** - Busca solicitudes entrantes de Fluxis 5. **Envía una entrega de prueba** - `POST /v1/account/{accountID}/webhook/{webhookID}/test` 6. **Verifica que no hay bloqueos de firewall** - Asegura que las IPs de Fluxis no estén bloqueadas 7. **Comprueba la respuesta del endpoint** - El handler de webhook debe devolver código de estado 2xx Si las entregas llegan pero tu handler las rechaza, consulta [Verificación de firmas de webhooks](/es/docs/developers/webhook-signature-verification) para JSON canónico y solución de problemas HMAC. Contacta con soporte si los problemas persisten tras estas comprobaciones. ## Soporte y recursos ### ¿Cómo contacto con soporte? - **Correo**: [support@fluxis.us](mailto:support@fluxis.us) - **Tiempo de respuesta**: En un plazo de 24 horas en días hábiles - **Para problemas urgentes**: Incluye "URGENT" en el asunto del correo ### ¿Dónde encuentro ejemplos de código? - **API Playground**: Ejemplos interactivos para todos los endpoints en [/api](/api) - **Tutoriales**: Guías paso a paso en nuestra [sección de desarrolladores](/es/docs/developers/tutorials/payment-request) - **Documentación de SDK**: Ejemplos específicos por lenguaje en nuestra [documentación de SDK](/es/docs/developers/sdk) ### ¿Hay una comunidad de desarrolladores? Estamos construyendo nuestros recursos de comunidad de desarrolladores. Mantente atento a: - Canal Discord/Slack para desarrolladores - Discusiones en GitHub - Foro comunitario - Office hours regulares Suscríbete a nuestro boletín o sigue nuestro blog para anuncios. ### ¿Dónde puedo reportar bugs o solicitar funcionalidades? Para reportes de bugs o solicitudes de funcionalidades: - **Correo**: [support@fluxis.us](mailto:support@fluxis.us) - **Incluye**: Descripción detallada, pasos para reproducir, comportamiento esperado vs actual - **Solicitudes de funcionalidades**: Incluye caso de uso y justificación de negocio Consulta nuestra [Hoja de ruta](/es/docs/roadmap) para ver funcionalidades próximas. --- ## ¿Aún tienes preguntas? Si tu pregunta no está respondida aquí, contáctanos en [support@fluxis.us](mailto:support@fluxis.us). ¡Estamos aquí para ayudarte!