care-api/QUICKSTART.md

KiviCare API - Quickstart Guide

Plugin WordPress completo para gestão de clínicas médicas via REST API

---

🚀 INSTALAÇÃO RÁPIDA

1. Pré-requisitos

• WordPress 6.0+
• PHP 8.1+
• MySQL 5.7+ / MariaDB 10.3+
• Plugin KiviCare base instalado e ativo
• Memoria: 512MB+ (recomendado: 1GB+)

2. Instalação

# 1. Upload dos ficheiros
wp-content/plugins/kivicare-api/

# 2. Ativar o plugin
wp plugin activate kivicare-api

# 3. Verificar dependências
wp plugin list --field=name --status=active | grep kivicare

3. Configuração Inicial

# Configurar permissões (wp-config.php)
define('KIVICARE_API_VERSION', '1.0.0');
define('KIVICARE_API_DEBUG', true);  // Apenas desenvolvimento
define('KIVICARE_API_CACHE_TTL', 3600);
define('KIVICARE_JWT_SECRET', 'your-secure-secret-key-here');

---

⚡ TESTE RÁPIDO DE FUNCIONAMENTO

1. Verificação do Sistema

# Teste de saúde da API
curl -X GET http://yoursite.com/wp-json/kivicare/v1/system/health

# Resposta esperada:
{
  "success": true,
  "message": "API is healthy",
  "data": {
    "status": "operational",
    "version": "1.0.0",
    "database": "connected",
    "cache": "active"
  }
}

2. Autenticação

# Login e obtenção de token JWT
curl -X POST http://yoursite.com/wp-json/kivicare/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your_password"
  }'

# Resposta esperada:
{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "user": {
      "id": 1,
      "user_type": "admin",
      "full_name": "Administrator"
    }
  }
}

3. Teste de Endpoints Principais

# Listar clínicas (usar token obtido)
curl -X GET http://yoursite.com/wp-json/kivicare/v1/clinics \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

# Listar pacientes
curl -X GET http://yoursite.com/wp-json/kivicare/v1/patients \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

# Listar médicos  
curl -X GET http://yoursite.com/wp-json/kivicare/v1/doctors \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

---

📊 VALIDAÇÃO COMPLETA DO SISTEMA

Executar Suite de Testes Completa

// No WordPress Admin ou via WP-CLI
$test_results = \KiviCare_API\Testing\Unit_Test_Suite::run_all_tests(array(
    'verbose' => true,
    'timeout' => 60
));

print_r($test_results['summary']);

Verificação Manual dos Componentes

✅ 1. Autenticação & Segurança

# Teste sem token (deve falhar)
curl -X GET http://yoursite.com/wp-json/kivicare/v1/patients
# Expected: 401 Unauthorized

# Teste com token inválido (deve falhar) 
curl -X GET http://yoursite.com/wp-json/kivicare/v1/patients \
  -H "Authorization: Bearer invalid_token"
# Expected: 401 Invalid token

# Teste com token válido (deve passar)
curl -X GET http://yoursite.com/wp-json/kivicare/v1/patients \
  -H "Authorization: Bearer VALID_TOKEN"
# Expected: 200 OK with data

✅ 2. CRUD Operations

# Criar paciente
curl -X POST http://yoursite.com/wp-json/kivicare/v1/patients \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "João",
    "last_name": "Silva", 
    "user_email": "joao@example.com",
    "clinic_id": 1
  }'

# Obter paciente por ID
curl -X GET http://yoursite.com/wp-json/kivicare/v1/patients/123 \
  -H "Authorization: Bearer TOKEN"

# Atualizar paciente
curl -X PUT http://yoursite.com/wp-json/kivicare/v1/patients/123 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "João Pedro"}'

✅ 3. Agendamentos & Consultas

# Criar agendamento
curl -X POST http://yoursite.com/wp-json/kivicare/v1/appointments \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": 123,
    "doctor_id": 456,
    "clinic_id": 1,
    "appointment_start_date": "2025-01-15",
    "appointment_start_time": "14:30:00"
  }'

# Verificar slots disponíveis
curl -X GET "http://yoursite.com/wp-json/kivicare/v1/appointments/available-slots?doctor_id=456&date=2025-01-15" \
  -H "Authorization: Bearer TOKEN"

✅ 4. Consultas Médicas & Prescrições

# Criar encounter
curl -X POST http://yoursite.com/wp-json/kivicare/v1/encounters \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": 123,
    "doctor_id": 456,
    "clinic_id": 1,
    "description": "Consulta de rotina"
  }'

# Adicionar prescrição
curl -X POST http://yoursite.com/wp-json/kivicare/v1/prescriptions \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "encounter_id": 789,
    "patient_id": 123,
    "medication_name": "Paracetamol 500mg",
    "frequency": "8/8h",
    "duration": "7 dias"
  }'

✅ 5. Faturação

# Criar fatura
curl -X POST http://yoursite.com/wp-json/kivicare/v1/bills \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "encounter_id": 789,
    "clinic_id": 1,
    "title": "Consulta Médica",
    "total_amount": 50.00
  }'

---

🔧 TROUBLESHOOTING

Problemas Comuns

❌ Plugin não ativa

# Verificar dependências
wp plugin list --status=must-use,active | grep kivicare

# Verificar logs
tail -f /wp-content/debug.log | grep kivicare

❌ Erro 500 em endpoints

# Verificar permissões de ficheiros
find /wp-content/plugins/kivicare-api -type f -exec chmod 644 {} \;
find /wp-content/plugins/kivicare-api -type d -exec chmod 755 {} \;

# Verificar memory limit
wp config get WP_MEMORY_LIMIT

❌ Problemas de autenticação

# Verificar .htaccess (Apache)
# Adicionar se necessário:
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

# Verificar configuração Nginx
# location ~ \.php$ {
#     fastcgi_param HTTP_AUTHORIZATION $http_authorization;
# }

❌ Database errors

# Verificar tabelas KiviCare
wp db query "SHOW TABLES LIKE '%kc_%'"

# Verificar conexões
wp db check

---

📈 MONITORIZAÇÃO & PERFORMANCE

Métricas em Tempo Real

# Performance da API  
curl -X GET http://yoursite.com/wp-json/kivicare/v1/system/performance \
  -H "Authorization: Bearer TOKEN"

# Estatísticas de cache
curl -X GET http://yoursite.com/wp-json/kivicare/v1/system/cache-stats \
  -H "Authorization: Bearer TOKEN"

Logs Importantes

# Logs da API
tail -f /wp-content/uploads/kivicare-api-logs/api-requests.log

# Logs de performance
tail -f /wp-content/uploads/kivicare-api-logs/performance.log

# Logs de segurança  
tail -f /wp-content/uploads/kivicare-api-logs/security.log

---

🎯 ENDPOINTS DISPONÍVEIS

Authentication

• POST /auth/login - Login utilizador
• POST /auth/refresh - Refresh token
• POST /auth/logout - Logout

Clínicas

• GET /clinics - Listar clínicas
• POST /clinics - Criar clínica
• GET /clinics/{id} - Obter clínica
• PUT /clinics/{id} - Atualizar clínica

Pacientes

• GET /patients - Listar pacientes
• POST /patients - Criar paciente
• GET /patients/{id} - Obter paciente
• PUT /patients/{id} - Atualizar paciente
• GET /patients/{id}/history - Histórico médico

Médicos

• GET /doctors - Listar médicos
• GET /doctors/{id} - Obter médico
• GET /doctors/{id}/schedule - Horário do médico
• GET /doctors/{id}/appointments - Agendamentos do médico

Agendamentos

• GET /appointments - Listar agendamentos
• POST /appointments - Criar agendamento
• GET /appointments/{id} - Obter agendamento
• PUT /appointments/{id} - Atualizar agendamento
• DELETE /appointments/{id} - Cancelar agendamento
• GET /appointments/available-slots - Slots disponíveis

Consultas Médicas

• GET /encounters - Listar encounters
• POST /encounters - Criar encounter
• GET /encounters/{id} - Obter encounter
• PUT /encounters/{id} - Atualizar encounter

Prescrições

• GET /prescriptions - Listar prescrições
• POST /prescriptions - Criar prescrição
• PUT /prescriptions/{id} - Atualizar prescrição
• GET /encounters/{id}/prescriptions - Prescrições do encounter

Faturação

• GET /bills - Listar faturas
• POST /bills - Criar fatura
• GET /bills/{id} - Obter fatura
• PUT /bills/{id} - Atualizar fatura
• POST /bills/{id}/payment - Registar pagamento

Relatórios

• GET /reports/appointments - Relatório de agendamentos
• GET /reports/revenue - Relatório de receita
• GET /reports/patients - Relatório de pacientes
• GET /reports/doctors - Relatório de médicos

Sistema

• GET /system/health - Estado da API
• GET /system/version - Versão da API
• GET /system/performance - Métricas de performance

---

📞 SUPORTE

Logs & Debug

# Ativar modo debug (wp-config.php)
define('KIVICARE_API_DEBUG', true);
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

Contactos

• Desenvolvimento Técnico: Descomplicar® Crescimento Digital
• Website: https://descomplicar.pt
• Documentação Completa: Ver SPEC_CARE_API.md

---

✅ CHECKLIST FINAL

• Plugin KiviCare base instalado e ativo
• Plugin KiviCare API ativado com sucesso
• Endpoint de saúde responde corretamente
• Autenticação JWT funcional
• Endpoints principais testados
• Logs a funcionar corretamente
• Cache ativo e otimizado
• Testes unitários executados com sucesso
• Monitorização de performance ativa
• Backup da base de dados realizado

🎉 PARABÉNS! A KiviCare API está 100% operacional!

---

Desenvolvido com ❤️ pela Descomplicar® Crescimento Digital
Sistema completo de gestão de clínicas médicas via REST API