Ambientes

A API FluxiQ NPC esta disponivel em tres ambientes distintos, cada um com caracteristicas especificas para diferentes fases do ciclo de desenvolvimento.

Visao Geral

Ambiente	URL Base	API Key	Descricao
Local	http://localhost:4000/api/v1/central	pk_test_*	Desenvolvimento com simulador
Sandbox	https://sandbox.pixconnect.com.br/api/v1/central	pk_test_*	Testes e homologacao
Producao	https://api.pixconnect.com.br/api/v1/central	pk_live_*	Ambiente produtivo real

Ambiente Local

O ambiente local permite desenvolver e testar sua integracao usando o Nuclea Simulator, que simula todos os servicos da infraestrutura Nuclea sem dependencias externas.

Requisitos

Requisito	Especificacao
Docker	Versao 20.10 ou superior
Docker Compose	Versao 2.0 ou superior
Memoria RAM	Minimo 4GB disponivel
Portas	4000-4010 disponiveis
Sistema	Linux, macOS ou Windows (WSL2)

Instalacao

Clone o repositorio e inicie o ambiente de desenvolvimento:

# Clone o repositorio
git clone https://github.com/playersbet/pixconnect-nuclea.git
cd pixconnect-nuclea

# Inicie todos os servicos
docker-compose up -d

# Verifique se os servicos estao rodando
docker-compose ps

Servicos Disponiveis

O ambiente local executa os seguintes servicos:

Servico	Porta	URL	Descricao
Backend API	4000	http://localhost:4000	API principal FluxiQ NPC
PCR Simulator	4001	http://localhost:4001	Simula a Plataforma Centralizada de Recebiveis
Webhook Receiver	4002	http://localhost:4002	Recebe webhooks para testes
FTP Server	4003	ftp://localhost:4003	Simula FTP Nuclea para arquivos ACMP615
Orchestrator	4005	http://localhost:4005	Orquestra cenarios de teste
Control Panel	4010	http://localhost:4010	Interface web do simulador

Cenarios de Teste

O Nuclea Simulator permite simular diversos cenarios de teste atraves do Orchestrator:

Simular Pagamento de Boleto

# Simula o pagamento de um boleto especifico
curl -X POST "http://localhost:4005/scenarios/payment" \
  -H "Content-Type: application/json" \
  -d '{
    "boleto_id": "uuid-do-boleto",
    "valor_pago": 15000,
    "data_pagamento": "2026-02-03"
  }'

Disparar Ciclo de Liquidacao

# Dispara manualmente um ciclo de liquidacao
curl -X POST "http://localhost:4005/scenarios/settlement" \
  -H "Content-Type: application/json" \
  -d '{
    "cycle_type": "morning",
    "boleto_ids": ["uuid-1", "uuid-2"]
  }'

Simular Erro do PCR

# Simula uma falha na comunicacao com o PCR
curl -X POST "http://localhost:4005/scenarios/pcr-error" \
  -H "Content-Type: application/json" \
  -d '{
    "error_type": "timeout",
    "duration_seconds": 30
  }'

Painel de Controle

Acesse http://localhost:4010 para visualizar:

• Status de todos os servicos
• Boletos registrados no simulador
• Historico de pagamentos simulados
• Logs de comunicacao PCR/FTP
• Triggers manuais para cenarios de teste

Desenvolvimento Local

O ambiente local e ideal para desenvolvimento e depuracao. Use-o para testar novos recursos antes de validar no Sandbox.

Ambiente Sandbox

O Sandbox e um ambiente de homologacao que replica o comportamento de producao, mas com dados de teste e sem impacto financeiro real.

Caracteristicas

• Dados isolados: Boletos e transacoes sao independentes de producao
• Mesma API: Endpoints identicos ao ambiente de producao
• Webhooks reais: Notificacoes enviadas para sua URL de teste
• Ciclos programados: Liquidacao simulada nos mesmos horarios (08:30 e 16:30)
• Sem custo: Requisicoes nao geram cobranca

Limitacoes

Recurso	Limitacao
Requisicoes por minuto	100 RPM
Boletos ativos	Maximo 1.000 simultaneos
Retencao de dados	30 dias
Valor maximo boleto	R$ 10.000,00 (1.000.000 centavos)
Webhooks	Maximo 3 retentativas

Dados de Teste

No Sandbox, utilize os seguintes dados para testes:

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

Dados Ficticios

Nunca use dados reais de clientes no ambiente Sandbox. Utilize apenas dados ficticios para testes.

Acesso ao Sandbox

1. Solicite credenciais de sandbox pelo FluxiQ Portal
2. Receba sua API Key com prefixo pk_test_
3. Configure sua aplicacao para usar a URL do Sandbox
4. Comece a testar!

Ambiente de Producao

O ambiente de producao processa transacoes financeiras reais e esta conectado a infraestrutura Nuclea oficial.

Caracteristicas

• Transacoes reais: Boletos registrados oficialmente no PCR
• Alta disponibilidade: SLA de 99.9%
• Seguranca: Conexao mTLS com certificados Nuclea
• Monitoramento: Alertas e metricas em tempo real
• Suporte: Atendimento prioritario

Checklist Pre-Producao

Antes de migrar para producao, certifique-se de completar todos os itens:

Integracao

• [ ] Testes completos no ambiente Sandbox
• [ ] Tratamento de todos os codigos de erro
• [ ] Implementacao de retentativas com backoff exponencial
• [ ] Validacao de webhooks com assinatura HMAC

Seguranca

• [ ] API Key de producao armazenada de forma segura
• [ ] HTTPS obrigatorio em todas as comunicacoes
• [ ] Logs sem dados sensiveis expostos
• [ ] Webhook endpoint configurado com HTTPS

Operacional

• [ ] Monitoramento de erros configurado
• [ ] Alertas para falhas de integracao
• [ ] Processo de rotacao de chaves documentado
• [ ] Contato de suporte tecnico definido

Compliance

• [ ] Politica de privacidade atualizada
• [ ] Termos de uso revisados
• [ ] LGPD compliance verificado

Solicitar Acesso

Para obter acesso ao ambiente de producao:

1. Complete a homologacao no Sandbox
2. Preencha o formulario de producao no FluxiQ Portal
3. Aguarde a revisao da equipe (ate 5 dias uteis)
4. Receba sua API Key de producao (pk_live_*)
5. Configure o webhook de producao
6. Inicie a operacao!

Ambiente Critico

O ambiente de producao processa transacoes financeiras reais. Teste exaustivamente no Sandbox antes de migrar.

Comparativo de Ambientes

Caracteristica	Local	Sandbox	Producao
Dados	Simulados	Teste	Reais
Nuclea PCR	Simulador	Homologacao	Producao
Disponibilidade	Dev local	99%	99.9%
Rate Limit	Ilimitado	100 RPM	1000 RPM
Webhooks	localhost	URLs publicas	URLs publicas + HTTPS
Suporte	Documentacao	Email	Prioritario
Custo	Gratuito	Gratuito	Por transacao

Proximos Passos

• Autenticacao - Configure sua API Key
• Criar Boleto - Registre seu primeiro boleto
• Webhooks - Receba notificacoes em tempo real