# Environments

The Monetarie 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.monetarie_npc.com.br/api/v1/central`| `pk_test_*`   | Testing and staging              |
| Production  | `https://api.monetarie_npc.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:

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

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

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

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

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

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

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

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

::: danger 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](/en/authentication) - Configure your API Key
- [Create Boleto](/en/api/boletos) - Register your first boleto
- [Webhooks](/en/webhooks/) - Receive real-time notifications