# Pontos de venda ## O que são pontos de venda? Um **Point of Sale** (PoS) é uma entidade fundamental na plataforma Fluxis que funciona como ponto de recebimento de pagamentos para sua organização. Pense nele como um caixa digital ou terminal de pagamento que permite gerar e gerenciar solicitações de pagamento (mais detalhes na seção [Solicitações de pagamento](/pt/docs/key-concepts/payment-request)). Cada PoS atua como um canal de pagamento distinto, permitindo que você: - Crie solicitações de pagamento para clientes - Configure métodos de pagamento aceitos (criptomoedas e redes blockchain) - Rastreie e monitore pagamentos recebidos - Organize transações por local, departamento ou unidade de negócio ## Conceitos-chave ### Tipos de ponto de venda | Tipo | Caso de uso | Fluxo de pagamento | | ---- | -------- | -------------- | | **`online_fixed`** | E-commerce, integrações de apps | Criar solicitações de pagamento via `POST /v1/pos/{posID}/payment-request` ou checkout hospedado via `POST /v1/pos/{posID}/payment-request-checkout` | | **`cashier_fixed`** | Caixa física com valor definido pelo comerciante | O comerciante cria uma intenção de pagamento; o cliente escaneia o QR | | **`cashier_open`** | Valor informado pelo cliente (ex.: doação/copo de gorjetas) | O cliente escaneia o QR e informa o valor no checkout | ### Estrutura de organização e conta Os PoS pertencem a uma **Organization** (sua entidade comercial) e podem ser associados opcionalmente a uma **Account** específica para organização mais granular: ```mermaid graph TD A[Organization] --> B[PoS #1] A --> C[PoS #2] A --> D[Account] D --> E[PoS #3] D --> F[PoS #4] ``` Essa estrutura hierárquica permite: - Separar canais de pagamento por departamento, local ou finalidade - Manter configurações de pagamento distintas para diferentes casos de uso - Rastrear e reportar pagamentos em múltiplos níveis ### Configuração de opções de pagamento Cada PoS pode ser configurado com **payment options** específicas, que são [Unique Asset IDs (UAIs)](/pt/docs/key-concepts/uai) representando as criptomoedas e redes que você aceita:
Network Token Example UAI
Polygon USDC npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
Polygon USDT npolygon_t0xc2132D05D31c914a87C6611C10748AEb04B58e8F
Ethereum USDC nerc20_t0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
Arbitrum USDC narbitrum_t0xaf88d065e77c8cC2239327C5EDb3A432268e5831
::::tip **Flexibilidade multiativo**: Ao configurar múltiplas opções de pagamento, você permite que os clientes paguem com a criptomoeda e rede preferidas, melhorando taxas de conversão e experiência do usuário. Depois você pode configurar um conjunto diferente de UAIs para suas [liquidações de PoS](/pt/docs/key-concepts/settlements-and-consolidation) ::::: ## Propriedades do ponto de venda | Property | Type | Description | Required | | --------------------- | --------- | ------------------------------------------------------- | -------------- | | **`id`** | UUID | Identificador único do Point of Sale | Auto-generated | | **`name`** | string | Nome legível para identificação | Yes | | **`type`** | string | Modo PoS: `online_fixed`, `cashier_fixed` ou `cashier_open` | Yes | | **`organization_id`** | UUID | Identificador da organização pai | Auto-generated | | **`account_id`** | UUID | Conta proprietária deste PoS (obrigatória ao criar como organização) | Yes | | **`config`** | object | Objeto de configuração (veja abaixo) | No | | **`created_at`** | timestamp | Timestamp de criação | Auto-generated | | **`updated_at`** | timestamp | Timestamp da última modificação | Auto-generated | ### Objeto de configuração (`config`) | Property | Type | Description | | ----------------------- | -------- | ------------------------------------------------ | | **`payment_options`** | string[] | UAIs aceitos; padrão da plataforma se omitido | | **`reference_currency`**| string | Moeda de referência para valores (`USD` ou `ARS`) | | **`merchant`** | object | Nome e descrição do comerciante exibidos ao pagador | ## Casos de uso comuns ### 1. Checkout de e-commerce Crie um PoS para sua loja online processar pagamentos de clientes no 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. Local físico Configure PoS distintos para cada local físico ou ponto de venda. ```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. Serviços de assinatura PoS dedicado para pagamentos recorrentes de assinatura. ```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 Organize pagamentos por departamento usando a estrutura de contas. ```json { "name": "Marketing Department Events", "type": "online_fixed", "account_id": "550e8400-e29b-41d4-a716-446655440000", "reference_currency": "USD", "payment_options": ["npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"] } ``` ## Fluxo de trabalho Depois que um PoS é criado, ele se torna a base para aceitar pagamentos: 1. **Criar PoS** → Configure seu ponto de pagamento com os ativos aceitos 2. **Gerar solicitação de pagamento** → Crie solicitações de pagamento individuais vinculadas a este PoS 3. **Pagamento do cliente** → O cliente paga usando qualquer uma das opções de pagamento configuradas 4. **Confirmação de pagamento** → A Fluxis detecta e confirma o pagamento on-chain 5. **Notificação webhook** → Seu sistema recebe atualizações de status de pagamento em tempo real via [webhooks em nível de conta](/pt/docs/developers/webhooks) ::::note **Notificação webhook**: Você também pode consultar a API Fluxis para obter o status de uma solicitação de pagamento. ::::: ```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 da API Todos os endpoints exigem os cabeçalhos `Authorization: Bearer ` e `x-fluxis-api-key`. | Method | Endpoint | Description | | ------ | -------- | ----------- | | `GET` | `/v1/pos?page=1&page_size=20` | Listar PoS (requer `page` e `page_size`) | | `POST` | `/v1/pos` | Criar PoS | | `GET` | `/v1/pos/{posID}` | Obter PoS por ID | | `PUT` | `/v1/pos/{posID}` | Atualizar nome e config do PoS | | `DELETE` | `/v1/pos/{posID}` | Excluir PoS | | `POST` | `/v1/pos/{posID}/payment-request` | Criar solicitação de pagamento de ativo fixo (apenas `online_fixed`) | | `POST` | `/v1/pos/{posID}/payment-request-checkout` | Criar checkout hospedado multiativo (apenas `online_fixed`) | | `GET` | `/v1/pos/{posID}/payment-request/{paymentRequestID}` | Obter status da solicitação de pagamento | | `GET` | `/v1/pos/{posID}/qr` | Obter token NASPIP QR estático (tipos `cashier_*`) | | `POST` | `/v1/pos/{posID}/payment-intention` | Criar intenção de pagamento de caixa | | `GET` | `/v1/pos/{posID}/payment-intention` | Obter intenção de pagamento ativa | | `POST` | `/v1/pos/{posID}/payment-intention/close` | Fechar intenção de pagamento ativa | ## Boas práticas ### Convenção de nomenclatura Use nomes claros e descritivos que reflitam a finalidade ou o local: - ✅ "Downtown Store - Main Register" - ✅ "Website Checkout - Production" - ✅ "Mobile App - In-App Purchases" - ❌ "PoS 1" - ❌ "Test123" ::::note Não se preocupe, você pode atualizar a configuração do seu PoS a qualquer momento. :::::