# Health Check

Endpoint to verify service health and configuration status of external components.

## Check Health

Returns detailed system status, including database connectivity and external service configuration.

```
GET /health
```

### Request Example

::: code-group

```bash [cURL]
curl -X GET "https://api.monetarie_npc.com.br/api/v1/central/health" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"
```

```javascript [JavaScript]
const response = await fetch(
  "https://api.monetarie_npc.com.br/api/v1/central/health",
  {
    method: "GET",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
  }
);

const data = await response.json();
console.log(data);
```

```python [Python]
import requests

url = "https://api.monetarie_npc.com.br/api/v1/central/health"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())
```

:::

### Success Response

**Status:** `200 OK`

```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2026-02-15T10:30:00Z",
    "version": "1.0.0",
    "services": {
      "database": {
        "status": "connected",
        "latency_ms": 5
      },
      "pcr_api": {
        "status": "configured",
        "url": "https://api.pcr.nuclea.com.br/***"
      },
      "ftp": {
        "status": "configured",
        "host": "ftp.nuclea.com.br"
      },
      "central_webhook": {
        "status": "configured",
        "url": "https://central.monetarie_npc.com/***"
      }
    }
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

### Response with Issues

**Status:** `503 Service Unavailable`

```json
{
  "success": false,
  "data": {
    "status": "unhealthy",
    "timestamp": "2026-02-15T10:30:00Z",
    "version": "1.0.0",
    "services": {
      "database": {
        "status": "error",
        "error": "connection refused"
      },
      "pcr_api": {
        "status": "not_configured",
        "message": "PCR API URL not set"
      },
      "ftp": {
        "status": "configured",
        "host": "ftp.nuclea.com.br"
      },
      "central_webhook": {
        "status": "not_configured",
        "message": "Central webhook URL not set"
      }
    }
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

---

## Overall System Status

| Status      | HTTP Code | Description                                        |
|-------------|-----------|---------------------------------------------------|
| `healthy`   | 200       | All services functioning correctly                 |
| `degraded`  | 503       | Some services with issues, but operational         |
| `unhealthy` | 503       | Database unavailable or critical service down      |

---

## Service Status

Each service can have one of the following statuses:

| Status           | Description                                        |
|------------------|---------------------------------------------------|
| `connected`      | Service connected and operational (database only)  |
| `configured`     | Service configured correctly                       |
| `not_configured` | Service not configured (missing credentials)       |
| `error`          | Service with connection or configuration error     |

---

## Monitored Services

### Database

Checks connectivity with the PostgreSQL database.

| Field        | Type    | Description                            |
|--------------|---------|----------------------------------------|
| `status`     | string  | `connected` or `error`                 |
| `latency_ms` | integer | Test query latency in ms               |
| `error`      | string  | Error message (when applicable)        |

### PCR API

Checks configuration of Nuclea's PCR API for boleto registration.

| Field     | Type   | Description                              |
|-----------|--------|------------------------------------------|
| `status`  | string | `configured` or `not_configured`         |
| `url`     | string | API URL (partially masked)               |
| `message` | string | Status message (when not configured)     |

::: info Required Configuration
For PCR API to be configured, the following values must be set:
- `pcr.api_url` - API URL
- `pcr.client_id` - OAuth client ID
- `pcr.cert_path` - mTLS certificate path
:::

### FTP

Checks configuration of FTP access for downloading ACMP615 files.

| Field     | Type   | Description                              |
|-----------|--------|------------------------------------------|
| `status`  | string | `configured` or `not_configured`         |
| `host`    | string | FTP server hostname                      |
| `message` | string | Status message (when not configured)     |

::: info Required Configuration
For FTP to be configured, the following values must be set:
- `ftp.host` - Server hostname
- `ftp.user` - Access user
:::

### Central Webhook

Checks webhook configuration for notifying FluxiQ NPC Central.

| Field     | Type   | Description                              |
|-----------|--------|------------------------------------------|
| `status`  | string | `configured` or `not_configured`         |
| `url`     | string | Webhook URL (partially masked)           |
| `message` | string | Status message (when not configured)     |

::: info Required Configuration
For webhook to be configured, the following values must be set:
- `central.webhook_url` - Webhook endpoint URL
- `central.api_key` - Authentication API Key
:::

---

## Monitoring Usage

The health check endpoint is ideal for:

- **Load balancers**: Check if the instance is healthy
- **Kubernetes**: Readiness and liveness probes
- **Alerts**: Monitor service availability
- **Dashboards**: Display real-time status

### Kubernetes Probe Example

```yaml
livenessProbe:
  httpGet:
    path: /api/v1/central/health
    port: 4000
    httpHeaders:
      - name: X-API-Key
        value: $(API_KEY)
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /api/v1/central/health
    port: 4000
    httpHeaders:
      - name: X-API-Key
        value: $(API_KEY)
  initialDelaySeconds: 5
  periodSeconds: 5
```

## Next Steps

- [Boletos](/en/api/boletos) - Create and manage boletos
- [Settlements](/en/api/settlements) - Process settlement files
- [Error Codes](/en/reference/errors) - Complete error reference