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

cURL

curl -X GET "https://api.pixconnect.com.br/api/v1/central/health" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch(
  "https://api.pixconnect.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

import requests

url = "https://api.pixconnect.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

{
  "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.pixconnect.com/***"
      }
    }
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Response with Issues

Status: 503 Service Unavailable

{
  "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)

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)

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)

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

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 - Create and manage boletos
• Settlements - Process settlement files
• Error Codes - Complete error reference