# Casos de uso

Este documento explora aplicaciones y casos de uso del mundo real para implementar pagos seguros con Fluxis API y el protocolo NASPIP, demostrando cómo integrar pagos blockchain en tus aplicaciones usando el flujo de API de comercio compatible.

::::tip Authentication pattern
Todos los ejemplos siguientes asumen que ya has intercambiado tu clave API y secreto por un token Bearer vía `POST /v1/auth/token`. Las rutas protegidas requieren **ambos** `Authorization: Bearer <token>` y `x-fluxis-api-key: <api_key>`. Nunca expongas secretos API en código del lado del cliente.
::::

## Comercio electrónico y retail

### Pagos en tienda online

**Escenario**: Una plataforma de comercio electrónico quiere aceptar pagos con criptomonedas junto con métodos de pago tradicionales.

**Solución Fluxis API**:

```javascript
const API_BASE = "https://api.fluxis.us/v1";
const POS_ID = "YOUR_POINT_OF_SALE_ID";

// 1) Intercambia clave API + secreto por un token de acceso (solo en servidor)
const authRes = await fetch(`${API_BASE}/auth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: process.env.FLUXIS_API_KEY,
    api_secret: process.env.FLUXIS_API_SECRET,
  }),
});
const { data: auth } = await authRes.json();

// 2) Crea una solicitud de pago para un checkout
const prRes = await fetch(`${API_BASE}/pos/${POS_ID}/payment-request`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${auth.token}`,
    "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "299.99",
    unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    reference_id: "order-12345",
  }),
});
const { data: paymentRequest } = await prRes.json();

// 3) Presenta paymentRequest.token al pagador (QR / deep link / checkout alojado)
// Opcional: POST /pos/:posID/payment-request-checkout para una URL de checkout alojado
```

**Beneficios**:

- **🚀 Integración rápida**: Empieza en minutos con Fluxis API
- **🔐 Seguridad empresarial**: Instrucciones de pago NASPIP firmadas (PASETO v4) y verificación de firmas de webhooks
- **🌐 Multired**: Soporte para activos EVM configurados (UAIs) en redes habilitadas como Polygon, Base, Avalanche y Arbitrum
- **📱 Checkout flexible**: Token NASPIP QR, deep links o checkout alojado
- **⚡ Alto rendimiento**: Infraestructura escalable para aplicaciones de producción

### Sistemas de punto de venta (POS)

**Escenario**: Una tienda retail quiere aceptar pagos con criptomonedas en ubicaciones físicas usando un flujo estilo cajero.

**Implementación Fluxis API**:

```javascript
const API_BASE = "https://api.fluxis.us/v1";

class POSSystem {
  constructor(apiKey, apiSecret, posId) {
    this.apiKey = apiKey;
    this.apiSecret = apiSecret;
    this.posId = posId;
    this.accessToken = null;
  }

  async authenticate() {
    const res = await fetch(`${API_BASE}/auth/token`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        api_key: this.apiKey,
        api_secret: this.apiSecret,
      }),
    });
    const { data } = await res.json();
    this.accessToken = data.token;
  }

  authHeaders() {
    return {
      Authorization: `Bearer ${this.accessToken}`,
      "x-fluxis-api-key": this.apiKey,
      "Content-Type": "application/json",
    };
  }

  async createPaymentIntention(amount, coinCode = "USD") {
    const res = await fetch(
      `${API_BASE}/pos/${this.posId}/payment-intention`,
      {
        method: "POST",
        headers: this.authHeaders(),
        body: JSON.stringify({
          amount,
          coin_code: coinCode,
          external_id: `pos-${Date.now()}`,
        }),
      },
    );
    return (await res.json()).data;
  }

  async getPaymentRequest(paymentRequestId) {
    const res = await fetch(
      `${API_BASE}/pos/${this.posId}/payment-request/${paymentRequestId}`,
      { headers: this.authHeaders() },
    );
    return (await res.json()).data;
  }
}

// Uso
const pos = new POSSystem(
  process.env.FLUXIS_API_KEY,
  process.env.FLUXIS_API_SECRET,
  "YOUR_POS_ID",
);
await pos.authenticate();
const intention = await pos.createPaymentIntention(50.0, "USD");
// Muestra el token de intención como QR; haz polling o usa webhooks para actualizaciones de estado
```

## Servicios financieros

### Remesas transfronterizas

**Escenario**: Un servicio de remesas quiere ofrecer transferencias internacionales rápidas y de bajo coste usando stablecoins.

**Implementación Fluxis API**:

```javascript
async function createRemittancePayment({ amount, referenceId, posId }) {
  const auth = await getAccessToken(); // POST /v1/auth/token

  const res = await fetch(
    `https://api.fluxis.us/v1/pos/${posId}/payment-request`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.token}`,
        "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: amount.toString(),
        unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        reference_id: referenceId,
        order: {
          description: "Cross-border remittance",
        },
      }),
    },
  );

  const { data } = await res.json();
  return {
    paymentRequestId: data.id,
    naspipToken: data.token,
    expiration: data.expiration,
  };
}
```

Registra un webhook de cuenta para recibir actualizaciones de estado `completed`, `underpaid` o `overpaid` y ejecuta la transferencia una vez confirmado el pago.

### Integración de pagos DeFi

**Escenario**: Un protocolo DeFi quiere integrar instrucciones de pago seguras para yield farming y provisión de liquidez.

```javascript
async function createPoolDepositPayment({ poolAddress, amount, posId }) {
  const auth = await getAccessToken();

  const res = await fetch(
    `https://api.fluxis.us/v1/pos/${posId}/payment-request`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.token}`,
        "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: amount.toString(),
        unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        reference_id: `pool-${poolAddress.slice(0, 8)}`,
        order: {
          description: `Yield farming deposit — ${poolAddress}`,
        },
      }),
    },
  );

  const { data } = await res.json();
  return { paymentRequest: data, naspipToken: data.token };
}
```

## Gaming y entretenimiento

### Compras dentro del juego

**Escenario**: Un juego móvil quiere aceptar pagos con criptomonedas para objetos del juego y funcionalidades premium.

```javascript
async function createInGamePurchase({ itemId, price, playerId, posId }) {
  const auth = await getAccessToken();

  const res = await fetch(
    `https://api.fluxis.us/v1/pos/${posId}/payment-request`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.token}`,
        "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: price.toString(),
        unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        reference_id: `player-${playerId}-item-${itemId}`,
        order: {
          description: `In-game purchase: ${itemId}`,
        },
      }),
    },
  );

  const { data } = await res.json();

  // Opcional: checkout alojado en lugar del token NASPIP en bruto
  // POST /v1/pos/:posID/payment-request-checkout

  return {
    paymentRequestId: data.id,
    naspipToken: data.token,
    referenceId: data.reference_id,
  };
}

// En webhook `completed` (o polling GET /pos/:posID/payment-request/:id):
// concede el objeto al jugador identificado por reference_id
```

## ¿Por qué elegir Fluxis API para estos casos de uso?

### 🚀 Desarrollo rápido

- **5 minutos hasta el primer pago**: Empieza de inmediato
- **API REST sencilla**: Integración fácil con cualquier stack tecnológico
- **Documentación completa**: Ejemplos y guías claros

### 🔒 Seguridad empresarial

- **Instrucciones de pago firmadas**: Tokens NASPIP con payloads verificables
- **Autenticidad de webhooks**: Firmas HMAC-SHA256 en eventos salientes
- **Credenciales en servidor**: Los secretos API nunca pertenecen a apps cliente

### 📈 Listo para producción

- **Infraestructura de producción**: Diseñada para alta disponibilidad (confirma los términos de SLA con el equipo comercial de Fluxis)
- **CDN global**: Tiempos de respuesta rápidos en todo el mundo
- **Autoescalado**: Gestiona picos de tráfico automáticamente

### 🛠️ Experiencia del desarrollador

- **Playground interactivo de la API**: Prueba endpoints directamente en el navegador
- **Guías de integración**: Onboarding de comercios paso a paso
- **Soporte experto**: Contacta con [support@fluxis.us](mailto:support@fluxis.us) cuando necesites ayuda

## Primeros pasos

¿Listo para implementar cualquiera de estos casos de uso? Empieza con la [Guía de integración de la API](/es/docs/developers/tutorials/api-integration-guide) o explora nuestra [Referencia de la API](/api).

### Próximos pasos

1. **[Regístrate en Fluxis](https://fluxis.us/signup)** - Crea tu cuenta
2. **[Obtén tu clave API](https://fluxis.us/dashboard)** - Genera tu primera clave
3. **[Sigue la Guía de integración de la API](/es/docs/developers/tutorials/api-integration-guide)** - Realiza tu primera llamada a la API
4. **[Primeros pasos](/es/docs/introduction/getting-started)** - Inicio rápido en 6 pasos

---

**¿Listo para transformar tu experiencia de pago?** [Empieza a integrar con Fluxis API](https://fluxis.us/signup) hoy mismo.