Health Check

Endpoint para verificar a saude do servico e o status de configuracao dos componentes externos.

Verificar Saude

Retorna o status detalhado do sistema, incluindo conectividade com banco de dados e configuracao de servicos externos.

GET /health

Exemplo de Requisicao

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())

Resposta de Sucesso

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"
  }
}

Resposta com Problemas

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"
  }
}

---

Status Geral do Sistema

Status	HTTP Code	Descricao
healthy	200	Todos os servicos funcionando corretamente
degraded	503	Alguns servicos com problemas, mas operacional
unhealthy	503	Banco de dados indisponivel ou servico critico fora

---

Status dos Servicos

Cada servico pode ter um dos seguintes status:

Status	Descricao
connected	Servico conectado e operacional (apenas database)
configured	Servico configurado corretamente
not_configured	Servico nao configurado (credenciais ausentes)
error	Servico com erro de conexao ou configuracao

---

Servicos Monitorados

Database

Verifica conectividade com o banco de dados PostgreSQL.

Campo	Tipo	Descricao
status	string	connected ou error
latency_ms	integer	Latencia da query de teste em ms
error	string	Mensagem de erro (quando aplicavel)

PCR API

Verifica configuracao da API PCR da Nuclea para registro de boletos.

Campo	Tipo	Descricao
status	string	configured ou not_configured
url	string	URL da API (parcialmente mascarada)
message	string	Mensagem de status (quando nao configurado)

Configuracao Necessaria

Para o PCR API estar configurado, os seguintes valores devem estar preenchidos:

• pcr.api_url - URL da API
• pcr.client_id - ID do cliente OAuth
• pcr.cert_path - Caminho do certificado mTLS

FTP

Verifica configuracao do acesso FTP para download de arquivos ACMP615.

Campo	Tipo	Descricao
status	string	configured ou not_configured
host	string	Hostname do servidor FTP
message	string	Mensagem de status (quando nao configurado)

Configuracao Necessaria

Para o FTP estar configurado, os seguintes valores devem estar preenchidos:

• ftp.host - Hostname do servidor
• ftp.user - Usuario de acesso

Central Webhook

Verifica configuracao do webhook para notificar o FluxiQ NPC Central.

Campo	Tipo	Descricao
status	string	configured ou not_configured
url	string	URL do webhook (parcialmente mascarada)
message	string	Mensagem de status (quando nao configurado)

Configuracao Necessaria

Para o webhook estar configurado, os seguintes valores devem estar preenchidos:

• central.webhook_url - URL do endpoint de webhook
• central.api_key - API Key para autenticacao

---

Uso em Monitoramento

O endpoint de health check e ideal para:

• Load balancers: Verificar se a instancia esta saudavel
• Kubernetes: Readiness e liveness probes
• Alertas: Monitorar disponibilidade do servico
• Dashboards: Exibir status em tempo real

Exemplo de Probe Kubernetes

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

Proximos Passos

• Boletos - Criar e gerenciar boletos
• Liquidacao - Processar arquivos de liquidacao
• Codigos de Erro - Referencia completa de erros