Copy page

Conceptos clave

Puntos de venta

¿Qué son los puntos de venta?

Un Point of Sale (PoS) es una entidad fundamental en la plataforma Fluxis que actúa como punto de recolección de pagos para su organización. Piense en él como una caja registradora digital o terminal de pago que le permite generar y gestionar solicitudes de pago (más detalles en la sección Solicitudes de pago).

Cada PoS actúa como un canal de pago distinto, lo que le permite:

• Crear solicitudes de pago para clientes
• Configurar métodos de pago aceptados (criptomonedas y redes blockchain)
• Rastrear y monitorear pagos entrantes
• Organizar transacciones por ubicación, departamento o unidad de negocio

Conceptos clave

Tipos de punto de venta

Tipo	Caso de uso	Flujo de pago
online_fixed	E-commerce, integraciones de apps	Crear solicitudes de pago vía POST /v1/pos/{posID}/payment-request o checkout alojado vía POST /v1/pos/{posID}/payment-request-checkout
cashier_fixed	Caja física con importe fijado por el comerciante	El comerciante crea una intención de pago; el cliente escanea el QR
cashier_open	Importe ingresado por el cliente (p. ej. donación/bote de propinas)	El cliente escanea el QR e ingresa el importe en el checkout

Estructura de organización y cuenta

Los PoS pertenecen a una Organization (su entidad comercial) y pueden asociarse opcionalmente a una Account específica para una organización más granular:

Code
graph TD
    A[Organization] --> B[PoS #1]
    A --> C[PoS #2]
    A --> D[Account]
    D --> E[PoS #3]
    D --> F[PoS #4]

Esta estructura jerárquica le permite:

• Separar canales de pago por departamento, ubicación o propósito
• Mantener configuraciones de pago distintas para diferentes casos de uso
• Rastrear e informar pagos en múltiples niveles

Configuración de opciones de pago

Cada PoS puede configurarse con payment options específicas, que son Unique Asset IDs (UAIs) que representan las criptomonedas y redes que acepta:

Network	Token	Example UAI
Polygon	USDC	npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
Polygon	USDT	npolygon_t0xc2132D05D31c914a87C6611C10748AEb04B58e8F
Ethereum	USDC	nerc20_t0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
Arbitrum	USDC	narbitrum_t0xaf88d065e77c8cC2239327C5EDb3A432268e5831

Propiedades del punto de venta

Property	Type	Description	Required
id	UUID	Identificador único del Point of Sale	Auto-generated
name	string	Nombre legible para identificación	Yes
type	string	Modo PoS: online_fixed, cashier_fixed o cashier_open	Yes
organization_id	UUID	Identificador de la organización padre	Auto-generated
account_id	UUID	Cuenta propietaria de este PoS (requerida al crear como organización)	Yes
config	object	Objeto de configuración (ver abajo)	No
created_at	timestamp	Marca de tiempo de creación	Auto-generated
updated_at	timestamp	Marca de tiempo de última modificación	Auto-generated

Objeto de configuración (config)

Property	Type	Description
payment_options	string[]	UAIs aceptados; valor predeterminado de la plataforma si se omite
reference_currency	string	Moneda de referencia para importes (USD o ARS)
merchant	object	Nombre y descripción del comerciante mostrados al pagador

Casos de uso comunes

1. Checkout de e-commerce

Cree un PoS para su tienda online para procesar pagos de clientes en el checkout.

Code
POST /v1/pos
{
  "name": "Main Store Checkout",
  "type": "online_fixed",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_currency": "USD",
  "payment_options": [
    "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    "npolygon_t0xc2132D05D31c914a87C6611C10748AEb04B58e8F"
  ]
}

2. Ubicación física

Configure PoS distintos para cada ubicación física o punto de venta.

Code
POST /v1/pos
{
  "name": "Manhattan Store - 5th Avenue",
  "type": "cashier_fixed",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_currency": "USD",
  "payment_options": ["npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"]
}

3. Servicios de suscripción

PoS dedicado para pagos recurrentes de suscripción.

Code
POST /v1/pos
{
  "name": "Premium Subscriptions",
  "type": "online_fixed",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_currency": "USD",
  "payment_options": [
    "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    "nerc20_t0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  ]
}

4. Por departamento

Organice pagos por departamento usando la estructura de cuentas.

Code
{
  "name": "Marketing Department Events",
  "type": "online_fixed",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_currency": "USD",
  "payment_options": ["npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"]
}

Flujo de trabajo

Una vez creado un PoS, se convierte en la base para aceptar pagos:

1. Crear PoS → Configure su punto de pago con los activos aceptados
2. Generar solicitud de pago → Cree solicitudes de pago individuales vinculadas a este PoS
3. Pago del cliente → El cliente paga usando cualquiera de las opciones de pago configuradas
4. Confirmación de pago → Fluxis detecta y confirma el pago on-chain
5. Notificación webhook → Su sistema recibe actualizaciones de estado de pago en tiempo real vía webhooks a nivel de cuenta

Code
sequenceDiagram
    participant M as Merchant
    participant F as Fluxis API
    participant B as Blockchain
    participant C as Customer

    M->>F: Create PoS
    F-->>M: PoS ID
    M->>F: Create Payment Request (via PoS)
    F-->>M: Payment Request + NASPIP Token
    M->>C: Display Payment Request
    C->>B: Send Payment
    B->>F: Payment Detected
    F->>M: Webhook: Payment Confirmed

Endpoints de la API

Todos los endpoints requieren los encabezados Authorization: Bearer <token> y x-fluxis-api-key.

Method	Endpoint	Description
GET	/v1/pos?page=1&page_size=20	Listar PoS (requiere page y page_size)
POST	/v1/pos	Crear PoS
GET	/v1/pos/{posID}	Obtener PoS por ID
PUT	/v1/pos/{posID}	Actualizar nombre y config del PoS
DELETE	/v1/pos/{posID}	Eliminar PoS
POST	/v1/pos/{posID}/payment-request	Crear solicitud de pago de activo fijo (solo online_fixed)
POST	/v1/pos/{posID}/payment-request-checkout	Crear checkout alojado multiactivo (solo online_fixed)
GET	/v1/pos/{posID}/payment-request/{paymentRequestID}	Obtener estado de solicitud de pago
GET	/v1/pos/{posID}/qr	Obtener token NASPIP QR estático (tipos cashier_*)
POST	/v1/pos/{posID}/payment-intention	Crear intención de pago de caja
GET	/v1/pos/{posID}/payment-intention	Obtener intención de pago activa
POST	/v1/pos/{posID}/payment-intention/close	Cerrar intención de pago activa

Buenas prácticas

Convención de nombres

Use nombres claros y descriptivos que reflejen el propósito o la ubicación:

• ✅ "Downtown Store - Main Register"
• ✅ "Website Checkout - Production"
• ✅ "Mobile App - In-App Purchases"
• ❌ "PoS 1"
• ❌ "Test123"