Environments

The FluxiQ NPC API is available in three distinct environments, each with specific characteristics for different phases of the development cycle.

Overview

Environment	Base URL	API Key	Description
Local	http://localhost:4000/api/v1/central	pk_test_*	Development with simulator
Sandbox	https://sandbox.pixconnect.com.br/api/v1/central	pk_test_*	Testing and staging
Production	https://api.pixconnect.com.br/api/v1/central	pk_live_*	Real production environment

Local Environment

The local environment allows you to develop and test your integration using the Nuclea Simulator, which simulates all Nuclea infrastructure services without external dependencies.

Requirements

Requirement	Specification
Docker	Version 20.10 or higher
Docker Compose	Version 2.0 or higher
RAM	Minimum 4GB available
Ports	4000-4010 available
System	Linux, macOS or Windows (WSL2)

Installation

Clone the repository and start the development environment:

# Clone the repository
git clone https://github.com/playersbet/pixconnect-nuclea.git
cd pixconnect-nuclea

# Start all services
docker-compose up -d

# Verify services are running
docker-compose ps

Available Services

The local environment runs the following services:

Service	Port	URL	Description
Backend API	4000	http://localhost:4000	Main FluxiQ NPC API
PCR Simulator	4001	http://localhost:4001	Simulates the Centralized Receivables Platform
Webhook Receiver	4002	http://localhost:4002	Receives webhooks for testing
FTP Server	4003	ftp://localhost:4003	Simulates Nuclea FTP for ACMP615 files
Orchestrator	4005	http://localhost:4005	Orchestrates test scenarios
Control Panel	4010	http://localhost:4010	Simulator web interface

Test Scenarios

The Nuclea Simulator allows simulating various test scenarios through the Orchestrator:

Simulate Boleto Payment

# Simulates payment of a specific boleto
curl -X POST "http://localhost:4005/scenarios/payment" \
  -H "Content-Type: application/json" \
  -d '{
    "boleto_id": "boleto-uuid",
    "valor_pago": 15000,
    "data_pagamento": "2026-02-03"
  }'

Trigger Settlement Cycle

# Manually triggers a settlement cycle
curl -X POST "http://localhost:4005/scenarios/settlement" \
  -H "Content-Type: application/json" \
  -d '{
    "cycle_type": "morning",
    "boleto_ids": ["uuid-1", "uuid-2"]
  }'

Simulate PCR Error

# Simulates a communication failure with PCR
curl -X POST "http://localhost:4005/scenarios/pcr-error" \
  -H "Content-Type: application/json" \
  -d '{
    "error_type": "timeout",
    "duration_seconds": 30
  }'

Control Panel

Access http://localhost:4010 to view:

• Status of all services
• Boletos registered in the simulator
• History of simulated payments
• PCR/FTP communication logs
• Manual triggers for test scenarios

Local Development

The local environment is ideal for development and debugging. Use it to test new features before validating in Sandbox.

Sandbox Environment

Sandbox is a staging environment that replicates production behavior, but with test data and no real financial impact.

Characteristics

• Isolated data: Boletos and transactions are independent from production
• Same API: Endpoints identical to production environment
• Real webhooks: Notifications sent to your test URL
• Scheduled cycles: Simulated settlement at the same times (08:30 and 16:30)
• Free: Requests do not incur charges

Limitations

Resource	Limitation
Requests per minute	100 RPM
Active boletos	Maximum 1,000 simultaneous
Data retention	30 days
Maximum boleto value	R$ 10,000.00 (1,000,000 cents)
Webhooks	Maximum 3 retries

Test Data

In Sandbox, use the following data for testing:

{
  "pagador": {
    "nome": "Sandbox Test User",
    "documento": "00000000000",
    "tipo_documento": "cpf"
  },
  "valor": 15000,
  "vencimento": "2026-03-15"
}

Fictitious Data

Never use real customer data in the Sandbox environment. Use only fictitious data for testing.

Sandbox Access

1. Request sandbox credentials through the FluxiQ Portal
2. Receive your API Key with prefix pk_test_
3. Configure your application to use the Sandbox URL
4. Start testing!

Production Environment

The production environment processes real financial transactions and is connected to the official Nuclea infrastructure.

Characteristics

• Real transactions: Boletos officially registered in PCR
• High availability: 99.9% SLA
• Security: mTLS connection with Nuclea certificates
• Monitoring: Real-time alerts and metrics
• Support: Priority assistance

Pre-Production Checklist

Before migrating to production, make sure to complete all items:

Integration

• [ ] Complete testing in Sandbox environment
• [ ] Handling of all error codes
• [ ] Implementation of retries with exponential backoff
• [ ] HMAC signature validation for webhooks

Security

• [ ] Production API Key stored securely
• [ ] HTTPS required for all communications
• [ ] Logs without exposed sensitive data
• [ ] Webhook endpoint configured with HTTPS

Operational

• [ ] Error monitoring configured
• [ ] Alerts for integration failures
• [ ] Key rotation process documented
• [ ] Technical support contact defined

Compliance

• [ ] Privacy policy updated
• [ ] Terms of use reviewed
• [ ] LGPD compliance verified

Request Access

To obtain access to the production environment:

1. Complete staging in Sandbox
2. Fill out the production form on the FluxiQ Portal
3. Wait for team review (up to 5 business days)
4. Receive your production API Key (pk_live_*)
5. Configure the production webhook
6. Start operating!

Critical Environment

The production environment processes real financial transactions. Test thoroughly in Sandbox before migrating.

Environment Comparison

Characteristic	Local	Sandbox	Production
Data	Simulated	Test	Real
Nuclea PCR	Simulator	Staging	Production
Availability	Local dev	99%	99.9%
Rate Limit	Unlimited	100 RPM	1000 RPM
Webhooks	localhost	Public URLs	Public URLs + HTTPS
Support	Documentation	Email	Priority
Cost	Free	Free	Per transaction

Next Steps

• Authentication - Configure your API Key
• Create Boleto - Register your first boleto
• Webhooks - Receive real-time notifications