care-api/specs/001-care-api-sistema/quickstart.md

Quickstart Guide: Care API System

Feature: Care API - Sistema de gestão de cuidados de saúde
Date: 2025-09-12
Prerequisites: WordPress + KiviCare plugin installed

Quick Setup

1. Plugin Installation

# Clone/download plugin to WordPress plugins directory
wp plugin activate kivicare-api

# Verify KiviCare dependency
wp plugin is-active kivicare-clinic-patient-management-system

2. Authentication Setup

# Test JWT authentication
curl -X POST http://your-site.local/wp-json/kivicare/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"doctor_user","password":"password"}'

# Expected response:
# {"token":"eyJ0eXAiOiJKV1QiLCJhbGc...","user_id":123,"role":"doctor"}

3. Basic API Testing

Create a Patient

export TOKEN="your_jwt_token_here"

curl -X POST http://your-site.local/wp-json/kivicare/v1/patients \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "João Silva",
    "user_email": "joao@example.com",
    "clinic_id": 1,
    "phone": "+351912345678"
  }'

Schedule an Appointment

curl -X POST http://your-site.local/wp-json/kivicare/v1/appointments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_start_date": "2025-01-15",
    "appointment_start_time": "14:30:00",
    "appointment_end_date": "2025-01-15",
    "appointment_end_time": "15:00:00",
    "doctor_id": 2,
    "patient_id": 123,
    "clinic_id": 1,
    "visit_type": "consultation",
    "description": "Consulta de rotina"
  }'

Create Medical Encounter

curl -X POST http://your-site.local/wp-json/kivicare/v1/encounters \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_id": 456,
    "description": "Patient presents with mild fever. Diagnosed with common cold. Prescribed rest and medication.",
    "status": 1
  }'

Add Prescription

curl -X POST http://your-site.local/wp-json/kivicare/v1/encounters/789/prescriptions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Paracetamol 500mg",
    "frequency": "Every 8 hours",
    "duration": "7 days",
    "instruction": "Take with water after meals"
  }'

User Story Validation

Story 1: Doctor Creates Patient Record

# Test: Create patient → Verify in database
curl -X POST .../patients -d '{"display_name":"Test Patient","user_email":"test@example.com","clinic_id":1}'
# Expected: Patient ID returned, entries in wp_users and wp_kc_patient_clinic_mappings

# Validate:
wp db query "SELECT u.ID, u.display_name, pcm.clinic_id FROM wp_users u 
             JOIN wp_kc_patient_clinic_mappings pcm ON u.ID = pcm.patient_id 
             WHERE u.user_email = 'test@example.com'"

Story 2: Doctor Creates Encounter with Prescriptions

# Test: Create encounter → Add prescriptions → Verify linkage
curl -X POST .../encounters -d '{"appointment_id":123,"description":"Test encounter"}'
curl -X POST .../encounters/456/prescriptions -d '{"name":"Test Med","frequency":"Daily","duration":"5 days"}'

# Validate:
wp db query "SELECT e.id, e.description, p.name, p.frequency FROM wp_kc_patient_encounters e
             JOIN wp_kc_prescription p ON e.id = p.encounter_id WHERE e.id = 456"

Story 3: Multi-Doctor Clinic Data Access

# Test: Doctor A creates encounter → Doctor B retrieves patient data
# (Using different JWT tokens for each doctor)

# Doctor A creates encounter
curl -X POST .../encounters -H "Authorization: Bearer $DOCTOR_A_TOKEN" -d '{...}'

# Doctor B retrieves patient encounters
curl -X GET .../patients/123/encounters -H "Authorization: Bearer $DOCTOR_B_TOKEN"
# Expected: Both doctors see the same encounter data (same clinic)

Story 4: Automatic Billing Generation

# Test: Complete encounter → Verify bill creation
curl -X PUT .../encounters/456 -d '{"status":1,"description":"Completed consultation"}'

# Validate billing:
wp db query "SELECT b.id, b.encounter_id, b.total_amount FROM wp_kc_bills b 
             WHERE b.encounter_id = 456"
# Expected: Bill record automatically created

Story 5: Role-Based Access Control

# Test receptionist access
curl -X GET .../appointments -H "Authorization: Bearer $RECEPTIONIST_TOKEN"
# Expected: Success - receptionists can manage appointments

curl -X GET .../encounters -H "Authorization: Bearer $RECEPTIONIST_TOKEN"  
# Expected: Error 403 - receptionists cannot access medical data

curl -X GET .../encounters -H "Authorization: Bearer $PATIENT_TOKEN"
# Expected: Only own encounters returned

Performance Validation

Response Time Tests

# Test appointment listing performance
time curl -X GET "http://your-site.local/wp-json/kivicare/v1/appointments?doctor_id=2&date=2025-01-15" \
  -H "Authorization: Bearer $TOKEN"
# Target: < 500ms response time

# Test patient encounter history
time curl -X GET "http://your-site.local/wp-json/kivicare/v1/patients/123/encounters" \
  -H "Authorization: Bearer $TOKEN"
# Target: < 500ms for 100+ encounters

Concurrent User Test

# Simulate 10 concurrent appointment creations
for i in {1..10}; do
  curl -X POST .../appointments -H "Authorization: Bearer $TOKEN" -d '{...}' &
done
wait
# Expected: All succeed without conflicts

Error Handling Validation

Authentication Errors

# Test invalid token
curl -X GET .../patients -H "Authorization: Bearer invalid_token"
# Expected: 401 {"code":"rest_forbidden","message":"..."}

# Test expired token
curl -X GET .../patients -H "Authorization: Bearer expired_token"  
# Expected: 401 with token expiry message

Data Validation Errors

# Test invalid patient data
curl -X POST .../patients -d '{"user_email":"invalid-email","clinic_id":"not_a_number"}'
# Expected: 400 {"code":"rest_invalid_param","message":"Validation failed","data":{...}}

# Test conflicting appointment
curl -X POST .../appointments -d '{"doctor_id":2,"appointment_start_date":"2025-01-15","appointment_start_time":"14:30:00",...}'
curl -X POST .../appointments -d '{"doctor_id":2,"appointment_start_date":"2025-01-15","appointment_start_time":"14:45:00",...}'
# Expected: Second request fails with time conflict error

Database Integrity Tests

# Test foreign key constraints
curl -X POST .../encounters -d '{"appointment_id":99999,"description":"Test"}'
# Expected: 400 error - invalid appointment_id

# Test clinic isolation
curl -X GET .../patients?clinic_id=2 -H "Authorization: Bearer $CLINIC_1_DOCTOR_TOKEN"
# Expected: 403 error - cannot access other clinic's data

Success Criteria Checklist

• All REST endpoints respond with correct HTTP status codes
• JWT authentication works for all user roles
• Role-based permissions enforced correctly
• Database transactions maintain referential integrity
• API response times < 500ms for standard operations
• Error responses include helpful debugging information
• Concurrent operations handle conflicts gracefully
• All user stories validate successfully
• No data corruption in existing KiviCare tables
• Plugin activation/deactivation works without errors

Troubleshooting

Common Issues

1. Plugin Activation Fails: Verify KiviCare plugin is active first
2. JWT Token Invalid: Check WordPress JWT configuration
3. Database Errors: Verify WordPress database permissions
4. API 404 Errors: Flush WordPress rewrite rules
5. CORS Issues: Configure WordPress CORS headers for cross-origin requests

Debug Mode

# Enable WordPress debug mode
wp config set WP_DEBUG true
wp config set WP_DEBUG_LOG true

# Check error logs
tail -f wp-content/debug.log

---

Quickstart Complete: Ready for integration testing