# 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](/es/docs/key-concepts/payment-request)). 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: ```mermaid 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)](/es/docs/key-concepts/uai) 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
::::tip **Flexibilidad multiactivo**: Al configurar múltiples opciones de pago, permite que los clientes paguen con su criptomoneda y red preferidas, mejorando las tasas de conversión y la experiencia de usuario. Más adelante puede configurar un conjunto diferente de UAIs para sus [liquidaciones de PoS](/es/docs/key-concepts/settlements-and-consolidation) ::::: ## 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. ```json 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. ```json 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. ```json 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. ```json { "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](/es/docs/developers/webhooks) ::::note **Notificación webhook**: También puede consultar la API de Fluxis para obtener el estado de una solicitud de pago. ::::: ```mermaid 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 ` 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" ::::note No se preocupe, puede actualizar la configuración de su PoS en cualquier momento. :::::