# Ambientes

A API Monetarie 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.monetarie_npc.com.br/api/v1/central`| `pk_test_*`   | Testes e homologacao             |
| Producao   | `https://api.monetarie_npc.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:

```bash
# Clone o repositorio
git clone https://github.com/playersbet/monetarie-npc.git
cd monetarie-npc

# 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 Monetarie 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

```bash
# 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

```bash
# 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

```bash
# 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

::: tip 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:

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

::: warning 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 [Monetarie Portal](https://npcadmin-dev.fluxiq.com.br)
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 [Monetarie Portal](https://npcadmin-dev.fluxiq.com.br)
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!

::: danger 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](/authentication) - Configure sua API Key
- [Criar Boleto](/api/boletos) - Registre seu primeiro boleto
- [Webhooks](/webhooks/) - Receba notificacoes em tempo real