Copy page

Conceitos-chave

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).

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:

Code
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) 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

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.

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. Local físico

Configure PoS distintos para cada local físico ou ponto de venda.

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. Serviços de assinatura

PoS dedicado para pagamentos recorrentes de assinatura.

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

Organize pagamentos por departamento usando a estrutura de contas.

Code
{
  "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

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 da API

Todos os endpoints exigem os cabeçalhos Authorization: Bearer <token> 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"